uvi-script
Musical event scripting with Lua
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 milliseconds.
 
function waitForRelease ()
 suspend the current thread callback execution until the note that created this callback is released by its 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:

Time Queries:

Synchronization:

Note
Event callbacks run as cooperative threads (onSave and onLoad excepted, they are synchronous calls). 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
funfunction 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
function getTime()
get the number of milliseconds elapsed since the script engine start.
Definition api.lua:845
function run(fun,...)
launch a function in a separate parallel execution thread.
Definition api.lua:1364
function wait(ms)
suspend the current thread callback execution for the given number of milliseconds.
Definition wrapper.lua:39
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
funThe 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
function spawn(fun,...)
Launch a function in a separate parallel execution thread (deferred execution)
Definition api.lua:1338
Practical Example - Delayed Arpeggiator:
function onNote(e)
-- Play the root note immediately
-- 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
void onNote(table e)
event callback that will receive all incoming note-on events if defined.
function playNote(note, vel, duration, layer, channel, input, vol, pan, tune, slice, oscIndex, dim1, dim2)
helper function to generate a note event.
Definition api.lua:1089
function postEvent(e, delta)
send a script event back to the script engine event queue.
Definition api.lua:959
Note
The spawned function runs in its own thread context and can use thread-blocking functions like wait() and waitBeat(). waitForRelease() and isNoteHeld() only act on the thread the note callback itself runs in, so a spawned function cannot use them to follow the note that started it.
See also
run, wait, waitBeat, waitForRelease

◆ wait()

function wait ( ms )

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

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

Parameters
msthe 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. The beat duration is converted to milliseconds once, using the tempo at the time of the call, before calling wait(): a tempo change during the wait does not shorten or lengthen it.

Parameters
beatThe 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
-- Wait for a whole note (4 beats)
-- Wait for an eighth note
function waitBeat(beat)
Suspend execution for a tempo-synchronized duration in beats.
Definition conversions.lua:142
See also
wait, waitForRelease, beat2ms

◆ waitForRelease()

function waitForRelease ( )

suspend the current thread callback execution until the note that created this callback is released by its note off.

The sustain pedal is not taken into account: the thread resumes on the note off even while CC 64 holds the sound. When the current callback was not started by a NoteOn (onController(), a function launched with spawn() or run()...) it returns immediately.

See also
wait, waitBeat