JS BeginRequest

From MDC

Indicates to the JS engine that the calling thread is entering a region of code that may call into the JSAPI but does not block.

[edit] Syntax

void JS_BeginRequest(JSContext *cx);

void JS_EndRequest(JSContext *cx);

Name	Type	Description
cx	JSContext *	The context in which the calling thread intends to call JSAPI functions.

[edit] Description

When your multithreaded application wants to execute JSAPI calls on a thread, it must use JS_BeginRequest and JS_EndRequest to bracket maximal non-blocking hunks of native code that call the JSAPI. This "request model" serves two purposes: to interlock with the global garbage collector, and to optimize object locking to be lock-free in most cases.

To achieve these purposes, JS_BeginRequest first checks that garbage collection is not in process. If it is, JS_BeginRequest waits until garbage collection is complete before proceeding.

When the calling thread is finished using the JSAPI, it must call JS_EndRequest to allow garbage collection to run and to unlock objects that were accessed during the request.

In a JS_THREADSAFE build, many JSAPI functions must only be called from within a request. In this reference, the cx parameter of such functions is documented with the phrase “Requires request”, like this:

Name	Type	Description
cx	JSContext *	The context to use. Requires request. (In a JS_THREADSAFE build, the caller must be in a request on this JSContext.)

In a DEBUG build, this is enforced with assertions.

Requests constrain garbage collection. If any threads are in requests, garbage collection can happen only when all those threads call into the JSAPI. It is therefore imperative that native code executing within an active request on cx not block, or simply take too long, outside the JSAPI. Any blocking native call, or lengthy computation that can race safely with the garbage collector, must be bracketed within the native method or function with JS_SuspendRequest and JS_ResumeRequest.

It is safe to nest calls to JS_BeginRequest so long as each call is balanced by a matching call to JS_EndRequest.

JSAPI 1.7 and earlier JS_BeginRequest and JS_EndRequest are available only in JS_THREADSAFE builds. In SpiderMonkey 1.8 and later, these functions will be present, but will do nothing, in non-JS_THREADSAFE builds.

LXR ID Search for JS_BeginRequest
LXR ID Search for JS_EndRequest