As explained earlier, the
implementation of an interface
Foo involves two objects: the DOM object
(implemented in Rust) and the reflector (a
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
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
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]
(#throwing-exceptions) will have the return value wrapped in
Methods that use certain WebIDL types like
object will get a
*mut JSContext argument prepended to the argument list. Static methods
will be passed a
for the relevant global. This argument comes before the
argument, if any.
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.
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.
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.
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
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.
To be written.
Legacy callers are not yet implemented.
WebIDL methods, getters, and setters that need to throw exceptions need to
be explicitly marked as such with the
[SetterThrows] custom attributes.
[Throws] applies to both methods and attributes; for attributes it means
both the getter and the setter (if any) can throw.
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
Err() from the method with the appropriate [error value]
- Base classes to work with IDL callbacks.
- A shareable mutable container for the DOM.
- Generated JS-Rust bindings.
- WebIDL constants.
- Conversions of Rust values to and from
- Utilities to throw exceptions from Rust bindings.
- Machinery to conditionally expose things.
- Machinery to initialise interface prototype objects and interface objects.
- Implementation of
iterable<..., ...>WebIDL declarations.
- Implementation of
maplike<..., ...>WebIDL declarations.
- Machinery to initialise namespace objects.
- Utilities for the implementation of JSAPI proxy handlers.
Record(open-ended dictionary) type.
- 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
- Smart pointers for the JS-managed DOM objects.
- Trait representing the concept of [serializable objects] (https://html.spec.whatwg.org/multipage/#serializable-objects).
- This module implements structured cloning, as defined by [HTML] (https://html.spec.whatwg.org/multipage/#safe-passing-of-structured-data).
- Utilities for tracing JS-managed values.
- Trait representing the concept of [transferable objects] (https://html.spec.whatwg.org/multipage/#transferable-objects).
- Weak-referenceable JS-managed DOM objects.
- Functions for validating and extracting qualified XML names.