JS_SetOperationCallback

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_SetOperationCallback
  • Revision title: JS_SetOperationCallback
  • Revision id: 85487
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 1 words added, 41 words removed

Revision Content

{{ jsapi_minversion_header("1.8.5") }}

Set a callback function that is automatically called periodically while JavaScript code runs.

Syntax

void JS_SetOperationCallback(JSContext *cx, JSOperationCallback callback);

JSOperationCallback JS_GetOperationCallback(JSContext *cx);

void JS_TriggerOperationCallback(JSContext *cx);

void JS_TriggerAllOperationCallbacks(JSRuntime *rt);
Name Type Description
cx JSContext * A context.
callback JSOperationCallback (only in JS_SetOperationCallback) The callback function to install.

Callback syntax

JSBool (*JSOperationCallback)(JSContext *cx);
Name Type Description
cx JSContext *

Pointer to a JSContext in which this callback was installed.  The callback may use this context to call JSAPI functions, but it should first use JS_SetOperationCallback to set the context's operation callback to NULL. Otherwise the engine may call the operation callback again, reentering it.

{{ jsapi_provides_request() }}

{{ jsapi_ref_callback_return_values() }}

Description

JS_SetOperationCallback sets a callback that can be called asynchronously. Some common uses for an operation callback are:

  • To run garbage collection periodically, by calling JS_MaybeGC;
  • To periodically take a break from script execution to update the UI (though note that Mozilla does not do this, by design);
  • To enforce application limits on the amount of time a script may run. (In this case, the callback may terminate the script by returning JS_FALSE.)

Applications must not use both the operation callback API and the older

branch callback

API.

JS_ClearOperationCallback clears the current operation callback.

JS_GetOperationCallback returns the currently installed operation callback, or NULL if none is currently installed.

JS_SetOperationCallbackFunction sets the operation callback without changing the operation limit.

JS_GetOperationLimit returns the current operation limit, or JS_MAX_OPERATION_LIMIT if no operation callback is currently installed.

JS_SetOperationLimit sets the operation limit without changing the operation callback. It must be called only when an operation callback is installed.

{{ LXRSearch("ident", "i", "JS_MAX_OPERATION_LIMIT") }}
{{ LXRSearch("ident", "i", "JS_OPERATION_WEIGHT_BASE") }}
{{ LXRSearch("ident", "i", "JS_SetOperationCallback") }}
{{ LXRSearch("ident", "i", "JS_ClearOperationCallback") }}
{{ LXRSearch("ident", "i", "JS_GetOperationCallback") }}
{{ LXRSearch("ident", "i", "JS_GetOperationLimit") }}
{{ LXRSearch("ident", "i", "JS_SetOperationLimit") }}

Revision Source

<p>{{ jsapi_minversion_header("1.8.5") }}</p>
<p>Set a callback function that is automatically called periodically while JavaScript code runs.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval">void <strong>JS_SetOperationCallback</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, JSOperationCallback callback);

JSOperationCallback <strong>JS_GetOperationCallback</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx);

void <strong>JS_TriggerOperationCallback</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx);

void <strong>JS_TriggerAllOperationCallbacks</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSRuntime</a> *rt);
</pre>
<table class="fullwidth-table"> <tbody> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> <tr> <td><code>cx</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td> <td>A context.</td> </tr> <tr> <td><code>callback</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetOperationCallback" title="en/JS_SetOperationCallback">JSOperationCallback</a></code></td> <td><em>(only in <code>JS_SetOperationCallback</code></em><em>)</em> The callback function to install.</td> </tr> </tbody>
</table>
<h3 id="Callback_syntax" name="Callback_syntax">Callback syntax</h3>
<pre class="eval"><a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> (*<strong>JSOperationCallback</strong>)(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx);
</pre>
<table class="fullwidth-table"> <tbody> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> <tr> <td><code>cx</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td> <td> <p>Pointer to a <code>JSContext</code> in which this callback was installed.  The callback may use this context to call JSAPI functions, but it should first use <code>JS_SetOperationCallback</code> to set the context's operation callback to NULL. Otherwise the engine may call the operation callback again, reentering it.</p> <p>{{ jsapi_provides_request() }}</p> </td> </tr> </tbody>
</table>
<p>{{ jsapi_ref_callback_return_values() }}</p>
<h2 id="Description" name="Description">Description</h2>
<p><strong><code>JS_SetOperationCallback</code></strong> sets a callback that can be called asynchronously. Some common uses for an operation callback are:</p>
<ul> <li>To run garbage collection periodically, by calling <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_MaybeGC" title="en/JS_MaybeGC">JS_MaybeGC</a></code>;</li> <li>To periodically take a break from script execution to update the UI (though note that Mozilla does not do this, by design);</li> <li>To enforce application limits on the amount of time a script may run. (In this case, the callback may terminate the script by returning <code>JS_FALSE</code>.)</li>
</ul>
<p>Applications must not use both the operation callback API and the older</p>
<p><a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_SetBranchCallback" title="En/SpiderMonkey/JSAPI Reference/JS SetBranchCallback">branch callback</a></p>
<p>API.</p>
<p><strong><code>JS_ClearOperationCallback</code></strong> clears the current operation callback.</p>
<p><strong><code>JS_GetOperationCallback</code></strong> returns the currently installed operation callback, or <code>NULL</code> if none is currently installed.</p>
<p><code><strong>JS_SetOperationCallbackFunction</strong></code> sets the operation callback without changing the operation limit.</p>
<p><strong><code>JS_GetOperationLimit</code></strong> returns the current operation limit, or <code>JS_MAX_OPERATION_LIMIT</code> if no operation callback is currently installed.</p>
<p><strong><code>JS_SetOperationLimit</code></strong> sets the operation limit without changing the operation callback. It must be called only when an operation callback is installed.</p>
<p>{{ LXRSearch("ident", "i", "JS_MAX_OPERATION_LIMIT") }}<br>
{{ LXRSearch("ident", "i", "JS_OPERATION_WEIGHT_BASE") }}<br>
{{ LXRSearch("ident", "i", "JS_SetOperationCallback") }}<br>
{{ LXRSearch("ident", "i", "JS_ClearOperationCallback") }}<br>
{{ LXRSearch("ident", "i", "JS_GetOperationCallback") }}<br>
{{ LXRSearch("ident", "i", "JS_GetOperationLimit") }}<br>
{{ LXRSearch("ident", "i", "JS_SetOperationLimit") }}</p>
Revert to this revision