Sfink/Draft - GC Pointer Handling: Difference between revisions

   JSRootedObject obj1(cx, JS_NewObject(...));

   JSRootedObject obj2(cx, JS_NewObject(...));

Note that obj1 parameter of JS_DefineProperty has been modified to be of type 'JSHandleObject'.

A JSRootedObject is treated as a GC root until the function returns. A JSHandleObject is a reference to a rooted object. (JSRootedObject is like a rooted 'const JSObject &'.) Anything stack-allocated (local variables, parameters) needs to be rooted if it is live across a call that could trigger the garbage collector. You should generally assume that any JSAPI call could invoke the garbage collector unless labeled otherwise -- you might at first expect that only JSAPI calls that create things could GC, but in fact many operations will create gcthings internally. For example, anything that could throw a JS exception can GC, because the exception object will be allocated. (And just about anything that accepts a gcthing pointer as a parameter can throw a JS exception -- eg, if the object is a proxy for something in a different compartment, the compartment crossing may be disallowed, which would trigger an exception to be thrown.)

The rule to follow is "any gcthing pointer must be rooted if it is ever live across a call that might GC." Combined with the fact that just about any JSAPI call can GC, that is pretty close to "any gcthing pointer must be rooted if is live across a JSAPI call." To root something, store it in a JSRooted(something) type and never use the bare pointer value for anything. If you need to declare a function that accepts gcthing pointers, declare them as JSHandle(something). For out or in/out parameters, use JSMutableHandle(something). The resulting values may be used as if they were the original bare pointers for almost all purposes.

   JSRootedObject / JSHandleObject / JSMutableHandleObject

   JSRootedValue  / JSHandleValue  / JSMutableHandleValue

   JSRootedString / JSHandleString

   JSRootedId    / JSHandleId

   JSObject *foo(JSContext *cx, JSHandleObject obj, JSMutableHandleObject inout)

     JSRootedObject obj1(cx, JS_Foo(obj));

     JSRootedObject obj2(cx, JS_Bar(obj));

JSRootedObject is a typedef of Rooted<JSObject *>. Rooted<T> is an RAII class template that tells the given JSContext that the contained pointer is a root, and should be updated if a GC occurs that moves the object pointed to. The destructor will unregister that root. The registration is implemented as a simple stack (LIFO queue), which means that registrations and unregistrations must be properly nested. Given that this is an RAII class, this is almost automatic. The compiler will prevent you from using them for temporaries as in:

   JSRootedObject result(cx, JS_Foo(cx, JSRootedObject(cx, obj)));

   JSRootedObject *obj1pointer;

     JSRootedObject obj2(cx, JS_Foo());

     obj1pointer = new JSRootedObject(cx, obj1);

Heap-allocating Rooted<T> values are rarely desireable, but very occasionally necessary. If you use them, you are required to maintain the LIFO ordering manually.

JSHandleObject is a typedef of Handle<JSObject*>. Handle<T> is another class template that serves as an additional layer of indirection on top of a (rooted) pointer, so that if the pointer is updated, users of the Handle will automatically use the new value. In other words, JSHandleObject is really just syntactic sugar for JSObject**. If a Handle<T> escapes an enclosing Rooted<T>'s scope, Bad Things will happen -- the pointed-to pointer may be on a reused address on the stack, and so may be overwritten at any time, or a GC may occur that moves the pointer and does not update it. As long as Handle<T> is not used as a return value type, it is difficult to cause this to happen.

A JSMutableHandleObject (really MutableHandle<JSObject*>) is also a pointer to a pointer to a gcthing, but it allows updating the gcthing pointer. It is essentially a pointer to a Rooted<T>, and will implicitly convert from that. Usage is:

   JSRootedObject(cx, obj);

   void JS_UpdateParameter(JSMutableHandle obj)

will not be traced to keep the objects live, nor will those pointers get updated on a moving GC. For local (stack-allocated) vectors, the easiest fix is to use AutoValueVector, AutoIdVector, or AutoVectorRooter<JSObject*>, which register a GC callback to trace through the vector during a GC. For heap-allocated vectors, you should convert the vectors contents to patterns of chicken entrails splattered onto a plate glass window, and infer which gcthing was intended by meditating while staring at the window while it is illuminated only by a green strobe light.

       RootedObject tmp(cx, JS_NewObject(...));

In hot code, the overhead of rooting can be avoided if you are careful. Remember that the only thing that needs to be avoided is holding a gcthing pointer live across a call that might GC. So if a function takes a gcthing pointer but never GCs, it is valid for it to declare a bare pointer as a parameter. Even if a function might GC, it is ok to pass in a bare pointer variable as long as that variable is dead after the call. The function will have to root the value itself, if needed, but it can declare that capability by accepting a bare pointer (or JSRawObject) instead of a Handle.

* The gcthing pointer value may be used to construct a hash code

* The gcthing pointer value may be tagged

* The structure containing the pointer is sometimes allocated on the stack, sometimes on the heap

=== Double-rooting vs RawPointers ===