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> |