GC Rooting Guide

  • Revision slug: SpiderMonkey/GC_Rooting_Guide
  • Revision title: GC Rooting Guide
  • Revision id: 306331
  • Created:
  • Creator: terrence
  • Is current revision? No
  • Comment

Revision Content

Warning: the new stack rooting API is still in heavy development, this should not be taken as final until SpiderMonkey consensus is reached.

Warning: The information at SpiderMonkey Garbage Collection Tips and in the JSAPI User Guide is woefully out of date and should be ignored completely.

Introduction

This guide explains the basics of interacting with SpiderMonkey's GC as a SpiderMonkey API user.  Since SpiderMonkey has a moving GC, it very important that SpiderMonkey know about each and every GCPointer in the system.  For the most part, the new SpiderMonkey API makes this task very simple.

Local<T>

All pointers that SpiderMonkey allocates and returns to the API user are wrapped in the Local<T> class.  A Local<T> is a "Handle" to a GC pointer.  You can use a Local<T> almost exactly like you would have used T previously.  The only difference is that their lifetime is managed by a HandleScope.  Because of the lifetime restriction, Local<T> must not stored on the heap: they are only allowed on the stack.  When you need to store a GC pointer in the heap, make its type on the heap a Heap<T>.  A Heap<T> knows how to convert itself from a Local<T> and will do so automatically when you store to one.

Heap<T>

Like a handle, but its lifetime is not bound to the stack.

HandleScope

The HandleScope controls the lifetimes of Local<T> and Heap<T> handles and manages the cleanup of the handles when the lifetime ends.  HandleScopes for Local<T> are created and destroyed at existing chokepoints, for example AutoEnterCompartment.  These are stored in Thread Local Storage and you should not have to interact with them directly.  The HandleScope for Heap<T> is also stored in TLS and should also not need to be interacted with directly.

Revision Source

<div class="warning">
  <p id="Warning.3A_the_new_stack_rooting_API_is_still_in_heavy_development.2C_this_should_not_be_taken_as_final_until_SpiderMonkey_concensus_is_reached."><strong>Warning</strong>: the new stack rooting API is still in heavy development, this should not be taken as final until SpiderMonkey consensus is reached.</p>
</div>
<div class="warning">
  <p><strong>Warning:</strong> The information at <a href="/en-US/docs/SpiderMonkey_Garbage_Collection_Tips" title="/en-US/docs/SpiderMonkey_Garbage_Collection_Tips">SpiderMonkey Garbage Collection Tips</a> and in the <a href="/en-US/docs/SpiderMonkey/JSAPI_User_Guide" title="/en-US/docs/SpiderMonkey/JSAPI_User_Guide">JSAPI User Guide</a> is woefully out of date and should be ignored completely.</p>
</div>
<h2 id="Introduction">Introduction</h2>
<p>This guide explains the basics of interacting with SpiderMonkey's <a href="#defineGC" title="#defineGC">GC</a> as a SpiderMonkey API user.&nbsp; Since SpiderMonkey has a moving GC, it very important that SpiderMonkey know about each and every <a href="#defineGCPointer" title="#defineGCPointer">GCPointer</a> in the system.&nbsp; For the most part, the new SpiderMonkey API makes this task very simple.</p>
<h2 id="Local&lt;T&gt;">Local&lt;T&gt;</h2>
<p>All pointers that SpiderMonkey allocates and returns to the API user are wrapped in the Local&lt;T&gt; class.&nbsp; A Local&lt;T&gt; is a "Handle" to a GC pointer.&nbsp; You can use a Local&lt;T&gt; almost exactly like you would have used T previously.&nbsp; The only difference is that their lifetime is managed by a HandleScope.&nbsp; Because of the lifetime restriction, Local&lt;T&gt; must not stored on the heap: they are only allowed on the stack.&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 automatically when you store to one.</p>
<h2 id="Heap&lt;T&gt;">Heap&lt;T&gt;</h2>
<p>Like a handle, but its lifetime is not bound to the stack.</p>
<h2 id="HandleScope">HandleScope</h2>
<p>The HandleScope controls the lifetimes of Local&lt;T&gt; and Heap&lt;T&gt; handles and manages the cleanup of the handles when the lifetime ends.&nbsp; HandleScopes for Local&lt;T&gt; are created and destroyed at existing chokepoints, for example AutoEnterCompartment.&nbsp; These are stored in Thread Local Storage and you should not have to interact with them directly.&nbsp; The HandleScope for Heap&lt;T&gt; is also stored in TLS and should also not need to be interacted with directly.</p>
Revert to this revision