reference/functions/nksp_callback_status_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>callback_status() function</title>
    <meta name="description" content="Returns the current status of a callback (thread).">
  </head>
  <body>
    <h1>callback_status()</h1>
    <p>
      Checks and returns the current status of the requested callback handler
      instance. You can use this function to check if a specific script execution
      instance (<i>thread</i>) is still alive. You have to pass the callback ID of the
      one you are intested in. There are various ways to get a callback ID. For
      example to get the currently running event handler's own callback ID you can
      read the built-in variable <code>$NI_CALLBACK_ID</code> which you then may
      hand over to other <i>threads</i> i.e. by storing it as user variable. Or if you
      spawned your own threads by calling <code>fork()</code> you may get the
      callback ID of the child threads by reading the array variable
      <code>%NKSP_CALLBACK_CHILD_ID[]</code>, or for the parent thread by reading
      <code>$NKSP_CALLBACK_PARENT_ID</code>. Refer to <code>fork()</code> for more
      details about the latter two built-in variables.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
callback_status(??callback-id??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??callback-id??</code></td>
        <td>Callback ID Number</td>
        <td>Status of this script thread will be checked.<br>
            [required]</td>
      </tr>
    </table>

    <h3>Return Value</h3>
    <p>
      Returns one of the following number values:
    </p>
    <table>
      <tr>
        <th>Value</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>$CALLBACK_STATUS_TERMINATED</code></td>
        <td>The callback is no longer alive and thus will no longer execute,
            so it either terminated regularly or because of an error.</td>
      </tr>
      <tr>
        <td><code>$CALLBACK_STATUS_QUEUE</code></td>
        <td>The callback is alive, but is currently not executing. It is
            currently waiting to be resumed by the scheduler. This might
            be the case i.e. if the callback has just been created and
            has not been executed by the scheduler at all yet, or if
            the callback is currently suspended i.e. because it called
            <code>wait()</code> or because it was auto suspended by the
            script engine due to execution timing reasons.</td>
      </tr>
      <tr>
        <td><code>$CALLBACK_STATUS_RUNNING</code></td>
        <td>The callback is alive and is actually executing at this moment.
            You will get this result value i.e. if a callback checks the
            status of itself.</td>
      </tr>
    </table>
    <note>
      Even though there are currently just three possible return values,
      <code>$CALLBACK_STATUS_QUEUE</code> and <code>$CALLBACK_STATUS_RUNNING</code> are
      defined as bit flags, and since other bit flags might be added in future
      you should only compare those two return values bitwise.
    </note>

    <h3>Examples</h3>
    <p>None yet.</p>

    <h3>Availability</h3>
    <p>Since LinuxSampler 2.0.0.svn66.<p>

    <h3>See also</h3>
    <p><code>event_status()</code>, <code>abort()</code>, <code>fork()</code><p>

    <note>
      This function is only available with NKSP, it does not exist with KSP.
    </note>

  </body>
</html>
1	schoenebeck	3297	<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>