Obsolete since JavaScript 1.8.5
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.
Make a JSString thread-safe.
Syntax
JSBool JS_MakeStringImmutable(JSContext *cx, JSString *str);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
A context. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext. |
s |
JSString * |
The string to operate on. s must not be null. |
Description
A string's characters can never be changed, but SpiderMonkey uses two string optimization techniques behind the scenes:
- A growable string (see
JS_NewGrowableString) has a buffer that the JavaScript engine can reallocate so that concatenating it with another string is much faster. - A dependent string (see
JS_NewDependentString) is a substring of another (growable, dependent, or immutable) string. In memory it is represented as a pointer to the other string and a pair of integers for the substring's starting point and length, rather than as a separate copy of all the characters. This makes thesubstringoperation, and regular expression matches, faster.
In both cases, the JavaScript engine may change the fields of the JSString. These changes are not atomic. Therefore such strings must not be used by more than one thread at a time. Applications must call JS_MakeStringImmutable before sharing a JSString among threads by storing it in a C/C++ variable, field, or array element that another thread can read. (When an application shares a string by storing it in a JavaScript object that another thread can read, the JavaScript engine automatically makes the string thread-safe.)
After a successful call to JS_MakeStringImmutable, subsequent calls to JS_GetStringCharsZ on the same string are guaranteed to succeed, and subsequent calls to JS_GetStringChars on the same string are guaranteed to return a null-terminated string.