JS_ClearContextThread

Transfer a JSContext from one thread to another.

Syntax

jsword JS_ClearContextThread(JSContext *cx);
jsword JS_SetContextThread(JSContext *cx);

Description

An application that creates or uses a JSContext in one thread, then uses or destroys it in another thread, must use JS_ClearContextThread and JS_SetContextThread to transfer the JSContext safely from one thread to the other.

The rules for using JSContexts in multiple threads are:

• Each JSContext may only be used by one thread at a time.
• Each request runs from start to finish on a single thread.
• Before transferring a JSContext from thread A to thread B, thread A must call JS_ClearContextThread. This is the last thing thread A does with the context.
• Before thread B uses the JSContext, it must call JS_SetContextThread. This is the first thing thread B does with the context, before beginning a request.

So the usual code for using a JSContext on a thread other than the one where it was created looks like this:

void myThread(JSContext *cx)
{
    JS_SetContextThread(cx);  /* Note: outside the request */
    JS_BeginRequest(cx);
    ...
    JS_EndRequest(cx);
    JS_ClearContextThread(cx);  /* Note: outside the request */
}

JS_SetContextThread ties cx to the current thread for exclusive use. No other thread may use cx until the current thread removes this association by calling JS_ClearContextThread. JS_SetContextThread returns the thread ID of the thread previously associated with this context. When the function is used properly, the return value is always zero, indicating that no thread was previously associated with the context.

JS_ClearContextThread relinquishes the calling thread's right to use cx. It returns the thread ID of the last thread to be associated with this context. (This is always the current thread ID when the function is used properly.)

JS_NewContext automatically associates the new context with the calling thread.

Use JS_GetContextThread to determine whether a context is associated with a thread.

JS_SetContextThread and JS_ClearContextThread are available only in JS_THREADSAFE builds.

MXR ID Search for JS_SetContextThread
MXR ID Search for JS_ClearContextThread