/[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 3297 - (show annotations) (download) (as text)
Wed Jun 28 10:48:30 2017 UTC (23 months, 3 weeks ago) by schoenebeck
File MIME type: text/html
File size: 5843 byte(s)
* NKSP: Added function callback_status().
* NKSP: Added built-in constant $CALLBACK_STATUS_QUEUE.
* NKSP: Added built-in constant $CALLBACK_STATUS_RUNNING.
* NKSP: Added built-in constant $CALLBACK_STATUS_TERMINATED.

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 fork() calls
75 by letting the respective child threads call fork() 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>Description</th> <th>Data Type</th>
109 </tr>
110 <tr>
111 <td>
112 Returns <code>-1</code> on error, i.e. if the requested amount of new threads would exceed
113 either the global limit or limit per thread for child threads. Otherwise on success, this
114 function returns <code>0</code> for the parent thread, <code>1</code> for the first child
115 thread, <code>2</code> for the second child thread, and so on.
116 </td>
117 <td>Integer Number</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>

  ViewVC Help
Powered by ViewVC