[Topic]

RTS

Support for real-time scheduling (RTS) is currently available for the following Lisp implementations:

• Gauche Scheme
• OpenMCL
• SBCL

To load RTS do:

(use-system :rts)

Loading RTS enables the following set of functions:

• rts
• rts-pause
• rts-continue
• rts-hush
• rts-stop
• A set of non-consing replacements for some CM runtime tools.

Implementation

rts is a real-time musical process scheduler based on POSIX threads that is source compatible with CM's non-real time events scheduler. Source compatible means that the exact same process definition can run in both environments. The most visible differences between the two schedulers are:

• the REPL is not blocked by rts while the scheduler is running.
• rts continues to run until it is explicitly stopped, even if its queue is empty.
• sprout can be called interactively from the REPL or from a receive hook to add objects to rts.
• Object time stamps are ignored during output. That is, setting the time of an object to a (now) value has no effect on the time that the object is actually output: it is always output at the current time plus any latency in the output stream.
• Values returned by now under RTS reflect the current real time in seconds, milliseconds or microseconds, depending on the time format specified to rts.

To Cons or Not To Cons

Although process definitions do not have to be changed to run under rts, real time scheduling does place timing demands on software that non-real time scheduling does not. To get maximum accuracy process definitions should avoid unnecessary consing -- creating lots of temporary data stuctures (lists, objects, vectors, strings etc), performing floating point arithmetic, or being otherwise wasteful and inefficient. As an alternative, consider running the scheduler in millisecond time format, reusing one event rather than creating new events for each output statement and using integer math. If you are working with MIDI, consider using low-level, consless MIDI messages in place of midi objects.

Non-consing Tools

Some operations in Lisp are inherently "consy", for example non-destructive operations on lists or performing math or random selection with floating point values. In order to facilite non-consing process definition, the RTS system provides non-consing replacements for a subset of CM's runtime functions. Obviously, these replacements provide only limited functionalty, for example they only return integer values.

[Function]

(rts:rhythm ticks [tempo])

Returns rhythmic value of ticks and tempo as integer milliseconds. The value of ticks can be an integer or symbol. Integer ticks are interpreted relative to a quarter-note worth 480 ticks, so 240 is one eighth, 960 one half, 320 one triplet quarter, 900 is a quarter tied to a doubly-dotted eighth and so on. If ticks is a symbol it can be one of: w h q e s t x (whole, half, quarter, eighth, sixteenth, thirty-second, sixty-fourth), the triplet variants: tw th tq te ts tt tx, the dotted variants: w. h. q. e. s. t. x. and the doubly-dotted variants.

[Function]

(rts:rescale x x1 x2 y1 y2)

Rescales an integer x that lies between integers x1 and x2 to lie proportionally between integers y1 and y2. Rescaling is essentially linear interpolation along a single line segment.

[Function]

(rts:interpl x list)

Performs integer linear interpolation of x in a list of integer coordinates (x1 y1 x2 y2 ... xn yn) where x1 ... xn must be in monotonically increasing order and y integers are unordered.

[Function]

(rts:random-seed seed)

Seeds random selection with integer seed. The Common Lisp function (get-universal-time) can be used to provide continuously new seed values.

[Function]

(rts:beween lb ub [avoid])

Returns an integer value equal to or greater than the integer lb but less than integer ub. If avoid is provided the value returned by the function will not be equal to it.

[Function]

(rts:odds pct [true] [false])

Returns the true value if a random choice between 0 and 100 is less than pct, which must also lie between 0 and 100 and where 0 means impossiblity and 100 is complete certainty, otherwise returns false. If true or false are not specfied they default to boolean true and false, respectively.

[Function]

(rts:drunk num width)

Returns integer num+width or num-width based on a random choice.

[Function]

(rts:shuffle list [start] [end])

Destructively modifies list by scrambling the order of elements between the start and end positions, which default to 0 and length of list, respectively.

See also:

• rts [Function]
• set-receiver! [Function]