Module script::dom::bindings::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

RootableVec

A vector of items to be rooted with RootedVec. Guaranteed to be empty when not rooted. Usage: rooted_vec!(let mut v); or if you have an iterator of DomRoots, rooted_vec!(let v <- iterator);.

RootedTraceableBox

Roots any JSTraceable thing

RootedTraceableSet 🔒

Holds a set of JSTraceables that need to be rooted

RootedVec

A vector of items that are rooted for the lifetime ’a.

Constants

ROOTED_TRACEABLES 🔒

TLV Holds a set of JSTraceables that need to be rooted

Traits

JSTraceable

A trait to allow tracing (only) DOM objects.

Functions

trace_jsval

Trace a JSVal.

trace_object

Trace a JSObject.

trace_reflector

Trace the JSObject held by reflector.

trace_script

Trace a JSScript.

trace_string

Trace a JSString.

trace_traceables^⚠

SM Callback that traces the rooted traceables