JS_BeginRequest

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);

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 this JSContext.

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