Documents
Writing Docs Gigedit SFZ Instrument Scripts NKSP Language NKSP Reference

fork()

Calling this function creates the requested amount of additional execution instances. In programming languages this is often referred to as creating new threads .

The entire execution state of the callback handler (parent thread) calling fork(), is copied to the newly spawned execution instance(s) (child thread(s)). Accordingly the new child threads are starting their execution at this fork() function call. Right after the parent thread and child thread(s) returned from this function, their entire execution state and data is identical, which includes all polyphonic variables. To be able to distinguish the individual new thread(s) and parent thread in your script, each one is returning with a different result value from this function.

Even though all polyphonic variables are completely identical for all threads after returning from this function, as soon as the individual threads modify their polyphonic variables, the latter will start to deviate from the polyphonic variables of all other threads. That's because the polyphonic variables are copied when the threads were forked, each thread though maintains its own polyphonic memory.

By passing 1 for argument auto-abort the child threads are automatically aborted as soon as the parent thread terminated. However you may also pass 0 for auto-abort which will let the child threads run "detached" from its parent thread. In this case you can still terminate individual child threads from the parent thread by calling the abort() function at any time, passing the respective child's callback ID, which you can get on the parent thread by reading the built-in array variable %NKSP_CALLBACK_CHILD_ID[]. For example abort(%NKSP_CALLBACK_CHILD_ID[0]) would terminate the first child thread, abort(%NKSP_CALLBACK_CHILD_ID[1]) would terminate the second child thread, and so on. If you call fork() several times from the same thread, the new child threads are always appended to that array variable. The thread IDs of child threads will never be removed from that array variable during the entire life-time of the parent thread, even if the respective child threads have terminated long time ago. You may use the callback_status() function if you need to check whether a certain thread is still alive.

Likewise child threads can read the built-in array variable $NKSP_CALLBACK_PARENT_ID to get the callback ID of the thread which created it. That way a child thread may also check the alive state of its parent thread or abort the parent thread with the previously mentioned functions.

This function follows the "all or nothing" principle. That means either all of the requested amount of child threads are spawned or none at all.

Due to the real-time nature of this script language and its use case, there is currently a limit of creating max. 8 child threads per thread. If you need more, you can still chain your fork() calls by letting the respective child threads call fork() themselves.

Function Prototype

fork([amount], [auto-abort])

Arguments

Argument Name Data Type Description
amount Integer Number Amount of child threads to be spawned (between 1 and 8).
[optional, default: 1]
auto-abort Integer Number Whether the child threads shall automatically be aborted when parent thread terminated:
0: Don't abort child threads.
1: Automatically abort child threads.
[optional, default: 1]

Return Value

Data Type Description
Integer Number Returns -1 on error, i.e. if the requested amount of new threads would exceed either the global limit or limit per thread for child threads. Otherwise on success, this function returns 0 for the parent thread, 1 for the first child thread, 2 for the second child thread, and so on.

Examples

None yet.

See also

abort(), callback_status()

Availability

Since LinuxSampler 2.0.0.svn65.

This function is only available with NKSP, it does not exist with KSP.

Document Updated:  2019-08-29  |  Author:  Christian Schoenebeck