Obsolete since JavaScript 1.9.1
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Specifies a callback function that is automatically called when a script branches backward during execution, when a function returns, and at the end of the script.
Replaced with JS_SetOperationCallback.
Syntax
JSBranchCallback JS_SetBranchCallback(JSContext *cx, JSBranchCallback cb);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
The context to hook. |
cb |
JSBranchCallback |
Pointer to the callback function. |
Callback syntax
JSBool (*JSBranchCallback)(JSContext *cx, JSScript *script);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
Pointer to a JSContext which the callback may use to call into JSAPI functions. For example, the callback my call 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()). |
script |
JSScript |
The script that is running. This is guaranteed to be non-null, unless the JSOPTION_NATIVE_BRANCH_CALLBACK option has been enabled for the context cx using JS_SetOptions(). |
If the callback returns JS_TRUE, the JS engine continues to execute the script.
If the callback raises an exception using JS_SetPendingException() and returns JS_FALSE, then the JavaScript engine propagates the exception to the script that was executing at the time.
If the callback returns JS_FALSE without raising an exception, then the JavaScript engine immediately stops running the script with an uncatchable error. The engine does not execute finally blocks in this case; this is the same behavior as any native method or callback.
Description
JS_SetBranchCallback specifies a callback function that is automatically called when a script branches backward during execution, when a function returns, and at the end of the script. One typical use for a callback is in a client application to enable a user to abort a script that runs for a long time. Another use is to call JS_MaybeGC periodically.
The callback is called very frequently, so applications should ensure that the callback runs very quickly most of the time. Typically an application only wants to do something every 5,000 or so branches. A common technique is to use a counter. The callback simply increments the counter and does nothing further (returning JS_TRUE immediately) unless the counter has reached the threshold value.