/[svn]/doc/docbase/instrument_scripts/nksp/reference/functions/nksp_fork_function.html
ViewVC logotype

Contents of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_fork_function.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3294 - (show annotations) (download) (as text)
Tue Jun 27 23:29:31 2017 UTC (6 years, 9 months ago) by schoenebeck
File MIME type: text/html
File size: 5633 byte(s)
* NKSP: Added function fork().
* NKSP: Added built-in array variable %NKSP_CALLBACK_CHILD_ID[].
* NKSP: Added built-in variable $NKSP_CALLBACK_PARENT_ID.

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.">
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>event_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
66 <note class="important">
67 Due to the real-time nature of this script language and its use
68 case, there is currently a limit of <code>8</code> child threads
69 per thread. If you need more, you can still chain your fork() calls
70 by letting the respective child threads call fork() themselves.
71 </note>
72
73 <h3>Function Prototype</h3>
74 <p/>
75 <code lang="nksp">
76 fork([??amount??], [??auto-abort??])
77 </code>
78
79 <h3>Arguments</h3>
80 <table>
81 <tr>
82 <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
83 </tr>
84 <tr>
85 <td><code>??amount??</code></td>
86 <td>Integer Number</td>
87 <td>Amount of child threads to be spawned (between <code>1</code> and <code>8</code>).<br>
88 [optional, default: <code>1</code>]</td>
89 </tr>
90 <tr>
91 <td><code>??auto-abort??</code></td>
92 <td>Integer Number</td>
93 <td>Whether the child threads shall automatically be aborted when parent thread termianted:<br>
94 <code>0</code>: Don't abort child threads.<br>
95 <code>1</code>: Automatically abort child threads.<br>
96 [optional, default: <code>1</code>]</td>
97 </tr>
98 </table>
99
100 <h3>Return Value</h3>
101 <table>
102 <tr>
103 <th>Description</th> <th>Data Type</th>
104 </tr>
105 <tr>
106 <td>
107 Returns <code>-1</code> on error, i.e. if the requested amount of new threads would exceed
108 either the global limit or limit per thread for child threads. Otherwise on success, this
109 function returns <code>0</code> for the parent thread, <code>1</code> for the first child
110 thread, <code>2</code> for the second child thread, and so on.
111 </td>
112 <td>Integer Number</td>
113 </tr>
114 </table>
115
116 <h3>Examples</h3>
117 <p>None yet.</p>
118
119 <h3>See also</h3>
120 <p><code>abort()</code>, <code>event_status()</code><p>
121
122 <h3>Availability</h3>
123 <p>Since LinuxSampler 2.0.0.svn65.<p>
124
125 <note>
126 This function is only available with NKSP, it does not exist with KSP.
127 </note>
128
129 </body>
130 </html>

  ViewVC Help
Powered by ViewVC