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

Contents of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_callback_status_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 (3 years, 11 months ago) by schoenebeck
File MIME type: text/html
File size: 3583 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>callback_status() function</title>
5 <meta name="description" content="Returns the current status of a callback (thread).">
6 </head>
7 <body>
8 <h1>callback_status()</h1>
9 <p>
10 Checks and returns the current status of the requested callback handler
11 instance. You can use this function to check if a specific script execution
12 instance (<i>thread</i>) is still alive. You have to pass the callback ID of the
13 one you are intested in. There are various ways to get a callback ID. For
14 example to get the currently running event handler's own callback ID you can
15 read the built-in variable <code>$NI_CALLBACK_ID</code> which you then may
16 hand over to other <i>threads</i> i.e. by storing it as user variable. Or if you
17 spawned your own threads by calling <code>fork()</code> you may get the
18 callback ID of the child threads by reading the array variable
19 <code>%NKSP_CALLBACK_CHILD_ID[]</code>, or for the parent thread by reading
20 <code>$NKSP_CALLBACK_PARENT_ID</code>. Refer to <code>fork()</code> for more
21 details about the latter two built-in variables.
22 </p>
23
24 <h3>Function Prototype</h3>
25 <p/>
26 <code lang="nksp">
27 callback_status(??callback-id??)
28 </code>
29
30 <h3>Arguments</h3>
31 <table>
32 <tr>
33 <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
34 </tr>
35 <tr>
36 <td><code>??callback-id??</code></td>
37 <td>Callback ID Number</td>
38 <td>Status of this script thread will be checked.<br>
39 [required]</td>
40 </tr>
41 </table>
42
43 <h3>Return Value</h3>
44 <p>
45 Returns one of the following number values:
46 </p>
47 <table>
48 <tr>
49 <th>Value</th> <th>Description</th>
50 </tr>
51 <tr>
52 <td><code>$CALLBACK_STATUS_TERMINATED</code></td>
53 <td>The callback is no longer alive and thus will no longer execute,
54 so it either terminated regularly or because of an error.</td>
55 </tr>
56 <tr>
57 <td><code>$CALLBACK_STATUS_QUEUE</code></td>
58 <td>The callback is alive, but is currently not executing. It is
59 currently waiting to be resumed by the scheduler. This might
60 be the case i.e. if the callback has just been created and
61 has not been executed by the scheduler at all yet, or if
62 the callback is currently suspended i.e. because it called
63 <code>wait()</code> or because it was auto suspended by the
64 script engine due to execution timing reasons.</td>
65 </tr>
66 <tr>
67 <td><code>$CALLBACK_STATUS_RUNNING</code></td>
68 <td>The callback is alive and is actually executing at this moment.
69 You will get this result value i.e. if a callback checks the
70 status of itself.</td>
71 </tr>
72 </table>
73 <note>
74 Even though there are currently just three possible return values,
75 <code>$CALLBACK_STATUS_QUEUE</code> and <code>$CALLBACK_STATUS_RUNNING</code> are
76 defined as bit flags, and since other bit flags might be added in future
77 you should only compare those two return values bitwise.
78 </note>
79
80 <h3>Examples</h3>
81 <p>None yet.</p>
82
83 <h3>Availability</h3>
84 <p>Since LinuxSampler 2.0.0.svn66.<p>
85
86 <h3>See also</h3>
87 <p><code>event_status()</code>, <code>abort()</code>, <code>fork()</code><p>
88
89 <note>
90 This function is only available with NKSP, it does not exist with KSP.
91 </note>
92
93 </body>
94 </html>

  ViewVC Help
Powered by ViewVC