JSTraceOp

  • Revision slug: SpiderMonkey/JSAPI_Reference/JSTraceOp
  • Revision title: JSTraceOp
  • Revision id: 142696
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment /* Description */ add "the" a few places :) and other readability tweaks

Revision Content

{{template.Jsapi_ref_header("JSTraceOp")}} {{template.Jsapi_minversion_header(1.9)}}

JSTraceOp is the type of the JSClass.mark callback when the JSCLASS_MARK_IS_TRACE flag is set.

Syntax

typedef void (*JSTraceOp)(JSTracer *trc, JSObject *obj);
Name Type Description
trc JSTracer * The tracer visiting obj.
obj JSObject * The object being visited.

Description

The JavaScript engine calls this hook to enumerate all traceable things reachable from obj's private data structure. For each such thing, the trace callback must call

  JS_CallTracer(trc, thing, kind);

or one of its convenience macros as described in jsapi.h. See also JSVAL_IS_TRACEABLE and JSVAL_TO_TRACEABLE.

JSTraceOp implementation can assume that no other threads mutate object state. The callback must not change the state of the object or the corresponding native structures. The only exception to this rule is the case when the embedding needs tight integration with GC. In that case the embedding can check if the traversal is a part of the marking phase through calling JS_IsGCMarkingTracer and run special code, like emptying caches or marking its native structures.

To define the tracer for a JSClass, the implementation must add JSCLASS_MARK_IS_TRACE to the JSClass.flags and use the JS_CLASS_TRACE(method) macro to convert JSTraceOp to JSMarkOp when initializing or assigning the JSClass.mark field.

Revision Source

<p>{{template.Jsapi_ref_header("JSTraceOp")}}
{{template.Jsapi_minversion_header(1.9)}}
</p><p><b><code>JSTraceOp</code></b> is the type of the <code><a href="en/JSClass.mark">JSClass.mark</a></code> callback when the <code>JSCLASS_MARK_IS_TRACE</code> flag is set.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval">typedef void (*<b>JSTraceOp</b>)(JSTracer *trc, JSObject *obj);
</pre>
<table class="fullwidth-table">
<tbody><tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>trc</code></td>
<td><code><a href="en/JSTracer">JSTracer</a> *</code></td>
<td>The tracer visiting <code>obj</code>.</td>
</tr>
<tr>
<td><code>obj</code></td>
<td><code><a href="en/JSObject">JSObject</a> *</code></td>
<td>The object being visited.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p>The JavaScript engine calls this hook to enumerate all traceable things reachable from <code>obj</code>'s private data structure. For each such thing, the <code>trace</code> callback must call
</p>
<pre class="eval">  <a href="en/JS_CallTracer">JS_CallTracer</a>(trc, thing, kind);
</pre>
<p>or one of its convenience macros as described in jsapi.h.  See also <code><a href="en/JSVAL_IS_TRACEABLE">JSVAL_IS_TRACEABLE</a></code> and <code><a href="en/JSVAL_TO_TRACEABLE">JSVAL_TO_TRACEABLE</a></code>.
</p><p><code>JSTraceOp</code> implementation can assume that no other threads mutate object state.  The callback must not change the state of the object or the corresponding native structures.  The only exception to this rule is the case when the embedding needs tight integration with GC.  In that case the embedding can check if the traversal is a part of the marking phase through calling <code><a href="en/JS_IsGCMarkingTracer">JS_IsGCMarkingTracer</a></code> and run special code, like emptying caches or marking its native structures.
</p><p>To define the tracer for a <code><a href="en/JSClass">JSClass</a></code>, the implementation must add <code>JSCLASS_MARK_IS_TRACE</code> to the <code><a href="en/JSClass.flags">JSClass.flags</a></code> and use the <code><a href="en/JS_CLASS_TRACE">JS_CLASS_TRACE</a>(method)</code> macro to convert <code>JSTraceOp</code> to <code>JSMarkOp</code> when initializing or assigning the <code>JSClass.mark</code> field.
</p>
Revert to this revision