Time and Threading

Functions
function	spawn (fun,...)
	Launch a function in a separate parallel execution thread (deferred execution)
function	run (fun,...)
	launch a function in a separate parallel execution thread.
function	waitBeat (beat)
	Suspend execution for a tempo-synchronized duration in beats.
function	wait (ms)
	suspend the current thread callback execution for the given number of samples.
function	waitForRelease ()
	suspend the current thread callback execution until the note that created this callback is released either by the pedal or by a note off.

Detailed Description

Time manipulation, thread control, and synchronization functions.

Functions for controlling script execution flow, creating parallel threads, and managing timing with sample-accurate precision. All timing operations maintain real-time guarantees while providing musical timing capabilities.

Thread Control:

• spawn - Create new thread (deferred execution)
• run - Create new thread (immediate execution)
• wait - Suspend thread for milliseconds
• waitBeat - Suspend thread for musical beats
• waitForRelease - Suspend until note is released

Time Queries:

• getTime() - Current time in milliseconds

Synchronization:

• isNoteHeld() - Check if triggering note is still held

Note

All callbacks run as cooperative threads. Always include wait() or waitBeat() in loops to yield control and prevent blocking.

See also

Threading and Timing, Math Conversions, Event Callbacks

Function Documentation

run()

function run	(	fun	,
			... )

launch a function in a separate parallel execution thread.

execute it immediately, then goes back to the caller thread once the thread waits for something

Parameters

fun	function to launch
...	variable number of arguments to pass to the function

function print_n_times(n, waitingTime)
    for i=1,n do
        print("time", getTime(), "print_n_times", i)
        wait(waitingTime)
    end
end
 
run(print_n_times, 3, 1000) -- trigger execution of print_n_times with arguments 3 and 1000, run executes print_n_times immediately until the first wait
 
print("time", getTime(), "end of run") -- this will be executed after the first iteration of print_n_times, but both will happen at the same virtual time

See also

spawn, wait, waitBeat

spawn()

function spawn	(	fun	,
			... )

Launch a function in a separate parallel execution thread (deferred execution)

Creates and schedules a new thread to execute the specified function. The execution is deferred until the end of the current "instant" (the current callback cycle). This means spawn() returns immediately to the caller, and the spawned function will begin execution after all code in the current instant has completed.

This is useful for creating fire-and-forget background tasks that run independently of the calling code without blocking the current execution flow.

Parameters

fun	The function to execute in a new thread
...	Variable number of arguments to pass to the function

Execution Timing:

• spawn() returns immediately without executing the function
• The spawned function begins execution at the end of the current instant
• Both the calling code and spawned function share the same virtual time

Basic Example:

function print_n_times(n, waitingTime)
    for i=1,n do
        print("time", getTime(), "print_n_times", i)
        wait(waitingTime)
    end
end
 
spawn(print_n_times, 3, 1000) -- Schedule execution with arguments 3 and 1000
 
print("time", getTime(), "end of spawn") -- This executes BEFORE print_n_times starts,
                                         -- but both share the same virtual timestamp

Practical Example - Delayed Arpeggiator:

function onNote(e)
    -- Play the root note immediately
    postEvent(e)
 
    -- Spawn an arpeggio that plays after this callback completes
    spawn(function()
        for i = 1, 4 do
            playNote(e.note + (i * 7), e.velocity, 200) -- Fifth intervals
            wait(250)
        end
    end)
 
    -- This callback completes immediately, arpeggio runs independently
end

Note

The spawned function runs in its own thread context and can use thread-blocking functions like wait(), waitBeat(), and waitForRelease().

See also

run, wait, waitBeat, waitForRelease

wait()

function wait

(

ms

)

suspend the current thread callback execution for the given number of samples.

It allows other thread callbacks to be resumed in between. The thread scheduler is sample-accurate.

Parameters

ms	the number of milliseconds to wait, has to be greater than 0

See also

waitForRelease, waitBeat

waitBeat()

function waitBeat

(

beat

)

Suspend execution for a tempo-synchronized duration in beats.

Suspends the current thread callback execution for the specified number of beats. This function provides musical time-based delays that automatically adjust to tempo changes. It internally converts the beat duration to milliseconds using the current tempo before calling wait().

Parameters

beat	The number of beats to wait (must be greater than 0). Can be fractional for subdivisions (e.g., 0.25 for a sixteenth note)

Example:

-- Wait for one quarter note
waitBeat(1.0)
 
-- Wait for a whole note (4 beats)
waitBeat(4.0)
 
-- Wait for an eighth note
waitBeat(0.5)

See also

wait, waitForRelease, waitSecond, beat2ms

waitForRelease()

function waitForRelease

(

)

suspend the current thread callback execution until the note that created this callback is released either by the pedal or by a note off.

See also

wait, waitSecond, waitBeat