This article needs a technical review. How you can help.
Obsolete since JSAPI 8
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
These functions have been removed. Each JSRuntime (and, implicitly, the JSContext
that is created under it) tmust only be used on the thread that created it.
Transfer a JSContext
from one thread to another.
Syntax
jsword JS_ClearContextThread(JSContext *cx); jsword JS_SetContextThread(JSContext *cx);
Name | Type | Description |
---|---|---|
cx |
JSContext * |
The context to transfer from one thread to another. There must not be any active or suspended requests using this context. |
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 JSContext
s 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 callJS_ClearContextThread
. This is the last thing thread A does with the context. - Before thread B uses the
JSContext
, it must callJS_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