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.
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. |
Description
When your multithreaded application wants to use a JSContext, it must use JS_BeginRequest
and JS_EndRequest
to bracket maximal non-blocking hunks of native code that call the JSAPI. This "request model" is necessary to interlock with the global garbage collector.
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 thisJSContext
.
In a DEBUG
build, this is enforced with assertions.
Requests constrain garbage collection. If any thread is in a requests, garbage collection can happen only when that thread calls into the JSAPI. If one thread needs garbage collection, it blocks until each other thread makes a JSAPI call. 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, within a request, must be bracketed 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 are present, but do nothing, in non-JS_THREADSAFE
builds.
MXR ID Search for JS_BeginRequest
MXR ID Search for JS_EndRequest