Module script::dom::bindings::refcounted

source ·
Expand description

A generic, safe mechanism by which DOM objects can be pinned and transferred between threads (or intra-thread for asynchronous events). Akin to Gecko’s nsMainThreadPtrHandle, this uses thread-safe reference counting and ensures that the actual SpiderMonkey GC integration occurs on the script thread via weak refcounts. Ownership of a Trusted<T> object means the DOM object of type T to which it points remains alive. Any other behaviour is undefined. To guarantee the lifetime of a DOM object when performing asynchronous operations, obtain a Trusted<T> from that object and pass it along with each operation. A usable pointer to the original DOM object can be obtained on the script thread from a Trusted<T> via the root method.

The implementation of Trusted<T> is as follows: The Trusted<T> object contains an atomic reference counted pointer to the Rust DOM object. A hashtable resides in the script thread, keyed on the pointer. The values in this hashtable are weak reference counts. When a Trusted<T> object is created or cloned, the reference count is increased. When a Trusted<T> is dropped, the count decreases. If the count hits zero, the weak reference is emptied, and is removed from its hash table during the next GC. During GC, the entries of the hash table are counted as JS roots.

Re-exports

Modules

Structs

  • LiveDOMReferences
    The set of live, pinned DOM objects that are currently prevented from being garbage collected due to outstanding references.
  • Trusted
    A safe wrapper around a raw pointer to a DOM object that can be shared among threads for use in asynchronous operations. The underlying DOM object is guaranteed to live at least as long as the last outstanding Trusted<T> instance.
  • TrustedPromise
    A safe wrapper around a DOM Promise object that can be shared among threads for use in asynchronous operations. The underlying DOM object is guaranteed to live at least as long as the last outstanding TrustedPromise instance. These values cannot be cloned, only created from existing Rc<Promise> values.
  • TrustedReference 🔒
    A pointer to a Rust DOM object that needs to be destroyed.

Functions