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_MaybeGC(cx). This is the context that is currently executing the code that triggered the callback. 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()).
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.

See Also