script_bindings/

root.rs

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */

use std::cell::UnsafeCell;
use std::hash::{Hash, Hasher};
use std::ops::Deref;
use std::rc::Rc;
use std::{fmt, mem, ptr};

use js::gc::{Handle, Traceable as JSTraceable};
use js::jsapi::{Heap, JSObject, JSTracer};
use js::rust::GCMethods;
use malloc_size_of::{MallocSizeOf, MallocSizeOfOps};

use crate::assert::assert_in_script;
use crate::conversions::DerivedFrom;
use crate::inheritance::Castable;
use crate::reflector::{DomObject, MutDomObject, Reflector};
use crate::trace::trace_reflector;

/// A rooted value.
#[cfg_attr(crown, crown::unrooted_must_root_lint::allow_unrooted_interior)]
pub struct Root<T: StableTraceObject> {
    /// The value to root.
    value: T,
    /// List that ensures correct dynamic root ordering
    root_list: *const RootCollection,
}

impl<T> Root<T>
where
    T: StableTraceObject + 'static,
{
    /// Create a new stack-bounded root for the provided value.
    /// It gives out references which cannot outlive this new `Root`.
    ///
    /// # Safety
    /// It must not outlive its associated `RootCollection`.
    pub unsafe fn new(value: T) -> Self {
        unsafe fn add_to_root_list(object: *const dyn JSTraceable) -> *const RootCollection {
            assert_in_script();
            STACK_ROOTS.with(|root_list| {
                unsafe { root_list.root(object) };
                root_list as *const _
            })
        }

        let root_list = unsafe { add_to_root_list(value.stable_trace_object()) };
        Root { value, root_list }
    }
}

/// `StableTraceObject` represents values that can be rooted through a stable address that will
/// not change for their whole lifetime.
/// It is an unsafe trait that requires implementors to ensure certain safety guarantees.
///
/// # Safety
///
/// Implementors of this trait must ensure that the `trace` method correctly accounts for all
/// owned and referenced objects, so that the garbage collector can accurately determine which
/// objects are still in use. Failing to adhere to this contract may result in undefined behavior,
/// such as use-after-free errors.
pub unsafe trait StableTraceObject {
    /// Returns a stable trace object which address won't change for the whole
    /// lifetime of the value.
    fn stable_trace_object(&self) -> *const dyn JSTraceable;
}

unsafe impl<T> StableTraceObject for Dom<T>
where
    T: DomObject,
{
    fn stable_trace_object(&self) -> *const dyn JSTraceable {
        // The JSTraceable impl for Reflector doesn't actually do anything,
        // so we need this shenanigan to actually trace the reflector of the
        // T pointer in Dom<T>.
        #[cfg_attr(crown, expect(crown::unrooted_must_root))]
        struct ReflectorStackRoot<T>(Reflector<T>);
        unsafe impl<T> JSTraceable for ReflectorStackRoot<T> {
            unsafe fn trace(&self, tracer: *mut JSTracer) {
                unsafe { trace_reflector(tracer, "on stack", &self.0) };
            }
        }
        unsafe {
            &*(self.reflector() as *const Reflector<T::ReflectorType>
                as *const ReflectorStackRoot<T::ReflectorType>)
        }
    }
}

unsafe impl<T> StableTraceObject for MaybeUnreflectedDom<T>
where
    T: DomObject,
{
    fn stable_trace_object(&self) -> *const dyn JSTraceable {
        // The JSTraceable impl for Reflector doesn't actually do anything,
        // so we need this shenanigan to actually trace the reflector of the
        // T pointer in Dom<T>.
        struct MaybeUnreflectedStackRoot<T>(T);
        unsafe impl<T> JSTraceable for MaybeUnreflectedStackRoot<T>
        where
            T: DomObject,
        {
            unsafe fn trace(&self, tracer: *mut JSTracer) {
                if self.0.reflector().get_jsobject().is_null() {
                    unsafe { self.0.trace(tracer) };
                } else {
                    unsafe { trace_reflector(tracer, "on stack", self.0.reflector()) };
                }
            }
        }
        unsafe { &*(self.ptr.as_ptr() as *const T as *const MaybeUnreflectedStackRoot<T>) }
    }
}

impl<T> Deref for Root<T>
where
    T: Deref + StableTraceObject,
{
    type Target = <T as Deref>::Target;

    fn deref(&self) -> &Self::Target {
        assert_in_script();
        &self.value
    }
}

impl<T> Drop for Root<T>
where
    T: StableTraceObject,
{
    fn drop(&mut self) {
        unsafe {
            (*self.root_list).unroot(self.value.stable_trace_object());
        }
    }
}

impl<T: fmt::Debug + StableTraceObject> fmt::Debug for Root<T> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        self.value.fmt(f)
    }
}

impl<T: fmt::Debug + DomObject> fmt::Debug for Dom<T> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        (**self).fmt(f)
    }
}

/// A traced reference to a DOM object
///
/// This type is critical to making garbage collection work with the DOM,
/// but it is very dangerous; if garbage collection happens with a `Dom<T>`
/// on the stack, the `Dom<T>` can point to freed memory.
///
/// This should only be used as a field in other DOM objects.
#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
#[repr(transparent)]
pub struct Dom<T> {
    ptr: ptr::NonNull<T>,
}

// Dom<T> is similar to Rc<T>, in that it's not always clear how to avoid double-counting.
// For now, we choose not to follow any such pointers.
impl<T> MallocSizeOf for Dom<T> {
    fn size_of(&self, _ops: &mut MallocSizeOfOps) -> usize {
        0
    }
}

/// Compare by pointer address
impl<T> PartialEq for Dom<T> {
    fn eq(&self, other: &Dom<T>) -> bool {
        self.ptr.as_ptr() == other.ptr.as_ptr()
    }
}

/// Compare by pointer address
impl<'a, T: DomObject> PartialEq<&'a T> for Dom<T> {
    fn eq(&self, other: &&'a T) -> bool {
        *self == Dom::from_ref(*other)
    }
}

impl<T> Eq for Dom<T> {}

/// Hashes the pointer address
impl<T> Hash for Dom<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.ptr.as_ptr().hash(state)
    }
}

impl<T> Clone for Dom<T> {
    #[inline]
    fn clone(&self) -> Self {
        assert_in_script();
        Dom { ptr: self.ptr }
    }
}

impl<T: DomObject> Dom<T> {
    /// Create a `Dom<T>` from a `&T`
    pub fn from_ref(obj: &T) -> Dom<T> {
        assert_in_script();
        Dom {
            ptr: ptr::NonNull::from(obj),
        }
    }

    /// Return a rooted version of this DOM object ([`DomRoot<T>`]) suitable for use on the stack.
    pub fn as_rooted(&self) -> DomRoot<T> {
        DomRoot::from_ref(self)
    }

    pub fn as_ptr(&self) -> *const T {
        self.ptr.as_ptr()
    }
}

impl<T: DomObject> Deref for Dom<T> {
    type Target = T;

    fn deref(&self) -> &T {
        assert_in_script();
        // We can only have &Dom<T> from a rooted thing, so it's safe to deref
        // it to &T.
        unsafe { &*self.ptr.as_ptr() }
    }
}

unsafe impl<T: DomObject> JSTraceable for Dom<T> {
    unsafe fn trace(&self, tracer: *mut JSTracer) {
        let trace_info = if cfg!(debug_assertions) {
            std::any::type_name::<T>()
        } else {
            "DOM object on heap"
        };
        unsafe {
            trace_reflector(tracer, trace_info, (*self.ptr.as_ptr()).reflector());
        }
    }
}

/// A traced reference to a DOM object that may not be reflected yet.
#[cfg_attr(crown, crown::unrooted_must_root_lint::must_root)]
pub struct MaybeUnreflectedDom<T> {
    ptr: ptr::NonNull<T>,
}

impl<T> MaybeUnreflectedDom<T>
where
    T: DomObject,
{
    /// Create a new MaybeUnreflectedDom value from the given boxed DOM object.
    ///
    /// # Safety
    /// TODO: unclear why this is marked unsafe.
    pub unsafe fn from_box(value: Box<T>) -> Self {
        Self {
            ptr: Box::leak(value).into(),
        }
    }

    /// Create a new MaybeUnreflectedDom value from the given RCed DOM object.
    ///
    /// # Safety
    /// TODO: unclear why this is marked unsafe.
    pub unsafe fn from_rc(value: Rc<T>) -> Self {
        Self {
            ptr: ptr::NonNull::new(Rc::into_raw(value) as *mut T).unwrap(),
        }
    }
}

impl<T> Root<MaybeUnreflectedDom<T>>
where
    T: DomObject,
{
    pub fn as_ptr(&self) -> *const T {
        self.value.ptr.as_ptr()
    }
}

impl<T> Root<MaybeUnreflectedDom<T>>
where
    T: MutDomObject,
{
    /// Treat the given JS object as the reflector of this unreflected object.
    ///
    /// # Safety
    /// obj must point to a valid, non-null JS object.
    pub unsafe fn reflect_with(self, obj: *mut JSObject) -> DomRoot<T> {
        let ptr = self.as_ptr();
        drop(self);
        let root = DomRoot::from_ref(unsafe { &*ptr });
        unsafe { root.init_reflector::<T>(obj) };
        root
    }
}

/// A rooted reference to a DOM object.
pub type DomRoot<T> = Root<Dom<T>>;

impl<T: Castable> DomRoot<T> {
    /// Cast a DOM object root upwards to one of the interfaces it derives from.
    pub fn upcast<U>(root: DomRoot<T>) -> DomRoot<U>
    where
        U: Castable,
        T: DerivedFrom<U>,
    {
        unsafe { mem::transmute::<DomRoot<T>, DomRoot<U>>(root) }
    }

    /// Cast a DOM object root downwards to one of the interfaces it might implement.
    pub fn downcast<U>(root: DomRoot<T>) -> Option<DomRoot<U>>
    where
        U: DerivedFrom<T>,
    {
        if root.is::<U>() {
            Some(unsafe { mem::transmute::<DomRoot<T>, DomRoot<U>>(root) })
        } else {
            None
        }
    }
}

impl<T: DomObject> DomRoot<T> {
    /// Generate a new root from a reference
    pub fn from_ref(unrooted: &T) -> DomRoot<T> {
        unsafe { DomRoot::new(Dom::from_ref(unrooted)) }
    }

    /// Create a traced version of this rooted object.
    ///
    /// # Safety
    ///
    /// This should never be used to create on-stack values. Instead these values should always
    /// end up as members of other DOM objects.
    pub fn as_traced(&self) -> Dom<T> {
        Dom::from_ref(self)
    }
}

impl<T> MallocSizeOf for DomRoot<T>
where
    T: DomObject + MallocSizeOf,
{
    fn size_of(&self, _ops: &mut MallocSizeOfOps) -> usize {
        0
    }
}

impl<T> PartialEq for DomRoot<T>
where
    T: DomObject,
{
    fn eq(&self, other: &Self) -> bool {
        self.value == other.value
    }
}

impl<T: DomObject> Eq for DomRoot<T> {}

impl<T: DomObject> Hash for DomRoot<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.value.hash(state);
    }
}

impl<T> Clone for DomRoot<T>
where
    T: DomObject,
{
    fn clone(&self) -> DomRoot<T> {
        DomRoot::from_ref(self)
    }
}

unsafe impl<T> JSTraceable for DomRoot<T>
where
    T: DomObject,
{
    unsafe fn trace(&self, _: *mut JSTracer) {
        // Already traced.
    }
}

/// A rooting mechanism for reflectors on the stack.
/// LIFO is not required.
///
/// See also [*Exact Stack Rooting - Storing a GCPointer on the CStack*][cstack].
///
/// [cstack]: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Internals/GC/Exact_Stack_Rooting
pub struct RootCollection {
    roots: UnsafeCell<Vec<*const dyn JSTraceable>>,
}

impl RootCollection {
    /// Create an empty collection of roots
    #[expect(clippy::new_without_default)]
    pub const fn new() -> RootCollection {
        RootCollection {
            roots: UnsafeCell::new(vec![]),
        }
    }

    /// Starts tracking a trace object.
    unsafe fn root(&self, object: *const dyn JSTraceable) {
        assert_in_script();
        unsafe { (*self.roots.get()).push(object) };
    }

    /// Stops tracking a trace object, asserting if it isn't found.
    unsafe fn unroot(&self, object: *const dyn JSTraceable) {
        assert_in_script();
        let roots = unsafe { &mut *self.roots.get() };
        match roots
            .iter()
            .rposition(|r| std::ptr::addr_eq(*r as *const (), object as *const ()))
        {
            Some(idx) => {
                // Partial inlining of `Vec::swap_remove` to avoid having to read and return the value since
                // we don't care about it, doing less work in our case.
                // SAFETY: the copy source and destination are derived from valid positions in the vector.
                unsafe {
                    let len = roots.len() - 1;
                    if len != idx {
                        let base_ptr = roots.as_mut_ptr();
                        ptr::copy_nonoverlapping(base_ptr.add(len), base_ptr.add(idx), 1);
                    }
                    roots.set_len(len);
                }
            },
            None => panic!("Can't remove a root that was never rooted!"),
        }
    }
}

thread_local!(pub static STACK_ROOTS: RootCollection = const { RootCollection::new() });

/// SM Callback that traces the rooted reflectors
///
/// # Safety
/// tracer must point to a valid, non-null JS tracer object.
pub unsafe fn trace_roots(tracer: *mut JSTracer) {
    trace!("tracing stack roots");
    STACK_ROOTS.with(|collection| {
        let collection = unsafe { &*collection.roots.get() };
        for root in collection {
            unsafe {
                (**root).trace(tracer);
            }
        }
    });
}

/// Get a slice of references to DOM objects.
pub trait DomSlice<T>
where
    T: JSTraceable + DomObject,
{
    /// Returns the slice of `T` references.
    fn r(&self) -> &[&T];
}

impl<T> DomSlice<T> for [Dom<T>]
where
    T: JSTraceable + DomObject,
{
    #[inline]
    fn r(&self) -> &[&T] {
        let _ = mem::transmute::<Dom<T>, &T>;
        unsafe { &*(self as *const [Dom<T>] as *const [&T]) }
    }
}

/// Returns a handle to a Heap member of a reflected DOM object.
/// The provided callback acts as a projection of the rooted-ness of
/// the provided DOM object; it must return a reference to a Heap
/// member of the DOM object.
pub fn rooted_heap_handle<'a, T: DomObject, U: GCMethods + Copy>(
    object: &'a T,
    f: impl Fn(&'a T) -> &'a Heap<U>,
) -> Handle<'a, U> {
    // SAFETY: Heap::handle is safe to call when the Heap is a member
    //   of a rooted object. Our safety invariants for DOM objects
    //   ensure that a &T is obtained via a root of T.
    unsafe { Handle::from_raw(f(object).handle()) }
}