script/dom/bindings/
trace.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//! Utilities for tracing JS-managed values.
6//!
7//! The lifetime of DOM objects is managed by the SpiderMonkey Garbage
8//! Collector. A rooted DOM object implementing the interface `Foo` is traced
9//! as follows:
10//!
11//! 1. The GC calls `_trace` defined in `FooBinding` during the marking
12//!    phase. (This happens through `JSClass.trace` for non-proxy bindings, and
13//!    through `ProxyTraps.trace` otherwise.)
14//! 2. `_trace` calls `Foo::trace()` (an implementation of `JSTraceable`).
15//!    This is typically derived via a `#[dom_struct]`
16//!    (implies `#[derive(JSTraceable)]`) annotation.
17//!    Non-JS-managed types have an empty inline `trace()` method,
18//!    achieved via `unsafe_no_jsmanaged_fields!` or similar.
19//! 3. For all fields, `Foo::trace()`
20//!    calls `trace()` on the field.
21//!    For example, for fields of type `Dom<T>`, `Dom<T>::trace()` calls
22//!    `trace_reflector()`.
23//! 4. `trace_reflector()` calls `Dom::TraceEdge()` with a
24//!    pointer to the `JSObject` for the reflector. This notifies the GC, which
25//!    will add the object to the graph, and will trace that object as well.
26//! 5. When the GC finishes tracing, it [`finalizes`](../index.html#destruction)
27//!    any reflectors that were not reachable.
28//!
29//! The `unsafe_no_jsmanaged_fields!()` macro adds an empty implementation of
30//! `JSTraceable` to a datatype.
31
32use std::collections::HashMap;
33use std::collections::hash_map::RandomState;
34use std::fmt::Display;
35use std::hash::{BuildHasher, Hash};
36
37/// A trait to allow tracing (only) DOM objects.
38pub(crate) use js::gc::Traceable as JSTraceable;
39use js::glue::{CallScriptTracer, CallStringTracer, CallValueTracer};
40use js::jsapi::{GCTraceKindToAscii, Heap, JSScript, JSString, JSTracer, TraceKind};
41use js::jsval::JSVal;
42use malloc_size_of::{MallocConditionalSizeOf, MallocSizeOf, MallocSizeOfOps};
43use rustc_hash::FxBuildHasher;
44use script_bindings::reflector::DomObject;
45pub(crate) use script_bindings::trace::*;
46
47use crate::dom::bindings::refcounted::{Trusted, TrustedPromise};
48use crate::dom::html::htmlmediaelement::HTMLMediaElementFetchContext;
49use crate::dom::srcset::SourceSet;
50use crate::dom::windowproxy::WindowProxyHandler;
51use crate::event_loop::script_thread::IncompleteParserContexts;
52use crate::script_runtime::StreamConsumer;
53use crate::tasks::task::TaskBox;
54
55/// Wrapper type for nop traceble
56///
57/// SAFETY: Inner type must not impl JSTraceable
58#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
59#[cfg_attr(crown, crown::trace_in_no_trace_lint::must_not_have_traceable)]
60pub(crate) struct NoTrace<T>(pub(crate) T);
61
62impl<T: Display> Display for NoTrace<T> {
63    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
64        self.0.fmt(f)
65    }
66}
67
68impl<T> From<T> for NoTrace<T> {
69    fn from(item: T) -> Self {
70        Self(item)
71    }
72}
73
74#[expect(unsafe_code)]
75unsafe impl<T> JSTraceable for NoTrace<T> {
76    #[inline]
77    unsafe fn trace(&self, _: *mut ::js::jsapi::JSTracer) {}
78}
79
80impl<T: MallocSizeOf> MallocSizeOf for NoTrace<T> {
81    fn size_of(&self, ops: &mut MallocSizeOfOps) -> usize {
82        self.0.size_of(ops)
83    }
84}
85
86/// HashMap wrapper, that has non-jsmanaged keys
87///
88/// Not all methods are reexposed, but you can access inner type via .0
89/// If you need cryptographic secure hashs, or your keys are arbitrary large inputs
90/// stick with the default hasher. Otherwise, stronlgy think about using FxHashBuilder
91/// with `new_fx()`
92#[cfg_attr(crown, crown::trace_in_no_trace_lint::must_not_have_traceable(0))]
93#[derive(Clone, Debug)]
94pub(crate) struct HashMapTracedValues<K, V, S = RandomState>(pub(crate) HashMap<K, V, S>);
95
96impl<K, V, S: Default> Default for HashMapTracedValues<K, V, S> {
97    fn default() -> Self {
98        Self(Default::default())
99    }
100}
101
102impl<K, V> HashMapTracedValues<K, V, RandomState> {
103    /// Wrapper for HashMap::new()
104    #[inline]
105    #[must_use]
106    pub(crate) fn new() -> HashMapTracedValues<K, V, RandomState> {
107        Self(HashMap::new())
108    }
109}
110
111impl<K, V> HashMapTracedValues<K, V, FxBuildHasher> {
112    #[inline]
113    #[must_use]
114    pub(crate) fn new_fx() -> HashMapTracedValues<K, V, FxBuildHasher> {
115        Self(HashMap::with_hasher(FxBuildHasher))
116    }
117}
118
119impl<K, V, S> HashMapTracedValues<K, V, S> {
120    #[inline]
121    pub(crate) fn iter(&self) -> std::collections::hash_map::Iter<'_, K, V> {
122        self.0.iter()
123    }
124
125    #[inline]
126    pub(crate) fn iter_mut(&mut self) -> std::collections::hash_map::IterMut<'_, K, V> {
127        self.0.iter_mut()
128    }
129
130    #[inline]
131    pub(crate) fn drain(&mut self) -> std::collections::hash_map::Drain<'_, K, V> {
132        self.0.drain()
133    }
134
135    #[inline]
136    pub(crate) fn is_empty(&self) -> bool {
137        self.0.is_empty()
138    }
139
140    #[inline]
141    pub(crate) fn values(&self) -> std::collections::hash_map::Values<'_, K, V> {
142        self.0.values()
143    }
144}
145
146impl<K, V, S> HashMapTracedValues<K, V, S>
147where
148    K: Eq + Hash,
149    S: BuildHasher,
150{
151    #[inline]
152    pub(crate) fn insert(&mut self, k: K, v: V) -> Option<V> {
153        self.0.insert(k, v)
154    }
155
156    #[inline]
157    pub(crate) fn get<Q>(&self, k: &Q) -> Option<&V>
158    where
159        K: std::borrow::Borrow<Q>,
160        Q: Hash + Eq + ?Sized,
161    {
162        self.0.get(k)
163    }
164
165    #[inline]
166    pub(crate) fn get_mut<Q: Hash + Eq + ?Sized>(&mut self, k: &Q) -> Option<&mut V>
167    where
168        K: std::borrow::Borrow<Q>,
169    {
170        self.0.get_mut(k)
171    }
172
173    #[inline]
174    pub(crate) fn contains_key<Q: Hash + Eq + ?Sized>(&self, k: &Q) -> bool
175    where
176        K: std::borrow::Borrow<Q>,
177    {
178        self.0.contains_key(k)
179    }
180
181    #[inline]
182    pub(crate) fn remove<Q: Hash + Eq + ?Sized>(&mut self, k: &Q) -> Option<V>
183    where
184        K: std::borrow::Borrow<Q>,
185    {
186        self.0.remove(k)
187    }
188
189    #[inline]
190    pub(crate) fn entry(&mut self, key: K) -> std::collections::hash_map::Entry<'_, K, V> {
191        self.0.entry(key)
192    }
193}
194
195impl<K, V, S> MallocSizeOf for HashMapTracedValues<K, V, S>
196where
197    K: Eq + Hash + MallocSizeOf,
198    V: MallocSizeOf,
199    S: BuildHasher,
200{
201    fn size_of(&self, ops: &mut MallocSizeOfOps) -> usize {
202        self.0.size_of(ops)
203    }
204}
205
206impl<K, V, S> MallocConditionalSizeOf for HashMapTracedValues<K, V, S>
207where
208    K: Eq + Hash + MallocSizeOf,
209    V: MallocConditionalSizeOf,
210    S: BuildHasher,
211{
212    fn conditional_size_of(&self, ops: &mut MallocSizeOfOps) -> usize {
213        self.0.conditional_size_of(ops)
214    }
215}
216
217#[expect(unsafe_code)]
218unsafe impl<K, V: JSTraceable, S> JSTraceable for HashMapTracedValues<K, V, S> {
219    #[inline]
220    unsafe fn trace(&self, trc: *mut ::js::jsapi::JSTracer) {
221        for v in self.0.values() {
222            unsafe { v.trace(trc) };
223        }
224    }
225}
226
227unsafe_no_jsmanaged_fields!(Box<dyn TaskBox>);
228
229unsafe_no_jsmanaged_fields!(IncompleteParserContexts);
230
231#[expect(dead_code)]
232/// Trace a `JSScript`.
233pub(crate) fn trace_script(tracer: *mut JSTracer, description: &str, script: &Heap<*mut JSScript>) {
234    unsafe {
235        trace!("tracing {}", description);
236        CallScriptTracer(
237            tracer,
238            script.ptr.get() as *mut _,
239            GCTraceKindToAscii(TraceKind::Script),
240        );
241    }
242}
243
244#[expect(dead_code)]
245/// Trace a `JSVal`.
246pub(crate) fn trace_jsval(tracer: *mut JSTracer, description: &str, val: &Heap<JSVal>) {
247    unsafe {
248        if !val.get().is_markable() {
249            return;
250        }
251
252        trace!("tracing value {}", description);
253        CallValueTracer(
254            tracer,
255            val.ptr.get() as *mut _,
256            GCTraceKindToAscii(val.get().trace_kind()),
257        );
258    }
259}
260
261#[expect(dead_code)]
262/// Trace a `JSString`.
263pub(crate) fn trace_string(tracer: *mut JSTracer, description: &str, s: &Heap<*mut JSString>) {
264    unsafe {
265        trace!("tracing {}", description);
266        CallStringTracer(
267            tracer,
268            s.ptr.get() as *mut _,
269            GCTraceKindToAscii(TraceKind::String),
270        );
271    }
272}
273
274unsafe_no_jsmanaged_fields!(TrustedPromise);
275
276unsafe_no_jsmanaged_fields!(WindowProxyHandler);
277unsafe_no_jsmanaged_fields!(SourceSet);
278unsafe_no_jsmanaged_fields!(HTMLMediaElementFetchContext);
279unsafe_no_jsmanaged_fields!(StreamConsumer);
280
281unsafe impl<T: DomObject> JSTraceable for Trusted<T> {
282    #[inline]
283    unsafe fn trace(&self, _: *mut JSTracer) {
284        // Do nothing
285    }
286}
script/dom/bindings/trace.rs

script/dom/bindings/
trace.rs
