4 The RT compiler

The RT compiler works by translating the Scheme-like input-code into s-expression based C-code, which is further translated into normal C-code by the eval-c macro. The eval-c macro is found in the file eval-c.scm. eval-c does also the compiling and linking by calling gcc.

4.1 Features

Compilation of simple lisp functions into machine code.
All compiled code should normally be hard real time safe.
The compiled code should be so fast, that theres normally nothing to gain by writing a function in C. At least, thats the plan, its currently not always true, although not far from.

4.2 Macros and functions to compile and run rt-functions

(rt-compile ...)

Macro

      (define a (rt-compile (lambda (b c)
			       (* b c))))

(rt-c ...)

Macro

Same as rt-compile

(rt-funcall ...)

Macro

           (rt-funcall a 2 3)
           => 6.0

(rt-func ...)

Macro

           (define a (rt-func (lambda (b c)
				(* b c))))
           (a 2 3)
           => 6.0

(rt-safety ...)

Setter function

rt-safety is a setter function. If set to 0, no runtime error checking is performed. Its safe to set (rt-safety) to 0 if you don't get any ``RT RUNTIME ERROR'' error messages to stderr when running your function, and you are sure thats impossible to happen. On the other hand, if you do see an ``RT RUNTIME ERROR'' message printed to stderr when running your function, theres a good chance you will lock up your machine by setting (rt-safety) to 0.

For operations on lists, pairs and vectors, this could have an impact on the performance. But, generally, don't expect to see a big improvement in the performance by setting it to 0.

(<rt> ...)

Macro

Creates a subclass of <realtime> :

       (define a (<rt> (lambda ()
		         (out (oscil osc)))))

(<rt-play> ...)

Macro

Creates a subclass of <realtime> :

        (<rt-play> (lambda ()
		     (out (- (random 1.8) 0.9))))
        [white noise is being generated]

        (<rt-play> 1
		   (lambda ()
		     (out (- (random 1.8) 0.9))))
        [one second later, white noise is being generated]

        (<rt-play> 1 10
		   (lambda ()
		     (out (- (random 1.8) 0.9))))
        [one second later, white noise is being generated for ten seconds]

<rt-play> is a macro that calls <rt>.

(<rt-play-abs> ...)

Macro
Same behavior as rt-play, except that the start-time is absolute time: (<rt-play> 1 func) is the same as (<rt-play-abs> (+ 1 (rte-time)) func)

(rt-clear-cache!)

Function
Compiled rt-functions are cached into memory (currently not to disk). (rt-clear-cache!) clears the cache.

4.3 The Ťrealtimeť class

The <realtime> class provides the following methods:

(play-abs [start] [duration]) Method
Starts playing at the absolute time start, stopping at the absolute time (+ start duration). Default value for start is the current time. If duration is not specified, a stop command is not scheduled.
(stop-abs [end]) Method
Stops playing at the absolute time end. Default value for end is the current time.
(play [start] [duration]) Method
Starts playing start seconds into the future from the current time, stopping at (+ start duration) seconds into the future from the current time. Default value for start 0. If end is not specified, a stop command is not scheduled.
(stop [end]) Method
Stops playing end seconds into the future from the current time. Default value for end is 0

4.4 Various

For define-rt, I have the following lines in my .emacs file:

  (font-lock-add-keywords
   'scheme-mode
   '(("(\\(define-rt\\)\\>\\s-*(?\\(\\sw+\\)?"
      (1 font-lock-keyword-face)
      (2 (cond ((match-beginning 1) font-lock-function-name-face)
  	     ((match-beginning 2) font-lock-variable-name-face)
	     (t font-lock-type-face))
         nil t))))

The definstrument-macro is implemented so that any rt-code is compiled when the instruments definition is being evaluated, and not when being called.
To extend the RT language with your own functions written in C, look at how the <rt-func> function works in rt-compiler.scm. The rt-renamefunc macro may also be of large use. Beware though that the API for <rt-func> and rt-renamefunc might still change.