reference/functions/nksp_fork_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>fork() function</title>
    <meta name="description" content="Creates new execution instances (threads).">
  </head>
  <body>
    <h1>fork()</h1>
    <p>
      Calling this function creates the requested <code>??amount??</code>
      of additional execution instances. In programming languages this is
      often referred to as creating new
      <i title="A thread of execution is one specific single sequence of programmed instructions. Multiple threads are executing concurrently, while they might be sharing certain data with each other.">
        threads
      </i>.
    </p>
    <p>
      The entire execution state of the callback handler (parent thread) calling
      <code>fork()</code>, is copied to the newly spawned execution
      instance(s) (child thread(s)). Accordingly the new child threads are starting their
      execution at this <code>fork()</code> 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.
    </p>
    <p>
      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.
    </p>
    <p>
      By passing <code>1</code> for argument <code>??auto-abort??</code>
      the child threads are automatically aborted as soon as the parent
      thread terminated. However you may also pass <code>0</code> for
      <code>??auto-abort??</code> 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 <code>abort()</code> 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
      <code>%NKSP_CALLBACK_CHILD_ID[]</code>. For example
      <code>abort(%NKSP_CALLBACK_CHILD_ID[0])</code> would terminate
      the first child thread, <code>abort(%NKSP_CALLBACK_CHILD_ID[1])</code>
      would terminate the second child thread, and so on. If you
      call <code>fork()</code> 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 <code>callback_status()</code> function if you
      need to check whether a certain thread is still alive.
    </p>
    <p>
      Likewise child threads can read the built-in array variable
      <code>$NKSP_CALLBACK_PARENT_ID</code> 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.
    </p>
    <p>
      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.
    </p>

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

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
fork([??amount??], [??auto-abort??])
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??amount??</code></td>
        <td>Integer Number</td>
        <td>Amount of child threads to be spawned (between <code>1</code> and <code>8</code>).<br>
            [optional, default: <code>1</code>]</td>
      </tr>
      <tr>
        <td><code>??auto-abort??</code></td>
        <td>Integer Number</td>
        <td>Whether the child threads shall automatically be aborted when parent thread terminated:<br>
            <code>0</code>: Don't abort child threads.<br>
            <code>1</code>: Automatically abort child threads.<br>
            [optional, default: <code>1</code>]</td>
      </tr>
    </table>
    
    <h3>Return Value</h3>
    <table>
      <tr>
        <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td>Integer Number</td>
        <td>
          Returns <code>-1</code> 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 <code>0</code> for the parent thread, <code>1</code> for the first child
          thread, <code>2</code> for the second child thread, and so on.
        </td>
      </tr>
    </table>

    <h3>Examples</h3>
    <p>None yet.</p>

    <h3>See also</h3>
    <p><code>abort()</code>, <code>callback_status()</code><p>

    <h3>Availability</h3>
    <p>Since LinuxSampler 2.0.0.svn65.<p>

    <note>
      This function is only available with NKSP, it does not exist with KSP.
    </note>

  </body>
</html>
1	<html>
2	<head>
3	<meta name="author" content="Christian Schoenebeck">
4	<title>fork() function</title>
5	<meta name="description" content="Creates new execution instances (threads).">
6	</head>
7	<body>
8	<h1>fork()</h1>
9	<p>
10	Calling this function creates the requested <code>??amount??</code>
11	of additional execution instances. In programming languages this is
12	often referred to as creating new
13	<i title="A thread of execution is one specific single sequence of programmed instructions. Multiple threads are executing concurrently, while they might be sharing certain data with each other.">
14	threads
15	</i>.
16	</p>
17	<p>
18	The entire execution state of the callback handler (parent thread) calling
19	<code>fork()</code>, is copied to the newly spawned execution
20	instance(s) (child thread(s)). Accordingly the new child threads are starting their
21	execution at this <code>fork()</code> function call. Right after
22	the parent thread and child thread(s) returned from this function,
23	their entire execution state and data is identical, which includes
24	all polyphonic variables. To be able to distinguish the individual
25	new thread(s) and parent thread in your script, each one is returning
26	with a different result value from this function.
27	</p>
28	<p>
29	Even though all polyphonic variables are completely identical for all
30	threads after returning from this function, as soon as the individual
31	threads modify their polyphonic variables, the latter will start to
32	deviate from the polyphonic variables of all other threads. That's
33	because the polyphonic variables are copied when the threads were
34	forked, each thread though maintains its own polyphonic memory.
35	</p>
36	<p>
37	By passing <code>1</code> for argument <code>??auto-abort??</code>
38	the child threads are automatically aborted as soon as the parent
39	thread terminated. However you may also pass <code>0</code> for
40	<code>??auto-abort??</code> which will let the child threads run
41	"detached" from its parent thread. In this case you can still
42	terminate individual child threads from the parent thread by
43	calling the <code>abort()</code> function at any time, passing
44	the respective child's callback ID, which you can get on the
45	parent thread by reading the built-in array variable
46	<code>%NKSP_CALLBACK_CHILD_ID[]</code>. For example
47	<code>abort(%NKSP_CALLBACK_CHILD_ID[0])</code> would terminate
48	the first child thread, <code>abort(%NKSP_CALLBACK_CHILD_ID[1])</code>
49	would terminate the second child thread, and so on. If you
50	call <code>fork()</code> several times from the same thread,
51	the new child threads are always appended to that array variable.
52	The thread IDs of child threads will never be removed from that
53	array variable during the entire life-time of the parent thread,
54	even if the respective child threads have terminated long time
55	ago. You may use the <code>callback_status()</code> function if you
56	need to check whether a certain thread is still alive.
57	</p>
58	<p>
59	Likewise child threads can read the built-in array variable
60	<code>$NKSP_CALLBACK_PARENT_ID</code> to get the callback ID
61	of the thread which created it. That way a child thread may
62	also check the alive state of its parent thread or abort the
63	parent thread with the previously mentioned functions.
64	</p>
65	<p>
66	This function follows the "all or nothing" principle. That means
67	either all of the requested amount of child threads are spawned
68	or none at all.
69	</p>
70
71	<note class="important">
72	Due to the real-time nature of this script language and its use
73	case, there is currently a limit of creating max. <code>8</code> child threads
74	per thread. If you need more, you can still chain your <code>fork()</code> calls
75	by letting the respective child threads call <code>fork()</code> themselves.
76	</note>
77
78	<h3>Function Prototype</h3>
79	<p/>
80	<code lang="nksp">
81	fork([??amount??], [??auto-abort??])
82	</code>
83
84	<h3>Arguments</h3>
85	<table>
86	<tr>
87	<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
88	</tr>
89	<tr>
90	<td><code>??amount??</code></td>
91	<td>Integer Number</td>
92	<td>Amount of child threads to be spawned (between <code>1</code> and <code>8</code>).<br>
93	[optional, default: <code>1</code>]</td>
94	</tr>
95	<tr>
96	<td><code>??auto-abort??</code></td>
97	<td>Integer Number</td>
98	<td>Whether the child threads shall automatically be aborted when parent thread terminated:<br>
99	<code>0</code>: Don't abort child threads.<br>
100	<code>1</code>: Automatically abort child threads.<br>
101	[optional, default: <code>1</code>]</td>
102	</tr>
103	</table>
104
105	<h3>Return Value</h3>
106	<table>
107	<tr>
108	<th>Data Type</th> <th>Description</th>
109	</tr>
110	<tr>
111	<td>Integer Number</td>
112	<td>
113	Returns <code>-1</code> on error, i.e. if the requested amount of new threads would exceed
114	either the global limit or limit per thread for child threads. Otherwise on success, this
115	function returns <code>0</code> for the parent thread, <code>1</code> for the first child
116	thread, <code>2</code> for the second child thread, and so on.
117	</td>
118	</tr>
119	</table>
120
121	<h3>Examples</h3>
122	<p>None yet.</p>
123
124	<h3>See also</h3>
125	<p><code>abort()</code>, <code>callback_status()</code><p>
126
127	<h3>Availability</h3>
128	<p>Since LinuxSampler 2.0.0.svn65.<p>
129
130	<note>
131	This function is only available with NKSP, it does not exist with KSP.
132	</note>
133
134	</body>
135	</html>