JS_SetInterruptCallback

This article covers features introduced in SpiderMonkey 31

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

Syntax

JSInterruptCallback
JS_SetInterruptCallback(JSRuntime *rt, JSInterruptCallback callback);
JSInterruptCallback
JS_GetInterruptCallback(JSRuntime *rt);
void
JS_RequestInterruptCallback(JSRuntime *rt);
Name Type Description
rt JSRuntime * The runtime.
callback JSInterruptCallback The callback function to install.

Callback syntax

bool
(* JSInterruptCallback)(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_SetInterruptCallback to set the context's interrupt callback to NULL. Otherwise the engine may call the interrupt callback again, reentering it.

Provides request. In JS_THREADSAFE builds, the JavaScript engine calls this callback only from within an active request on cx. The callback does not need to call JS_BeginRequest()).

Description

These functions allow setting an interrupt callback that will be called from the JS thread some time after any thread triggered the callback using JS_RequestInterruptCallback.
To schedule the GC and for other activities the engine internally triggers interrupt callbacks. The embedding should thus not rely on callbacks being triggered through the external API only.

Important note: Additional callbacks can occur inside the callback handler if it re-enters the JS engine. The embedding must ensure that the callback is disconnected before attempting such re-entry.

JS_SetInterruptCallback sets a callback that can be called asynchronously. Some common uses for an interrupt 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 false.)

JS_GetInterruptCallback returns the currently installed interrupt callback, or NULL if none is currently installed.

JS_RequestInterruptCallback requests a callback set using JS_SetInterruptCallback.

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, kscarfone
 Last updated by: arai,