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.
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.