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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3297 - (hide annotations) (download) (as text)
Wed Jun 28 10:48:30 2017 UTC (6 years, 9 months 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 schoenebeck 3294 <html>
2     <head>
3     <meta name="author" content="Christian Schoenebeck">
4     <title>fork() function</title>
5 schoenebeck 3295 <meta name="description" content="Creates new execution instances (threads).">
6 schoenebeck 3294 </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 schoenebeck 3297 ago. You may use the <code>callback_status()</code> function if you
56 schoenebeck 3294 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 schoenebeck 3295 <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 schoenebeck 3294
71     <note class="important">
72     Due to the real-time nature of this script language and its use
73 schoenebeck 3295 case, there is currently a limit of creating max. <code>8</code> child threads
74 schoenebeck 3294 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 schoenebeck 3295 <td>Whether the child threads shall automatically be aborted when parent thread terminated:<br>
99 schoenebeck 3294 <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 schoenebeck 3297 <p><code>abort()</code>, <code>callback_status()</code><p>
126 schoenebeck 3294
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