Compare Revisions

GC Rooting Guide

Revision 482887:

Revision 482887 by JonCoppeard on

Revision 482889:

Revision 482889 by JonCoppeard on

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

Revision 482887
Revision 482889
n17      A "GC thing" is the the term we use to dor something whose n17      A "GC thing" is the the term we use for something whose mem
>memory is allocated and managed by the garbage collector.  T>ory is allocated and managed by the garbage collector.  The 
>he types of GC thing pointer are:>main types of GC thing pointer are:
n32      Note that JS::Value and jsid may contain pointers internalln32      Note that JS::Value and jsid can contain pointers internall
>y even though they are not a normal pointer type, hence their inc>y even though they are not a normal pointer type, hence their inc
>lusion in this list.>lusion in this list.
n128      Since only a JS::Rooted<T> will cast to a JS::Handle&n128      Since only a JS::Rooted<T> will cast to a JS::Handle&
>lt;T>, the compiler will enforce correct rooting of any parame>lt;T>, the compiler will enforce correct rooting of any parame
>ters passed to a function that may trigger GC. JS::Handle<T&gt>ters passed to a function that may trigger GC. JS::Handle<T&gt
>; exists because creating and destroying a JS::Rooted<T> no>; exists because creating and destroying a JS::Rooted<T> is
>t free (though it only costs a few cycles). Thus, it makes more s> not free (though it only costs a few cycles). Thus, it makes mor
>ense to only root the GC thing once and reuse it through an indir>e sense to only root the GC thing once and reuse it through an in
>ect reference. Like a reference, a JS::Handle is immutable: it ca>direct reference. Like a reference, a JS::Handle is immutable: it
>n only ever refer to the JS::Rooted<T> that it was created > can only ever refer to the JS::Rooted<T> that it was creat
>for.>ed for.
n209      All GC thing pointers which are used as an out-parameter mun209      All GC thing pointers which are used as an out-parameter mu
>st be wrapped in a JS::MutableHandle<T>. A JS::MutableHandl>st be wrapped in a JS::MutableHandle<T>. A JS::MutableHandl
>e<T> is a reference to a JS::Rooted<T> that, unlike a>e<T> is a reference to a JS::Rooted<T> that, unlike a
> normal handle, may modify the underlying JS::Rooted<T>. Al> normal handle, may modify the underlying JS::Rooted<T>. Al
>l JS::MutableHandle<T> are created through an explicit "&am>l JS::MutableHandle<T>s are created through an explicit "&a
>p;" - address of operator - on a JS::Rooted<T> instance. JS>mp;" - address of operator - on a JS::Rooted<T> instance. J
>::MutableHandle<T> is exactly like a JS::Handle<T> ex>S::MutableHandle<T> is exactly like a JS::Handle<T> e
>cept that it adds a |.set(T &t)| method and must be created f>xcept that it adds a |.set(T &t)| method and must be created 
>rom a JS::Rooted<T> explicitly.>from a JS::Rooted<T> explicitly.
n319      There are some situations when using JS::Rooted<T> whn319      There are some situations when using JS::Rooted<T> is
>ere this is not possible, or is undesirable for performance reaso> not possible, or is undesirable for performance reasons.  T
>ns.  To cover these cases, there are various AutoRooter clas>o cover these cases, there are various AutoRooter classes that ca
>ses that can be used.>n be used.
t385      GC thing pointers on the heap must be wrapped in a JS::Heapt385      GC thing pointers on the heap must be wrapped in a JS::Heap
><T>. The only exception to this is if they are added as roo><T>. The only exception to this is if they are added as roo
>ts with the JS_Add<T>Root() functions, but don't do this un>ts with the JS_Add<T>Root() functions, but don't do this un
>less it's necessary.  Heap pointers must also continue to be>less it's really necessary.  Heap pointers must also continu
> traced in the normal way, which is not covered here.>e to be traced in the normal way, which is not covered here.

Back to History