JS SetBranchCallback

From MDC

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.

[edit] Syntax

JSBranchCallback JS_SetBranchCallback(JSContext *cx, JSBranchCallback cb);

Name	Type	Description
cx	JSContext *	The context to hook.
cb	JSBranchCallback	Pointer to the callback function.

[edit] Callback syntax

JSBool (* JS_DLL_CALLBACK 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 JS 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(cx, exc) and returns JS_FALSE, then the JS 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 JS 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.)

[edit] 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.

LXR ID Search for JS_SetBranchCallback