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 byteteereadintorequest;
233pub(crate) mod byteteereadrequest;
234pub(crate) mod byteteeunderlyingsource;
235
236pub(crate) mod cdatasection;
237pub(crate) mod characterdata;
238pub(crate) mod client;
239pub(crate) mod clipboard;
240pub(crate) mod clipboardevent;
241pub(crate) mod clipboarditem;
242pub(crate) mod closeevent;
243pub(crate) mod commandevent;
244pub(crate) mod comment;
245pub(crate) mod compositionevent;
246pub(crate) mod compressionstream;
247pub(crate) mod console;
248pub(crate) mod cookiestore;
249pub(crate) mod countqueuingstrategy;
250mod create;
251pub(crate) mod credentialmanagement;
252pub(crate) use self::credentialmanagement::*;
253pub(crate) mod crypto;
254pub(crate) mod cryptokey;
255pub(crate) mod css;
256pub(crate) use self::css::*;
257pub(crate) mod customelementregistry;
258pub(crate) mod customevent;
259pub(crate) mod customstateset;
260pub(crate) mod datatransfer;
261pub(crate) mod datatransferitem;
262pub(crate) mod datatransferitemlist;
263pub(crate) mod debuggeradddebuggeeevent;
264pub(crate) mod debuggergetpossiblebreakpointsevent;
265pub(crate) mod debuggerglobalscope;
266pub(crate) mod debuggersetbreakpointevent;
267pub(crate) mod decompressionstream;
268pub(crate) mod defaultteereadrequest;
269pub(crate) mod defaultteeunderlyingsource;
270pub(crate) mod dissimilaroriginlocation;
271pub(crate) mod dissimilaroriginwindow;
272#[expect(dead_code)]
273pub(crate) mod document;
274mod document_embedder_controls;
275pub(crate) mod document_event_handler;
276pub(crate) mod documentfragment;
277pub(crate) mod documentorshadowroot;
278pub(crate) mod documenttype;
279pub(crate) mod domexception;
280pub(crate) mod domimplementation;
281pub(crate) mod dommatrix;
282pub(crate) mod dommatrixreadonly;
283pub(crate) mod domparser;
284pub(crate) mod dompoint;
285pub(crate) mod dompointreadonly;
286pub(crate) mod domquad;
287pub(crate) mod domrect;
288pub(crate) mod domrectlist;
289pub(crate) mod domrectreadonly;
290pub(crate) mod domstringlist;
291pub(crate) mod domstringmap;
292pub(crate) mod domtokenlist;
293pub(crate) mod dynamicmoduleowner;
294#[expect(dead_code)]
295pub(crate) mod element;
296pub(crate) mod elementinternals;
297pub(crate) mod errorevent;
298pub(crate) mod event;
299pub(crate) mod eventsource;
300pub(crate) mod eventtarget;
301pub(crate) mod extendableevent;
302pub(crate) mod extendablemessageevent;
303pub(crate) mod fetchlaterresult;
304pub(crate) mod file;
305pub(crate) mod filelist;
306pub(crate) mod filereader;
307pub(crate) mod filereadersync;
308pub(crate) mod focusevent;
309pub(crate) mod formdata;
310pub(crate) mod formdataevent;
311#[cfg(feature = "gamepad")]
312pub(crate) mod gamepad;
313#[cfg(feature = "gamepad")]
314pub(crate) use self::gamepad::*;
315pub(crate) mod geolocation;
316pub(crate) use self::geolocation::*;
317#[expect(dead_code)]
318pub(crate) mod globalscope;
319pub(crate) mod hashchangeevent;
320pub(crate) mod headers;
321pub(crate) mod history;
322pub(crate) mod html;
323pub(crate) use self::html::*;
324pub(crate) mod indexeddb;
325pub(crate) use self::indexeddb::*;
326pub(crate) mod inputevent;
327pub(crate) mod intersectionobserver;
328pub(crate) mod intersectionobserverentry;
329pub(crate) mod keyboardevent;
330pub(crate) mod location;
331pub(crate) mod media;
332pub(crate) use self::media::*;
333pub(crate) mod messagechannel;
334pub(crate) mod messageevent;
335#[expect(dead_code)]
336pub(crate) mod messageport;
337pub(crate) mod mimetype;
338pub(crate) mod mimetypearray;
339pub(crate) mod mouseevent;
340pub(crate) mod mutationobserver;
341pub(crate) mod mutationrecord;
342pub(crate) mod namednodemap;
343pub(crate) mod navigationpreloadmanager;
344pub(crate) mod navigator;
345pub(crate) mod navigatorinfo;
346#[expect(dead_code)]
347pub(crate) mod node;
348pub(crate) mod nodeiterator;
349#[expect(dead_code)]
350pub(crate) mod nodelist;
351pub(crate) mod notification;
352pub(crate) mod origin;
353pub(crate) mod pagetransitionevent;
354pub(crate) mod paintsize;
355pub(crate) mod paintworkletglobalscope;
356pub(crate) mod performance;
357pub(crate) use self::performance::*;
358pub(crate) mod permissions;
359pub(crate) mod permissionstatus;
360pub(crate) mod pipelineid;
361pub(crate) mod plugin;
362pub(crate) mod pluginarray;
363#[expect(dead_code)]
364pub(crate) mod pointerevent;
365pub(crate) mod popstateevent;
366pub(crate) mod processinginstruction;
367pub(crate) mod processingoptions;
368pub(crate) mod progressevent;
369#[expect(dead_code)]
370pub(crate) mod promise;
371pub(crate) mod promisenativehandler;
372pub(crate) mod promiserejectionevent;
373pub(crate) mod quotaexceedederror;
374pub(crate) mod radionodelist;
375pub(crate) mod range;
376pub(crate) mod raredata;
377#[expect(dead_code)]
378pub(crate) mod readablebytestreamcontroller;
379pub(crate) mod readablestream;
380pub(crate) mod readablestreambyobreader;
381pub(crate) mod readablestreambyobrequest;
382pub(crate) mod readablestreamdefaultcontroller;
383pub(crate) mod readablestreamdefaultreader;
384pub(crate) mod readablestreamgenericreader;
385pub(crate) mod reportingendpoint;
386pub(crate) mod reportingobserver;
387pub(crate) mod request;
388pub(crate) mod resizeobserver;
389pub(crate) mod resizeobserverentry;
390pub(crate) mod resizeobserversize;
391pub(crate) mod response;
392pub(crate) mod screen;
393mod scrolling_box;
394pub(crate) mod security;
395pub(crate) use self::security::*;
396pub(crate) mod selection;
397pub(crate) mod servointernals;
398#[expect(dead_code)]
399pub(crate) mod servoparser;
400pub(crate) mod shadowroot;
401pub(crate) mod staticrange;
402pub(crate) mod storage;
403pub(crate) mod storageevent;
404pub(crate) mod submitevent;
405pub(crate) mod subtlecrypto;
406pub(crate) mod svg;
407pub(crate) use self::svg::*;
408#[cfg(feature = "testbinding")]
409mod testing;
410#[cfg(feature = "testbinding")]
411pub(crate) use self::testing::*;
412pub(crate) mod text;
413pub(crate) mod textcontrol;
414pub(crate) mod textdecoder;
415pub(crate) mod textdecodercommon;
416pub(crate) mod textdecoderstream;
417pub(crate) mod textencoder;
418pub(crate) mod textencoderstream;
419pub(crate) mod texttrack;
420pub(crate) mod texttrackcue;
421pub(crate) mod texttrackcuelist;
422pub(crate) mod texttracklist;
423pub(crate) mod timeranges;
424pub(crate) mod toggleevent;
425pub(crate) mod touch;
426pub(crate) mod touchevent;
427pub(crate) mod touchlist;
428pub(crate) mod trackevent;
429pub(crate) mod transitionevent;
430pub(crate) mod treewalker;
431pub(crate) mod trustedhtml;
432pub(crate) mod trustedscript;
433pub(crate) mod trustedscripturl;
434pub(crate) mod trustedtypepolicy;
435pub(crate) mod trustedtypepolicyfactory;
436pub(crate) mod uievent;
437pub(crate) mod underlyingsourcecontainer;
438pub(crate) mod url;
439pub(crate) mod urlhelper;
440pub(crate) mod urlpattern;
441pub(crate) mod urlsearchparams;
442pub(crate) mod userscripts;
443pub(crate) mod validation;
444pub(crate) mod validitystate;
445pub(crate) mod values;
446pub(crate) mod videotrack;
447pub(crate) mod videotracklist;
448pub(crate) mod virtualmethods;
449pub(crate) mod visibilitystateentry;
450pub(crate) mod visualviewport;
451pub(crate) mod vttcue;
452pub(crate) mod vttregion;
453pub(crate) mod webgl;
454pub(crate) use self::webgl::extensions::ext::*;
455pub(crate) use self::webgl::*;
456pub(crate) mod websocket;
457#[cfg(feature = "webxr")]
458mod webxr;
459#[cfg(feature = "webxr")]
460pub(crate) use self::webxr::*;
461#[cfg(feature = "webgpu")]
462pub(crate) mod webgpu;
463#[cfg(feature = "webgpu")]
464pub(crate) use self::webgpu::*;
465#[cfg(not(feature = "webgpu"))]
466pub(crate) mod gpucanvascontext;
467pub(crate) mod webrtc;
468pub(crate) use self::webrtc::*;
469pub(crate) mod transformstream;
470pub(crate) mod transformstreamdefaultcontroller;
471pub(crate) mod wheelevent;
472#[expect(dead_code)]
473pub(crate) mod window;
474pub(crate) mod windowproxy;
475pub(crate) mod workers;
476pub(crate) use self::workers::*;
477pub(crate) mod worklet;
478pub(crate) mod workletglobalscope;
479pub(crate) mod writablestream;
480pub(crate) mod writablestreamdefaultcontroller;
481pub(crate) mod writablestreamdefaultwriter;
482pub(crate) mod xmldocument;
483pub(crate) mod xmlhttprequest;
484pub(crate) mod xmlhttprequesteventtarget;
485pub(crate) mod xmlhttprequestupload;
486pub(crate) mod xmlserializer;
487pub(crate) mod xpathevaluator;
488pub(crate) mod xpathexpression;
489pub(crate) mod xpathresult;