Module script::dom::bindings

The code to expose the DOM to JavaScript through IDL bindings.

Exposing a DOM object to JavaScript

As explained earlier, the implementation of an interface Foo involves two objects: the DOM object (implemented in Rust) and the reflector (a JSObject).

In order to expose the interface’s members to the web, properties corresponding to the operations and attributes are defined on an object in the reflector’s prototype chain or on the reflector itself.

Typically, these properties are either value properties whose value is a function (for operations) or accessor properties that have a getter and optionally a setter function (for attributes, depending on whether they are marked readonly).

All these JavaScript functions are set up such that, when they’re called, they call a Rust function in the generated glue code. This glue code does some sanity checks and argument conversions, and calls into API implementation for the DOM object.

Rust reflections of WebIDL constructs

WebIDL members are turned into methods on the DOM object (static methods for a static members and instance methods for regular members).

The instance methods for an interface Foo are defined on a dom::bindings::codegen::Bindings::FooBindings::FooMethods trait. This trait is then implemented for Foo. (All methods take an &self parameter, as pointers to DOM objects can be freely aliased.)

The return type and argument types are determined as described below. In addition to those, all methods that are allowed to throw will have the return value wrapped in Fallible<T>. Methods that use certain WebIDL types like any or object will get a *mut JSContext argument prepended to the argument list. Static methods will be passed a &GlobalScope for the relevant global. This argument comes before the *mut JSContext argument, if any.

Rust reflections of WebIDL operations (methods)

A WebIDL operation is turned into one method for every overload. The first overload gets the base name, and consecutive overloads have an underscore appended to the name.

The base name of the Rust method is simply the name of the WebIDL operation with the first letter converted to uppercase.

Rust reflections of WebIDL attributes

A WebIDL attribute is turned into a pair of methods: one for the getter and one for the setter. A readonly attribute only has a getter and no setter.

The getter’s name is the name of the attribute with the first letter converted to uppercase. It has Get prepended to it if the type of the attribute is nullable or if the getter can throw.

The method signature for the getter looks just like an operation with no arguments and the attribute’s type as the return type.

The setter’s name is Set followed by the name of the attribute with the first letter converted to uppercase. The method signature looks just like an operation with a void return value and a single argument whose type is the attribute’s type.

Rust reflections of WebIDL constructors

A WebIDL constructor is turned into a static class method named Constructor. The arguments of this method will be the arguments of the WebIDL constructor, with a &GlobalScope for the relevant global prepended. The return value of the constructor for MyInterface is exactly the same as that of a method returning an instance of MyInterface. Constructors are always allowed to throw.

Rust reflections of WebIDL types

The exact Rust representation for WebIDL types can depend on the precise way that they’re being used (e.g., return values and arguments might have different representations).

Optional arguments which do not have a default value are represented by wrapping Option<T> around the representation of the argument type. Optional arguments which do have a default value are represented by the argument type itself, set to the default value if the argument was not in fact passed in.

Variadic WebIDL arguments are represented by wrapping a Vec<T> around the representation of the argument type.

See the type mapping for particular types.

Rust reflections of stringifiers

To be written.

Rust reflections of legacy callers

Legacy callers are not yet implemented.

Throwing exceptions

WebIDL methods, getters, and setters that need to throw exceptions need to be explicitly marked as such with the [Throws], [GetterThrows] and [SetterThrows] custom attributes.

[Throws] applies to both methods and attributes; for attributes it means both the getter and the setter (if any) can throw. [GetterThrows] applies only to attributes. [SetterThrows] applies only to writable attributes.

The corresponding Rust methods will have the return value wrapped in Fallible<T>. To throw an exception, simply return Err() from the method with the appropriate [error value] (error/enum.Error.html).

Modules

• buffer_source
• callback
  Base classes to work with IDL callbacks.
• cell
  A shareable mutable container for the DOM.
• codegen
  Generated JS-Rust bindings.
• constant
  WebIDL constants.
• constructor
• conversions
  Conversions of Rust values to and from JSVal.
• error
  Utilities to throw exceptions from Rust bindings.
• finalize
• guard
  Machinery to conditionally expose things.
• import
• inheritance
  The Castable trait.
• interface
  Machinery to initialise interface prototype objects and interface objects.
• iterable
  Implementation of iterable<...> and iterable<..., ...> WebIDL declarations.
• like
  Implementation of setlike<...> and maplike<..., ...> WebIDL declarations.
• namespace
  Machinery to initialise namespace objects.
• num
  The Finite<T> struct.
• principals
• proxyhandler
  Utilities for the implementation of JSAPI proxy handlers.
• record
  The Record (open-ended dictionary) type.
• refcounted
  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.
• reflector
  The Reflector struct.
• root
  Smart pointers for the JS-managed DOM objects.
• serializable
  Trait representing the concept of [serializable objects] (https://html.spec.whatwg.org/multipage/#serializable-objects).
• settings_stack
• str
  The ByteString struct.
• structuredclone
  This module implements structured cloning, as defined by HTML.
• trace
  Utilities for tracing JS-managed values.
• transferable
  Trait representing the concept of [transferable objects] (https://html.spec.whatwg.org/multipage/#transferable-objects).
• utils
  Various utilities to glue JavaScript and the DOM implementation together.
• weakref
  Weak-referenceable JS-managed DOM objects.
• xmlname
  Functions for validating and extracting qualified XML names.