JavaScript-1.5 Reference

JS_BeginRequest Function

Summary

Indicates to the JS engine that an application thread is entering a critical section that calls the JS API freely but does not block.

Syntax

void JS_BeginRequest(JSContext *cx);

Description

When your multi-threaded application wants to execute JS API calls on a thread, it should use JS_BeginRequest and JS_EndRequest to bracket maximal non-blocking hunks of native code that call the JS API. This "request model" serves two purposes: to interlock with the global mark/sweep garbage collector, and to optimize object locking to be lock-free in most cases. In order 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 locking the JS engine runtime and incrementing its request counter. After incrementing the counter, JS_BeginRequest unlocks the runtime if it previously locked it.

It is therefore imperative that native code executing within an active request on cx not block, or simply take too long. 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 JS_EndRequest.

Notes

JS_BeginRequest is available only if you compile the JS engine with JS_THREADSAFE defined. In a default engine compilation, JS_THREADSAFE is undefined.

See Also

Groups [ Function ]
Documents [ LXR ID Search ]
Entries [ JS_EndRequest | JS_ResumeRequest | JS_SuspendRequest ]

This page was generated by APIDOC