Module script::dom::bindings::trace

source ·
Expand description

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
  • 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 Holds a set of JSTraceables that need to be rooted
  • RootedVec
    A vector of items that are rooted for the lifetime ’a.

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