Compare Revisions

GC Rooting Guide

Revision 306331:

Revision 306331 by terrence on

Revision 363091:

Revision 363091 by terrence on

Title:
GC Rooting Guide
GC Rooting Guide
Slug:
SpiderMonkey/GC_Rooting_Guide
SpiderMonkey/GC_Rooting_Guide
Content:

Revision 306331
Revision 363091
n21      This guide explains the basics of interacting with SpiderMon21      This guide explains the basics of interacting with SpiderMo
>nkey's <a href="#defineGC" title="#defineGC">GC</a> as a SpiderMo>nkey's <a href="#defineGC" title="#defineGC">GC</a> as a SpiderMo
>nkey API user.&nbsp; Since SpiderMonkey has a moving GC, it very >nkey API user.&nbsp; Since SpiderMonkey has a moving GC, it is ve
>important that SpiderMonkey know about each and every <a href="#d>ry important that SpiderMonkey know about each and every <a href=
>efineGCPointer" title="#defineGCPointer">GCPointer</a> in the sys>"#defineGCPointer" title="#defineGCPointer">GCPointer</a> in the 
>tem.&nbsp; For the most part, the new SpiderMonkey API makes this>system.&nbsp; For the most part, the new SpiderMonkey API makes t
> task very simple.>his task very simple.
n24      Local&lt;T&gt;n24      JS::Rooted&lt;T&gt;
n27      All pointers that SpiderMonkey allocates and returns to then27      All GC thing pointers stored on the stack must be wrapped i
> API user are wrapped in the Local&lt;T&gt; class.&nbsp; A Local&>n the JS::Rooted&lt;T&gt; class. This will take care of all requi
>lt;T&gt; is a "Handle" to a GC pointer.&nbsp; You can use a Local>red rooting, but is only valid when used on the stack. Any pointe
>&lt;T&gt; almost exactly like you would have used T previously.&n>r stored in the heap must continue to be traced during the GC. A 
>bsp; The only difference is that their lifetime is managed by a H>JS::Rooted&lt;T&gt; instance will behave exactly as if it were th
>andleScope.&nbsp; Because of the lifetime restriction, Local&lt;T>e underlying pointer.
>&gt; must not stored on the heap: they are only allowed on the st 
>ack.&nbsp; When you need to store a GC pointer in the heap, make  
>its type on the heap a Heap&lt;T&gt;.&nbsp; A Heap&lt;T&gt; knows 
> how to convert itself from a Local&lt;T&gt; and will do so autom 
>atically when you store to one. 
28    </p>
29    <p>
30      SpiderMonkey makes it easy to remember to use JS::Rooted&lt
 >;T&gt; instead of a raw pointer because all of the API methods th
 >at may GC take a JS::Handle&lt;T&gt;, as described below.
n30      Heap&lt;T&gt;n33      JS::Handle&lt;T&gt;
n33      Like a handle, but its lifetime is not bound to the stack.n36      All GC thing pointers that are parameters to a function mus
 >t be wrapped in JS::Handle&lt;T&gt;. A JS::Handle&lt;T&gt; is a r
 >eference to a JS::Rooted&lt;T&gt;. All JS::Handle&lt;T&gt; are cr
 >eated implicitly by referencing a JS::Rooted&lt;T&gt;: It is not 
 >valid to create a JS::Handle&lt;T&gt; manually. Like JS::Rooted&l
 >t;T&gt;, a JS::Handle&lt;T&gt; can be used as if it were the unde
 >rlying pointer.
n35    <h2 id="HandleScope">n38    <p>
36      HandleScope39      Since only a JS::Rooted&lt;T&gt; will cast to a JS::Handle&
 >lt;T&gt;, the JSAPI will force correct rooting of any parameters 
 >passed to a function which may trigger GC. JS::Handle&lt;T&gt; ex
 >ists because creating and destroying a JS::Rooted&lt;T&gt; is a n
 >on-trivial amount of work. Thus, it makes more since to only root
 > the GC thing once and re-use it through an indirect reference. L
 >ike a reference, a JS::Handle is immutable.
40    </p>
41    <h2 id="Heap&lt;T&gt;">
42      Summary
t38    <p>t44    <ul>
39      The HandleScope controls the lifetimes of Local&lt;T&gt; an45      <li>Use JS::Rooted&lt;T&gt; on the stack.
>d Heap&lt;T&gt; handles and manages the cleanup of the handles wh 
>en the lifetime ends.&nbsp; HandleScopes for Local&lt;T&gt; are c 
>reated and destroyed at existing chokepoints, for example AutoEnt 
>erCompartment.&nbsp; These are stored in Thread Local Storage and 
> you should not have to interact with them directly.&nbsp; The Ha 
>ndleScope for Heap&lt;T&gt; is also stored in TLS and should also 
> not need to be interacted with directly. 
46      </li>
47      <li>Do not use JS::Rooted&lt;T&gt; on the heap.
48      </li>
49      <li>Do not use JS::Rooted&lt;T&gt; for parameters.
50      </li>
51      <li>Use JS::Handle&lt;T&gt; for parameters.
52      </li>
53      <li>Use an implicit cast from JS::Rooted&lt;T&gt; to get a 
 >JS::Handle&lt;T&gt;.
54      </li>
40    </p>55    </ul>
56    <h2 id="Heap&lt;T&gt;">
57      Example
58    </h2>

Back to History