script::dom::bindings

Module 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ยง

  • 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.
  • RootedTraceableBox ๐Ÿ”’
    Roots any JSTraceable thing
  • RootedVec ๐Ÿ”’
    A vector of items 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ยง