Module trace

Utilities for tracing JS-managed values.

The lifetime of DOM objects is managed by the SpiderMonkey Garbage Collector. A rooted DOM object implementing the interface Foo is traced as follows:

1. The GC calls _trace defined in FooBinding during the marking phase. (This happens through JSClass.trace for non-proxy bindings, and through ProxyTraps.trace otherwise.)
2. _trace calls Foo::trace() (an implementation of JSTraceable). This is typically derived via a #[dom_struct] (implies #[derive(JSTraceable)]) annotation. Non-JS-managed types have an empty inline trace() method, achieved via unsafe_no_jsmanaged_fields! or similar.
3. For all fields, Foo::trace() calls trace() on the field. For example, for fields of type Dom<T>, Dom<T>::trace() calls trace_reflector().
4. trace_reflector() calls Dom::TraceEdge() with a pointer to the JSObject for the reflector. This notifies the GC, which will add the object to the graph, and will trace that object as well.
5. When the GC finishes tracing, it finalizes any reflectors that were not reachable.

The unsafe_no_jsmanaged_fields!() macro adds an empty implementation of JSTraceable to a datatype.

Structs

HashMapTracedValues 🔒

HashMap wrapper, that has non-jsmanaged keys

NoTrace 🔒

Wrapper type for nop traceble

RootedTraceableBox 🔒

Roots any JSTraceable thing

Traits

CustomTraceable 🔒

A trait to allow tracing only DOM sub-objects.

JSTraceable 🔒

A trait to allow tracing (only) DOM objects. Types that can be traced.

Functions

trace_jsval 🔒

Trace a JSVal.

trace_reflector 🔒 ^⚠

Trace the JSObject held by reflector.

trace_script 🔒

Trace a JSScript.

trace_string 🔒

Trace a JSString.