script/dom/
mod.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5//! The implementation of the DOM.
6//!
7//! The DOM is comprised of interfaces (defined by specifications using
8//! [WebIDL](https://heycam.github.io/webidl/)) that are implemented as Rust
9//! structs in submodules of this module. Its implementation is documented
10//! below.
11//!
12//! A DOM object and its reflector
13//! ==============================
14//!
15//! The implementation of an interface `Foo` in Servo's DOM involves two
16//! related but distinct objects:
17//!
18//! * the **DOM object**: an instance of the Rust struct `dom::foo::Foo`
19//!   (marked with the `#[dom_struct]` attribute) on the Rust heap;
20//! * the **reflector**: a `JSObject` allocated by SpiderMonkey, that owns the
21//!   DOM object.
22//!
23//! Memory management
24//! =================
25//!
26//! Reflectors of DOM objects, and thus the DOM objects themselves, are managed
27//! by the SpiderMonkey Garbage Collector. Thus, keeping alive a DOM object
28//! is done through its reflector.
29//!
30//! For more information, see:
31//!
32//! * rooting pointers on the stack:
33//!   the [`Root`](bindings/root/struct.Root.html) smart pointer;
34//! * tracing pointers in member fields: the [`Dom`](bindings/root/struct.Dom.html),
35//!   [`MutNullableDom`](bindings/root/struct.MutNullableDom.html) and
36//!   [`MutDom`](bindings/root/struct.MutDom.html) smart pointers and
37//!   [the tracing implementation](bindings/trace/index.html);
38//! * rooting pointers from across thread boundaries or in channels: the
39//!   [`Trusted`](bindings/refcounted/struct.Trusted.html) smart pointer;
40//!
41//! Inheritance
42//! ===========
43//!
44//! Rust does not support struct inheritance, as would be used for the
45//! object-oriented DOM APIs. To work around this issue, Servo stores an
46//! instance of the superclass in the first field of its subclasses. (Note that
47//! it is stored by value, rather than in a smart pointer such as `Dom<T>`.)
48//!
49//! This implies that a pointer to an object can safely be cast to a pointer
50//! to all its classes.
51//!
52//! This invariant is enforced by the lint in
53//! `plugins::lints::inheritance_integrity`.
54//!
55//! Interfaces which either derive from or are derived by other interfaces
56//! implement the `Castable` trait, which provides three methods `is::<T>()`,
57//! `downcast::<T>()` and `upcast::<T>()` to cast across the type hierarchy
58//! and check whether a given instance is of a given type.
59//!
60//! ```ignore
61//! use dom::bindings::inheritance::Castable;
62//! use dom::element::Element;
63//! use dom::htmlelement::HTMLElement;
64//! use dom::htmlinputelement::HTMLInputElement;
65//!
66//! if let Some(elem) = node.downcast::<Element> {
67//!     if elem.is::<HTMLInputElement>() {
68//!         return elem.upcast::<HTMLElement>();
69//!     }
70//! }
71//! ```
72//!
73//! Furthermore, when discriminating a given instance against multiple
74//! interface types, code generation provides a convenient TypeId enum
75//! which can be used to write `match` expressions instead of multiple
76//! calls to `Castable::is::<T>`. The `type_id()` method of an instance is
77//! provided by the farthest interface it derives from, e.g. `EventTarget`
78//! for `HTMLMediaElement`. For convenience, that method is also provided
79//! on the `Node` interface to avoid unnecessary upcasts to `EventTarget`.
80//!
81//! ```ignore
82//! use dom::bindings::inheritance::{EventTargetTypeId, NodeTypeId};
83//!
84//! match *node.type_id() {
85//!     EventTargetTypeId::Node(NodeTypeId::CharacterData(_)) => ...,
86//!     EventTargetTypeId::Node(NodeTypeId::Element(_)) => ...,
87//!     ...,
88//! }
89//! ```
90//!
91//! Construction
92//! ============
93//!
94//! DOM objects of type `T` in Servo have two constructors:
95//!
96//! * a `T::new_inherited` static method that returns a plain `T`, and
97//! * a `T::new` static method that returns `DomRoot<T>`.
98//!
99//! (The result of either method can be wrapped in `Result`, if that is
100//! appropriate for the type in question.)
101//!
102//! The latter calls the former, boxes the result, and creates a reflector
103//! corresponding to it by calling `dom::bindings::utils::reflect_dom_object`
104//! (which yields ownership of the object to the SpiderMonkey Garbage Collector).
105//! This is the API to use when creating a DOM object.
106//!
107//! The former should only be called by the latter, and by subclasses'
108//! `new_inherited` methods.
109//!
110//! DOM object constructors in JavaScript correspond to a `T::Constructor`
111//! static method. This method is always fallible.
112//!
113//! Destruction
114//! ===========
115//!
116//! When the SpiderMonkey Garbage Collector discovers that the reflector of a
117//! DOM object is garbage, it calls the reflector's finalization hook. This
118//! function deletes the reflector's DOM object, calling its destructor in the
119//! process.
120//!
121//! Mutability and aliasing
122//! =======================
123//!
124//! Reflectors are JavaScript objects, and as such can be freely aliased. As
125//! Rust does not allow mutable aliasing, mutable borrows of DOM objects are
126//! not allowed. In particular, any mutable fields use `Cell` or `DomRefCell`
127//! to manage their mutability.
128//!
129//! `Reflector` and `DomObject`
130//! =============================
131//!
132//! Every DOM object has a `Reflector` as its first (transitive) member field.
133//! This contains a `*mut JSObject` that points to its reflector.
134//!
135//! The `FooBinding::Wrap` function creates the reflector, stores a pointer to
136//! the DOM object in the reflector, and initializes the pointer to the reflector
137//! in the `Reflector` field.
138//!
139//! The `DomObject` trait provides a `reflector()` method that returns the
140//! DOM object's `Reflector`. It is implemented automatically for DOM structs
141//! through the `#[dom_struct]` attribute.
142//!
143//! Implementing methods for a DOM object
144//! =====================================
145//!
146//! * `dom::bindings::codegen::Bindings::FooBinding::FooMethods` for methods
147//!   defined through IDL;
148//! * `&self` public methods for public helpers;
149//! * `&self` methods for private helpers.
150//!
151//! Accessing fields of a DOM object
152//! ================================
153//!
154//! All fields of DOM objects are private; accessing them from outside their
155//! module is done through explicit getter or setter methods.
156//!
157//! Inheritance and casting
158//! =======================
159//!
160//! All DOM interfaces part of an inheritance chain (i.e. interfaces
161//! that derive others or are derived from) implement the trait `Castable`
162//! which provides both downcast and upcasts.
163//!
164//! ```ignore
165//! # use script::dom::bindings::inheritance::Castable;
166//! # use script::dom::element::Element;
167//! # use script::dom::node::Node;
168//! # use script::dom::htmlelement::HTMLElement;
169//! fn f(element: &Element) {
170//!     let base = element.upcast::<Node>();
171//!     let derived = element.downcast::<HTMLElement>().unwrap();
172//! }
173//! ```
174//!
175//! Adding a new DOM interface
176//! ==========================
177//!
178//! Adding a new interface `Foo` requires at least the following:
179//!
180//! * adding the new IDL file at `components/script/dom/webidls/Foo.webidl`;
181//! * creating `components/script/dom/foo.rs`;
182//! * listing `foo.rs` in `components/script/dom/mod.rs`;
183//! * defining the DOM struct `Foo` with a `#[dom_struct]` attribute, a
184//!   superclass or `Reflector` member, and other members as appropriate;
185//! * implementing the
186//!   `dom::bindings::codegen::Bindings::FooBinding::FooMethods` trait for
187//!   `Foo`;
188//! * adding/updating the match arm in create_element in
189//!   `components/script/dom/create.rs` (only applicable to new types inheriting
190//!   from `HTMLElement`)
191//!
192//! More information is available in the [bindings module](bindings/index.html).
193//!
194//! Accessing DOM objects from layout
195//! =================================
196//!
197//! Layout code can access the DOM through the
198//! [`LayoutDom`](bindings/root/struct.LayoutDom.html) smart pointer. This does not
199//! keep the DOM object alive; we ensure that no DOM code (Garbage Collection
200//! in particular) runs while layout is accessing the DOM.
201//!
202//! Methods accessible to layout are implemented on `LayoutDom<Foo>` using
203//! `LayoutFooHelpers` traits.
204
205#[macro_use]
206pub(crate) mod macros;
207
208pub(crate) mod types {
209    include!(concat!(env!("OUT_DIR"), "/InterfaceTypes.rs"));
210}
211
212pub(crate) mod abortcontroller;
213pub(crate) mod abortsignal;
214#[expect(dead_code)]
215pub(crate) mod abstractrange;
216pub(crate) mod activation;
217pub(crate) mod animationevent;
218pub(crate) mod attr;
219pub(crate) mod audio;
220pub(crate) use self::audio::*;
221pub(crate) mod beforeunloadevent;
222pub(crate) mod bindings;
223pub(crate) mod blob;
224#[cfg(feature = "bluetooth")]
225pub(crate) mod bluetooth;
226#[cfg(feature = "bluetooth")]
227pub(crate) use self::bluetooth::*;
228pub(crate) mod broadcastchannel;
229pub(crate) mod bytelengthqueuingstrategy;
230mod canvas;
231pub(crate) use self::canvas::*;
232pub(crate) mod cdatasection;
233pub(crate) mod characterdata;
234pub(crate) mod client;
235pub(crate) mod clipboard;
236pub(crate) mod clipboardevent;
237pub(crate) mod clipboarditem;
238pub(crate) mod closeevent;
239pub(crate) mod commandevent;
240pub(crate) mod comment;
241pub(crate) mod compositionevent;
242pub(crate) mod compressionstream;
243pub(crate) mod console;
244pub(crate) mod cookiestore;
245pub(crate) mod countqueuingstrategy;
246mod create;
247pub(crate) mod credentialmanagement;
248pub(crate) use self::credentialmanagement::*;
249pub(crate) mod crypto;
250pub(crate) mod cryptokey;
251pub(crate) mod css;
252pub(crate) use self::css::*;
253pub(crate) mod customelementregistry;
254pub(crate) mod customevent;
255pub(crate) mod customstateset;
256pub(crate) mod datatransfer;
257pub(crate) mod datatransferitem;
258pub(crate) mod datatransferitemlist;
259pub(crate) mod debuggeradddebuggeeevent;
260pub(crate) mod debuggergetpossiblebreakpointsevent;
261pub(crate) mod debuggerglobalscope;
262pub(crate) mod decompressionstream;
263pub(crate) mod defaultteereadrequest;
264pub(crate) mod defaultteeunderlyingsource;
265pub(crate) mod dissimilaroriginlocation;
266pub(crate) mod dissimilaroriginwindow;
267#[expect(dead_code)]
268pub(crate) mod document;
269mod document_embedder_controls;
270pub(crate) mod document_event_handler;
271pub(crate) mod documentfragment;
272pub(crate) mod documentorshadowroot;
273pub(crate) mod documenttype;
274pub(crate) mod domexception;
275pub(crate) mod domimplementation;
276pub(crate) mod dommatrix;
277pub(crate) mod dommatrixreadonly;
278pub(crate) mod domparser;
279pub(crate) mod dompoint;
280pub(crate) mod dompointreadonly;
281pub(crate) mod domquad;
282pub(crate) mod domrect;
283pub(crate) mod domrectlist;
284pub(crate) mod domrectreadonly;
285pub(crate) mod domstringlist;
286pub(crate) mod domstringmap;
287pub(crate) mod domtokenlist;
288pub(crate) mod dynamicmoduleowner;
289#[expect(dead_code)]
290pub(crate) mod element;
291pub(crate) mod elementinternals;
292pub(crate) mod errorevent;
293pub(crate) mod event;
294pub(crate) mod eventsource;
295pub(crate) mod eventtarget;
296pub(crate) mod extendableevent;
297pub(crate) mod extendablemessageevent;
298pub(crate) mod fetchlaterresult;
299pub(crate) mod file;
300pub(crate) mod filelist;
301pub(crate) mod filereader;
302pub(crate) mod filereadersync;
303pub(crate) mod focusevent;
304pub(crate) mod formdata;
305pub(crate) mod formdataevent;
306pub(crate) mod gamepad;
307pub(crate) use self::gamepad::*;
308pub(crate) mod geolocation;
309pub(crate) use self::geolocation::*;
310#[expect(dead_code)]
311pub(crate) mod globalscope;
312pub(crate) mod hashchangeevent;
313pub(crate) mod headers;
314pub(crate) mod history;
315pub(crate) mod html;
316pub(crate) use self::html::*;
317pub(crate) mod indexeddb;
318pub(crate) use self::indexeddb::*;
319pub(crate) mod inputevent;
320pub(crate) mod intersectionobserver;
321pub(crate) mod intersectionobserverentry;
322pub(crate) mod keyboardevent;
323pub(crate) mod location;
324pub(crate) mod media;
325pub(crate) use self::media::*;
326pub(crate) mod messagechannel;
327pub(crate) mod messageevent;
328#[expect(dead_code)]
329pub(crate) mod messageport;
330pub(crate) mod mimetype;
331pub(crate) mod mimetypearray;
332pub(crate) mod mouseevent;
333pub(crate) mod mutationobserver;
334pub(crate) mod mutationrecord;
335pub(crate) mod namednodemap;
336pub(crate) mod navigationpreloadmanager;
337pub(crate) mod navigator;
338pub(crate) mod navigatorinfo;
339#[expect(dead_code)]
340pub(crate) mod node;
341pub(crate) mod nodeiterator;
342#[expect(dead_code)]
343pub(crate) mod nodelist;
344pub(crate) mod notification;
345pub(crate) mod pagetransitionevent;
346pub(crate) mod paintsize;
347pub(crate) mod paintworkletglobalscope;
348pub(crate) mod performance;
349pub(crate) use self::performance::*;
350pub(crate) mod permissions;
351pub(crate) mod permissionstatus;
352pub(crate) mod pipelineid;
353pub(crate) mod plugin;
354pub(crate) mod pluginarray;
355#[expect(dead_code)]
356pub(crate) mod pointerevent;
357pub(crate) mod popstateevent;
358pub(crate) mod processinginstruction;
359pub(crate) mod processingoptions;
360pub(crate) mod progressevent;
361#[expect(dead_code)]
362pub(crate) mod promise;
363pub(crate) mod promisenativehandler;
364pub(crate) mod promiserejectionevent;
365pub(crate) mod quotaexceedederror;
366pub(crate) mod radionodelist;
367pub(crate) mod range;
368pub(crate) mod raredata;
369#[expect(dead_code)]
370pub(crate) mod readablebytestreamcontroller;
371pub(crate) mod readablestream;
372pub(crate) mod readablestreambyobreader;
373pub(crate) mod readablestreambyobrequest;
374pub(crate) mod readablestreamdefaultcontroller;
375pub(crate) mod readablestreamdefaultreader;
376pub(crate) mod readablestreamgenericreader;
377pub(crate) mod reportingendpoint;
378pub(crate) mod reportingobserver;
379pub(crate) mod request;
380pub(crate) mod resizeobserver;
381pub(crate) mod resizeobserverentry;
382pub(crate) mod resizeobserversize;
383pub(crate) mod response;
384pub(crate) mod screen;
385mod scrolling_box;
386pub(crate) mod security;
387pub(crate) use self::security::*;
388pub(crate) mod selection;
389pub(crate) mod servointernals;
390#[expect(dead_code)]
391pub(crate) mod servoparser;
392pub(crate) mod shadowroot;
393pub(crate) mod staticrange;
394pub(crate) mod storage;
395pub(crate) mod storageevent;
396pub(crate) mod submitevent;
397pub(crate) mod subtlecrypto;
398pub(crate) mod svg;
399pub(crate) use self::svg::*;
400#[cfg(feature = "testbinding")]
401mod testing;
402#[cfg(feature = "testbinding")]
403pub(crate) use self::testing::*;
404pub(crate) mod text;
405pub(crate) mod textcontrol;
406pub(crate) mod textdecoder;
407pub(crate) mod textdecodercommon;
408pub(crate) mod textdecoderstream;
409pub(crate) mod textencoder;
410pub(crate) mod textencoderstream;
411pub(crate) mod texttrack;
412pub(crate) mod texttrackcue;
413pub(crate) mod texttrackcuelist;
414pub(crate) mod texttracklist;
415pub(crate) mod timeranges;
416pub(crate) mod toggleevent;
417pub(crate) mod touch;
418pub(crate) mod touchevent;
419pub(crate) mod touchlist;
420pub(crate) mod trackevent;
421pub(crate) mod transitionevent;
422pub(crate) mod treewalker;
423pub(crate) mod trustedhtml;
424pub(crate) mod trustedscript;
425pub(crate) mod trustedscripturl;
426pub(crate) mod trustedtypepolicy;
427pub(crate) mod trustedtypepolicyfactory;
428pub(crate) mod uievent;
429pub(crate) mod underlyingsourcecontainer;
430pub(crate) mod url;
431pub(crate) mod urlhelper;
432pub(crate) mod urlpattern;
433pub(crate) mod urlsearchparams;
434pub(crate) mod userscripts;
435pub(crate) mod validation;
436pub(crate) mod validitystate;
437pub(crate) mod values;
438pub(crate) mod videotrack;
439pub(crate) mod videotracklist;
440pub(crate) mod virtualmethods;
441pub(crate) mod visibilitystateentry;
442pub(crate) mod vttcue;
443pub(crate) mod vttregion;
444pub(crate) mod webgl;
445pub(crate) use self::webgl::extensions::ext::*;
446pub(crate) use self::webgl::*;
447pub(crate) mod websocket;
448#[cfg(feature = "webxr")]
449mod webxr;
450#[cfg(feature = "webxr")]
451pub(crate) use self::webxr::*;
452#[cfg(feature = "webgpu")]
453pub(crate) mod webgpu;
454#[cfg(feature = "webgpu")]
455pub(crate) use self::webgpu::*;
456#[cfg(not(feature = "webgpu"))]
457pub(crate) mod gpucanvascontext;
458pub(crate) mod webrtc;
459pub(crate) use self::webrtc::*;
460pub(crate) mod transformstream;
461pub(crate) mod transformstreamdefaultcontroller;
462pub(crate) mod wheelevent;
463#[expect(dead_code)]
464pub(crate) mod window;
465#[expect(dead_code)]
466pub(crate) mod windowproxy;
467pub(crate) mod workers;
468pub(crate) use self::workers::*;
469pub(crate) mod worklet;
470pub(crate) mod workletglobalscope;
471pub(crate) mod writablestream;
472pub(crate) mod writablestreamdefaultcontroller;
473pub(crate) mod writablestreamdefaultwriter;
474pub(crate) mod xmldocument;
475pub(crate) mod xmlhttprequest;
476pub(crate) mod xmlhttprequesteventtarget;
477pub(crate) mod xmlhttprequestupload;
478pub(crate) mod xmlserializer;
479pub(crate) mod xpathevaluator;
480pub(crate) mod xpathexpression;
481pub(crate) mod xpathresult;