wait()

Suspends / pauses execution of the current event handler instance for the requested amount of microseconds. The paused event handler instance can also be resumed before the requested amount times elapsed by calling stop_wait() from another event handler instance.

The duration-us argument must neither be negative nor zero, otherwise script execution will be aborted, because this is a common indication of bugs in scripts which could potentially lead to real-time instability or worse scenarios otherwise.

If the event handler instance's built-in variable $NKSP_IGNORE_WAIT reflects 1 then all calls to wait() will be ignored. This might for example be the case when stop_wait() with 1 being passed to the 2nd argument of that function.

Function Prototype

wait(duration-us)

Arguments

Argument Name	Data Type	Description
`duration-us`	Integer Number or Real Number	Positive (non zero) amount of microseconds to pause execution. [required]

Return Value

None.

Remarks

This functions optionally accepts s as standard unit for its argument duration-us.

Examples

The following example resembles a simple delay effect. For each note being triggered by the musician, the script launches additional notes, each one of such additional successive notes with a more and more reduced volume.

on init
{ The amount of notes to play }
declare const $delayNotes := 4
{ Tempo with which the new notes will follow the orignal note }
declare const $bpm := 90
{ Convert BPM to microseconds (duration between the notes) }
declare const $delayMicroSeconds := 60 * 1000000 / $bpm
{ Just a working variable for being used with the while loop below }
declare polyphonic $i
{ For each successive note we trigger, we will reduce the velocity a bit}
declare polyphonic $velocity
end on
on note
{ First initialize the variable $i with 4 each time we enter this event handler, because each time we executed this handler, the variable will be 0 }
$i := $delayNotes
{ Loop which will be executed 4 times in a row }
while ($i)
{ Calculate the velocity for the next note being triggered }
$velocity := 127 * $i / ($delayNotes + 1)
{ Suspend this script for a short moment ... }
wait($delayMicroSeconds)
{ ... and after that short break, trigger a new note. }
play_note($EVENT_NOTE, $velocity)
{ Decrement loop counter $i by one }
$i := $i - 1
end while
end on

Using the wait() function can lead to concurrency issues with regular variables, which are global variables by default. You might need to use polyphonic variables in such cases.