wasm_bindgen/
parent.rs

1//! `Parent<T>` — storage wrapper that backs the auto-injected `parent`
2//! field of an exported Rust type declared with
3//! `#[wasm_bindgen(extends = Parent)]`.
4//!
5//! Each parent method's wasm shim takes a `*const WasmRefCell<Parent>`,
6//! while the child's `__wbg_ptr` points at a `WasmRefCell<Child>`.
7//! The two pointers can't alias safely, so each JS instance carries a
8//! separate `__wbg_ptr_<Class>` slot for every class in its inheritance
9//! chain, and the parent data lives in its own `Rc<WasmRefCell<T>>`
10//! allocation that the wasm runtime can clone on demand. `Parent<T>` is
11//! that storage — a newtype around `Rc<WasmRefCell<T>>`.
12//!
13//! Users do **not** declare a `Parent<T>` field themselves. Writing
14//! `#[wasm_bindgen(extends = Animal)] struct Dog { ... }` causes the macro
15//! to inject `parent: wasm_bindgen::Parent<Animal>` as the first field of
16//! `Dog`; an explicit user-declared `Parent<T>` field on any
17//! `#[wasm_bindgen]` struct is rejected at macro time. In the child's
18//! constructor the field is populated with `Animal::new(...).into()` (using
19//! the [`From<T>`] impl below) or with [`Parent::new`]. From inside method
20//! bodies the parent value is reached as `self.parent.borrow()` /
21//! `self.parent.borrow_mut()`.
22
23use crate::__rt::alloc::rc::Rc;
24use crate::__rt::{Ref, RefMut, WasmRefCell};
25
26/// Storage wrapper for the auto-injected `parent` field on a struct that
27/// declares `#[wasm_bindgen(extends = Parent)]`.
28///
29/// Under the hood this is an `Rc<WasmRefCell<T>>` so that wasm-bindgen can
30/// produce a separately-refcounted parent pointer for JS-side prototype
31/// dispatch. Use [`Parent::borrow`] / [`Parent::borrow_mut`] to access the
32/// inner value. You should not need to construct `Parent<T>` directly
33/// outside the child's constructor; the [`From<T>`] impl is the typical way
34/// to initialize the injected `parent` field.
35///
36/// `Clone` is a cheap `Rc` clone — both copies point at the same parent
37/// data. `Debug` prints the wrapper plus the inner `T` (when `T: Debug`).
38pub struct Parent<T> {
39    inner: Rc<WasmRefCell<T>>,
40}
41
42impl<T> Clone for Parent<T> {
43    fn clone(&self) -> Self {
44        Self {
45            inner: Rc::clone(&self.inner),
46        }
47    }
48}
49
50impl<T: core::fmt::Debug> core::fmt::Debug for Parent<T> {
51    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
52        f.debug_tuple("Parent")
53            .field(&*self.inner.borrow())
54            .finish()
55    }
56}
57
58impl<T> Parent<T> {
59    /// Wraps a value in a new `Parent<T>`.
60    pub fn new(value: T) -> Self {
61        Self {
62            inner: Rc::new(WasmRefCell::new(value)),
63        }
64    }
65
66    /// Immutably borrows the wrapped value.
67    ///
68    /// Panics (or throws on the wasm target) if the value is currently
69    /// mutably borrowed.
70    pub fn borrow(&self) -> Ref<'_, T> {
71        self.inner.borrow()
72    }
73
74    /// Mutably borrows the wrapped value.
75    ///
76    /// Panics (or throws on the wasm target) if the value is currently
77    /// borrowed.
78    pub fn borrow_mut(&self) -> RefMut<'_, T> {
79        self.inner.borrow_mut()
80    }
81
82    /// Internal accessor used by the `#[wasm_bindgen(extends = ...)]`
83    /// codegen to clone the inner `Rc` when producing an ancestor ABI
84    /// pointer for JS. Not part of the public API.
85    #[doc(hidden)]
86    pub fn __wbg_clone_rc(&self) -> Rc<WasmRefCell<T>> {
87        Rc::clone(&self.inner)
88    }
89}
90
91impl<T> From<T> for Parent<T> {
92    fn from(value: T) -> Self {
93        Parent::new(value)
94    }
95}
wasm_bindgen/parent.rs

wasm_bindgen/
parent.rs
