mozilla

Revision 111171 of JS::Value

  • Revision slug: SpiderMonkey/JSAPI_Reference/Jsval
  • Revision title: jsval
  • Revision id: 111171
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 1 words added, 4 words removed

Revision Content

jsval is the type of JavaScript values in the JSAPI.

A C/C++ variable of type jsval can hold exactly the same values as a JavaScript var or property: string, number, object, boolean, null, or undefined. (Arrays, functions, and Errors are all objects.)

jsval is a variant type whose exact representation varies by architecture.  Embeddings should not rely on observed representation details, the size of jsval, or whether jsval is a primitive type.

The are two major caveats about working with jsvals.

jsval is not particularly type-safe

The data in a jsval can be accessed using these JSAPI macros and functions:

JS type jsval type tests jsval constants and constructors jsval accessors
null JSVAL_IS_NULL(v) JSVAL_NULL   
undefined JSVAL_IS_VOID(v) JSVAL_VOID   
boolean JSVAL_IS_BOOLEAN(v) JSVAL_TRUE, JSVAL_FALSE, BOOLEAN_TO_JSVAL(b) JSVAL_TO_BOOLEAN(v)
number JSVAL_IS_NUMBER(v), JSVAL_IS_INT(v), JSVAL_IS_DOUBLE(v) JSVAL_ZERO, JSVAL_ONE, INT_TO_JSVAL(i), DOUBLE_TO_JSVAL(d) JSVAL_TO_INT(v), JSVAL_TO_DOUBLE(v)
string JSVAL_IS_STRING(v) STRING_TO_JSVAL(str) JSVAL_TO_STRING(v), JS_GetStringChars(str), JS_GetStringLength(str)
object !JSVAL_IS_PRIMITIVE(v)
OBJECT_TO_JSVAL(obj) JSVAL_TO_OBJECT(v)

{{ Warning("The JSVAL_TO_x functions use C casts and bit twiddling. They are only safe if you already know that the jsval is of exactly the right type. Calling JSVAL_TO_DOUBLE() on an int jsval, for instance, triggers undefined behavior and will probably lead to a crash.") }}

jsvals are subject to garbage collection

A jsval can refer to a string or object that's located in SpiderMonkey's garbage-collected heap.

The garbage collector is designed to automatically free unreachable memory. It is rather eager about its job. It's like a robot that goes around picking up everything that isn't nailed down and putting it in the trash. If an application has a jsval variable that refers to a JSObject, the garbage collector might not know you're using the JSObject. So it might free it, leaving a dangling pointer. The solution is to tell SpiderMonkey that you're using the object, then tell it again when you're done.

In short, your jsvals must be rooted or your program will randomly crash. In some places, SpiderMonkey provides already-rooted jsvals which you can use for variables. See SpiderMonkey Garbage Collection Tips.

Revision Source

<p><strong><code>jsval</code></strong> is the type of JavaScript values in the JSAPI.</p>
<p>A C/C++ variable of type <code>jsval</code> can hold exactly the same values as a JavaScript <code>var</code> or property: string, number, object, boolean, <code>null</code>, or <code>undefined</code>. (Arrays, functions, and <code>Error</code>s are all objects.)</p>
<p><code>jsval</code> is a variant type whose exact representation varies by architecture.  Embeddings should not rely on observed representation details, the size of jsval, or whether jsval is a primitive type.</p>
<p>The are two major caveats about working with <code>jsval</code>s.</p>
<h3 id="jsval_is_not_particularly_type-safe" name="jsval_is_not_particularly_type-safe"><code>jsval</code> is not particularly type-safe</h3>
<p>The data in a <code>jsval</code> can be accessed using these JSAPI macros and functions:</p>
<table class="fullwidth-table"> <tbody> <tr> <th>JS type</th> <th><code>jsval</code> type tests</th> <th><code>jsval</code> constants and constructors</th> <th><code>jsval</code> accessors</th> </tr> <tr> <td><code>null</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_NULL" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_NULL">JSVAL_IS_NULL</a>(v)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_NULL" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_NULL">JSVAL_NULL</a></code></td> <td>  </td> </tr> <tr> <td><code>undefined</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_VOID" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_VOID">JSVAL_IS_VOID</a>(v)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID">JSVAL_VOID</a></code></td> <td>  </td> </tr> <tr> <td>boolean</td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_BOOLEAN" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_BOOLEAN">JSVAL_IS_BOOLEAN</a>(v)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_TRUE" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_TRUE">JSVAL_TRUE</a></code>, <code><a href="/en/JSVAL_FALSE" title="en/JSVAL_FALSE">JSVAL_FALSE</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/BOOLEAN_TO_JSVAL" title="en/SpiderMonkey/JSAPI_Reference/BOOLEAN_TO_JSVAL">BOOLEAN_TO_JSVAL</a>(b)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_BOOLEAN" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_BOOLEAN">JSVAL_TO_BOOLEAN</a>(v)</code></td> </tr> <tr> <td>number</td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_NUMBER" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_NUMBER">JSVAL_IS_NUMBER</a>(v)</code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_INT" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_INT">JSVAL_IS_INT</a>(v)</code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_DOUBLE" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_DOUBLE">JSVAL_IS_DOUBLE</a>(v)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_ZERO" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_ZERO">JSVAL_ZERO</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_ONE" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_ONE">JSVAL_ONE</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/INT_TO_JSVAL" title="en/SpiderMonkey/JSAPI_Reference/INT_TO_JSVAL">INT_TO_JSVAL</a>(i)</code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/DOUBLE_TO_JSVAL" title="en/SpiderMonkey/JSAPI_Reference/DOUBLE_TO_JSVAL">DOUBLE_TO_JSVAL</a>(d)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_INT" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_INT">JSVAL_TO_INT</a>(v)</code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_DOUBLE" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_DOUBLE">JSVAL_TO_DOUBLE</a>(v)</code></td> </tr> <tr> <td>string</td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_STRING" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_STRING">JSVAL_IS_STRING</a>(v)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/STRING_TO_JSVAL" title="en/SpiderMonkey/JSAPI_Reference/STRING_TO_JSVAL">STRING_TO_JSVAL</a>(str)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_STRING" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_STRING">JSVAL_TO_STRING</a>(v)</code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetStringChars" title="en/SpiderMonkey/JSAPI_Reference/JS_GetStringChars">JS_GetStringChars</a>(str)</code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetStringLength" title="en/SpiderMonkey/JSAPI_Reference/JS_GetStringLength">JS_GetStringLength</a>(str)</code></td> </tr> <tr> <td>object</td> <td><code>!<a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_OBJECT" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_IS_PRIMITIVE">JSVAL_IS_PRIMITIVE</a>(v)<br> </code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/OBJECT_TO_JSVAL" title="en/SpiderMonkey/JSAPI_Reference/OBJECT_TO_JSVAL">OBJECT_TO_JSVAL</a>(obj)</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_OBJECT" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_TO_OBJECT">JSVAL_TO_OBJECT</a>(v)</code></td> </tr> </tbody>
</table>
<p>{{ Warning("The <code>JSVAL_TO_x</code> functions use C casts and bit twiddling. They are only safe if you already know that the <code>jsval</code> is of exactly the right type. Calling <code>JSVAL_TO_DOUBLE()</code> on an int <code>jsval</code>, for instance, triggers undefined behavior and will probably lead to a crash.") }}</p><h3 id="jsvals_are_subject_to_garbage_collection" name="jsvals_are_subject_to_garbage_collection"><code>jsval</code>s are subject to garbage collection</h3>
<p>A <code>jsval</code> can refer to a string or object that's located in SpiderMonkey's garbage-collected heap.</p>
<p>The garbage collector is designed to automatically free unreachable memory. It is rather eager about its job. It's like a robot that goes around picking up everything that isn't nailed down and putting it in the trash. If an application has a <code>jsval</code> variable that refers to a <code>JSObject</code>, the garbage collector might not know you're using the <code>JSObject</code>. So it might free it, leaving a dangling pointer. The solution is to tell SpiderMonkey that you're using the object, then tell it again when you're done.</p>
<p>In short, your <code>jsval</code>s must be <em>rooted</em> or your program will randomly crash. In some places, SpiderMonkey provides already-rooted <code>jsval</code>s which you can use for variables. See <a href="/en/SpiderMonkey_Garbage_Collection_Tips" title="en/SpiderMonkey_Garbage_Collection_Tips">SpiderMonkey Garbage Collection Tips</a>.</p>
Revert to this revision