JS SetOperationCallback

From MDC

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

[edit] 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);

uint32 JS_GetOperationLimit(JSContext *cx);

void JS_SetOperationLimit(JSContext *cx, uint32 operationLimit);

Name	Type	Description
cx	JSContext *	The context.
callback	JSOperationCallback	(only in JS_SetOperationCallback) 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.

[edit] Callback syntax

JSBool (* JS_DLL_CALLBACK 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. 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.)

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_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.

JS_ClearOperationCallback clears the current operation callback.

JS_GetOperationCallback returns the currently installed operation callback, or NULL if none is currently installed.

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.

LXR ID Search for JS_MAX_OPERATION_LIMIT
LXR ID Search for JS_OPERATION_WEIGHT_BASE
LXR ID Search for JS_SetOperationCallback
LXR ID Search for JS_ClearOperationCallback
LXR ID Search for JS_GetOperationCallback
LXR ID Search for JS_GetOperationLimit
LXR ID Search for JS_SetOperationLimit