JS_SetOperationCallback

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

Revision Content

{{ Jsapi_minversion_header("1.8") }}

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

Syntax

#define JS_MAX_OPERATION_LIMIT  /* a uint32 constant */

#define JS_OPERATION_WEIGHT_BASE /* a uint32 constant */

void JS_SetOperationCallback(
    JSContext *cx, JSOperationCallback callback, uint32 operationLimit);

void JS_ClearOperationCallback(JSContext *cx);

JSOperationCallback JS_GetOperationCallback(JSContext *cx);

void JS_SetOperationCallbackFunction(JSContext *cx, JSOperationCallback callback);

uint32 JS_GetOperationLimit(JSContext *cx);

void JS_SetOperationLimit(JSContext *cx, uint32 operationLimit);

void JS_TriggerOperationCallback(JSContext *cx);
Name Type Description
cx JSContext * The context.
callback JSOperationCallback (only in JS_SetOperationCallback and JS_SetOperationCallbackFunction) The callback function to install.
operationLimit uint32 (only in JS_SetOperationCallback and JS_SetOperationLimit) A measure of the period between callbacks. This must be at least 1 and no greater than JS_MAX_OPERATION_LIMIT.

Callback syntax

JSBool (*JSOperationCallback)(JSContext *cx);
Name Type Description
cx JSContext * Pointer to a JSContext which the callback may use to call into JSAPI functions. For example, the callback may call JS_MaybeGC(cx). This is the context that is currently executing the code that triggered the callback. {{ Jsapi_provides_request() }}

{{ Jsapi_ref_callback_return_values() }}

Description

JS_SetOperationCallback sets a callback that the engine calls periodically, each time the internal operation count reaches the specified limit. Some common uses for an operation callback are:

  • To run garbage collection periodically, by calling JS_MaybeGC;
  • In a JS_THREADSAFE build, to cause multiple threads to pause and share objects periodically, by calling JS_YieldRequest;
  • 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.)

The operationLimit is a measure of the period between callbacks. The JavaScript engine maintains an internal counter that roughly reflects the amount of JavaScript processing left to do before the next callback. Each bit of JavaScript code that runs decrements this counter by some amount. When the counter reaches zero, the JavaScript engine pauses script execution, calls the callback, resets the counter to the current operation limit, and continues execution. When operationLimit is JS_OPERATION_WEIGHT_BASE, the callback will be called at least after each backward jump in the interpreter. To minimize the overhead of the callback invocation, an operationLimit of at least (100 * JS_OPERATION_WEIGHT_BASE) is recommended.

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") }}</p>
<p>Set a callback function that is automatically called periodically while JavaScript code runs.</p>
<h2 name="Syntax">Syntax</h2>
<pre class="eval">#define <strong>JS_MAX_OPERATION_LIMIT</strong>  /* a <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint32</a> constant */

#define <strong>JS_OPERATION_WEIGHT_BASE</strong> /* a <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint32</a> constant */

void <strong>JS_SetOperationCallback</strong>(
    <a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, JSOperationCallback callback, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint32</a> operationLimit);

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

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

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

<a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint32</a> <strong>JS_GetOperationLimit</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx);

void <strong>JS_SetOperationLimit</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint32</a> operationLimit);

void <strong>JS_TriggerOperationCallback</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>The 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> and <em><code>JS_SetOperationCallbackFunction</code></em>)</em> The callback function to install.</td> </tr> <tr> <td><code>operationLimit</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint32</a></code></td> <td><em>(only in <code>JS_SetOperationCallback</code> and <code>JS_SetOperationLimit</code>)</em> A measure of the period between callbacks. This must be at least 1 and no greater than <code>JS_MAX_OPERATION_LIMIT</code>.</td> </tr> </tbody>
</table>
<h3 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>Pointer to a <code>JSContext</code> which the callback may use to call into JSAPI functions. For example, the callback may call <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_MaybeGC" title="en/JS_MaybeGC">JS_MaybeGC</a>(cx)</code>. This is the context that is currently executing the code that triggered the callback. {{ Jsapi_provides_request() }}</td> </tr> </tbody>
</table>
<p>{{ Jsapi_ref_callback_return_values() }}</p><h2 name="Description">Description</h2>
<p><strong><code>JS_SetOperationCallback</code></strong> sets a callback that the engine calls periodically, each time the internal operation count reaches the specified limit. 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>In a <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_THREADSAFE" title="en/JS_THREADSAFE">JS_THREADSAFE</a></code> build, to cause multiple threads to pause and share objects periodically, by calling <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_YieldRequest" title="en/JS_YieldRequest">JS_YieldRequest</a></code>;</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>The <code>operationLimit</code> is a measure of the period between callbacks. The JavaScript engine maintains an internal counter that roughly reflects the amount of JavaScript processing left to do before the next callback. Each bit of JavaScript code that runs decrements this counter by some amount. When the counter reaches zero, the JavaScript engine pauses script execution, calls the callback, resets the counter to the current operation limit, and continues execution. When <code>operationLimit</code> is <strong><code>JS_OPERATION_WEIGHT_BASE</code></strong>, the callback will be called at least after each backward jump in the interpreter. To minimize the overhead of the callback invocation, an <code>operationLimit</code> of at least <code>(100 * JS_OPERATION_WEIGHT_BASE)</code> is recommended.</p>
<p>Applications must not use both the operation callback API and the older <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_SetBranchCallback" title="En/SpiderMonkey/JSAPI Reference/JS SetBranchCallback">branch callback</a> 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