Syntax

JSBool
JS_MakeStringImmutable(JSContext *cx, JSString *str);

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 the substring operation, 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.

See Also

• bug 1115986