Skip to main content

wasmtime/runtime/gc/
maybe_rooted.rs

1//! GC references held in [`Val`](crate::Val)s and [`Ref`](crate::Ref)s.
2
3use crate::runtime::vm::VMGcRef;
4use crate::store::{AutoAssertNoGc, StoreOpaque};
5use crate::{
6    AnyRef, ArrayRef, AsContext, AsContextMut, EqRef, GcRef, HeapType, OwnedRooted, Result, Rooted,
7    StructRef, Unrooted, prelude::*,
8};
9use core::fmt;
10
11/// A reference to a GC object of type `T`, as held in a [`Val`](crate::Val)
12/// or [`Ref`](crate::Ref): either rooted or unrooted.
13///
14/// A [`MaybeRooted::Rooted`] reference keeps its object alive until the
15/// current LIFO rooting scope exits; see [`Rooted`]. A
16/// [`MaybeRooted::Unrooted`] reference is cheaper to create and needs only
17/// shared access to the store, but is valid only until the store's GC heap
18/// next changes; see [`Unrooted`].
19///
20/// APIs that read GC values, such as [`Global::get`](crate::Global::get),
21/// [`StructRef::field`](crate::StructRef::field), or the results of
22/// [`Func::call`](crate::Func::call), return unrooted references, so that
23/// rooting is always opt-in: the caller can choose to root them, and how
24/// (with [`MaybeRooted::to_rooted`], [`MaybeRooted::to_owned_rooted`], or
25/// [`Val::ensure_all_rooted`](crate::Val::ensure_all_rooted) for several at
26/// once), or to keep them unrooted.
27///
28/// APIs that take GC values to store or pass along, such as
29/// [`Global::set`](crate::Global::set),
30/// [`StructRef::new`](crate::StructRef::new), or the arguments of
31/// [`Func::call`](crate::Func::call), mutate the store, which invalidates
32/// unrooted references, and so they require rooted references, and return an
33/// error for unrooted ones; root them first.
34pub enum MaybeRooted<T: GcRef> {
35    /// A reference rooted in the current LIFO rooting scope; see [`Rooted`].
36    Rooted(Rooted<T>),
37
38    /// A reference that is not rooted, and is valid only until the store's GC
39    /// heap next changes; see [`Unrooted`].
40    Unrooted(Unrooted<T>),
41}
42
43impl<T: GcRef> Clone for MaybeRooted<T> {
44    fn clone(&self) -> Self {
45        *self
46    }
47}
48
49impl<T: GcRef> Copy for MaybeRooted<T> {}
50
51impl<T: GcRef> fmt::Debug for MaybeRooted<T> {
52    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
53        match self {
54            MaybeRooted::Rooted(r) => f.debug_tuple("Rooted").field(r).finish(),
55            MaybeRooted::Unrooted(r) => f.debug_tuple("Unrooted").field(r).finish(),
56        }
57    }
58}
59
60impl<T: GcRef> From<Rooted<T>> for MaybeRooted<T> {
61    #[inline]
62    fn from(r: Rooted<T>) -> Self {
63        MaybeRooted::Rooted(r)
64    }
65}
66
67impl<T: GcRef> From<Unrooted<T>> for MaybeRooted<T> {
68    #[inline]
69    fn from(r: Unrooted<T>) -> Self {
70        MaybeRooted::Unrooted(r)
71    }
72}
73
74macro_rules! upcasts {
75    ($($from:ty => $to:ty;)*) => {$(
76        impl From<MaybeRooted<$from>> for MaybeRooted<$to> {
77            #[inline]
78            fn from(r: MaybeRooted<$from>) -> Self {
79                match r {
80                    MaybeRooted::Rooted(r) => MaybeRooted::Rooted(r.into()),
81                    MaybeRooted::Unrooted(r) => MaybeRooted::Unrooted(r.into()),
82                }
83            }
84        }
85
86        impl From<Rooted<$from>> for MaybeRooted<$to> {
87            #[inline]
88            fn from(r: Rooted<$from>) -> Self {
89                MaybeRooted::Rooted(r.into())
90            }
91        }
92
93        impl From<Unrooted<$from>> for MaybeRooted<$to> {
94            #[inline]
95            fn from(r: Unrooted<$from>) -> Self {
96                MaybeRooted::Unrooted(r.into())
97            }
98        }
99    )*};
100}
101
102upcasts! {
103    EqRef => AnyRef;
104    StructRef => AnyRef;
105    ArrayRef => AnyRef;
106}
107
108impl<T: GcRef> MaybeRooted<T> {
109    /// Is this a rooted reference?
110    #[inline]
111    pub fn is_rooted(&self) -> bool {
112        matches!(self, MaybeRooted::Rooted(_))
113    }
114
115    /// Is this an unrooted reference?
116    #[inline]
117    pub fn is_unrooted(&self) -> bool {
118        matches!(self, MaybeRooted::Unrooted(_))
119    }
120
121    /// Get this reference as a [`Rooted<T>`], if it is rooted.
122    #[inline]
123    pub fn as_rooted(&self) -> Option<Rooted<T>> {
124        match self {
125            MaybeRooted::Rooted(r) => Some(*r),
126            MaybeRooted::Unrooted(_) => None,
127        }
128    }
129
130    /// Get this reference as a [`Rooted<T>`], panicking if it is not rooted.
131    ///
132    /// # Panics
133    ///
134    /// Panics if this reference is not rooted.
135    #[inline]
136    #[track_caller]
137    pub fn unwrap_rooted(&self) -> Rooted<T> {
138        self.as_rooted()
139            .expect("MaybeRooted::unwrap_rooted on a reference that is not rooted")
140    }
141
142    /// Get this reference as an [`Unrooted<T>`], if it is unrooted.
143    #[inline]
144    pub fn as_unrooted(&self) -> Option<Unrooted<T>> {
145        match self {
146            MaybeRooted::Rooted(_) => None,
147            MaybeRooted::Unrooted(r) => Some(*r),
148        }
149    }
150
151    /// Get this reference as an [`Unrooted<T>`], panicking if it is not
152    /// unrooted.
153    ///
154    /// # Panics
155    ///
156    /// Panics if this reference is not unrooted.
157    #[inline]
158    #[track_caller]
159    pub fn unwrap_unrooted(&self) -> Unrooted<T> {
160        self.as_unrooted()
161            .expect("MaybeRooted::unwrap_unrooted on a reference that is not unrooted")
162    }
163
164    /// Get this reference as a [`Rooted<T>`], or return an error if it is not
165    /// rooted.
166    ///
167    /// APIs that take GC values to store or pass along, such as
168    /// [`StructRef::new`](crate::StructRef::new), use this to check that their
169    /// values are rooted.
170    ///
171    /// # Errors
172    ///
173    /// Returns an error if this reference is not rooted.
174    pub fn validate_rooted(&self) -> Result<Rooted<T>> {
175        match self {
176            MaybeRooted::Rooted(r) => Ok(*r),
177            MaybeRooted::Unrooted(_) => bail!(
178                "expected a rooted GC reference, found an unrooted one; root it \
179                 first with `MaybeRooted::ensure_rooted` or `Val::ensure_rooted`"
180            ),
181        }
182    }
183
184    /// Root this reference in place, if it is not rooted already, in the
185    /// current LIFO rooting scope, and return it as a [`Rooted<T>`].
186    ///
187    /// Rooting a reference invalidates every other unrooted reference into the
188    /// store's GC heap; use [`Rooted::to_all_rooted`] or
189    /// [`Val::ensure_all_rooted`](crate::Val::ensure_all_rooted) to root
190    /// several references at once.
191    ///
192    /// # Errors
193    ///
194    /// Returns an error if this reference is unrooted and no longer valid.
195    ///
196    /// # Panics
197    ///
198    /// Panics if this reference is associated with a different store.
199    pub fn ensure_rooted(&mut self, mut store: impl AsContextMut) -> Result<Rooted<T>> {
200        self.ensure_rooted_(store.as_context_mut().0)
201    }
202
203    pub(crate) fn ensure_rooted_(&mut self, store: &mut StoreOpaque) -> Result<Rooted<T>> {
204        let rooted = self.to_rooted_(store)?;
205        *self = MaybeRooted::Rooted(rooted);
206        Ok(rooted)
207    }
208
209    /// Get a [`Rooted<T>`] referencing the same GC object as this reference:
210    /// this reference itself if it is rooted, or a new root in the current
211    /// LIFO rooting scope if it is unrooted.
212    ///
213    /// Rooting a reference invalidates every other unrooted reference into the
214    /// store's GC heap; use [`Rooted::to_all_rooted`] or
215    /// [`Val::ensure_all_rooted`](crate::Val::ensure_all_rooted) to root
216    /// several references at once.
217    ///
218    /// # Errors
219    ///
220    /// Returns an error if this reference is unrooted and no longer valid.
221    ///
222    /// # Panics
223    ///
224    /// Panics if this reference is associated with a different store.
225    pub fn to_rooted(&self, mut store: impl AsContextMut) -> Result<Rooted<T>> {
226        self.to_rooted_(store.as_context_mut().0)
227    }
228
229    pub(crate) fn to_rooted_(&self, store: &mut StoreOpaque) -> Result<Rooted<T>> {
230        match self {
231            MaybeRooted::Rooted(r) => {
232                assert!(
233                    r.comes_from_same_store(store),
234                    "object used with wrong store"
235                );
236                Ok(*r)
237            }
238            MaybeRooted::Unrooted(r) => r.to_rooted_(store),
239        }
240    }
241
242    /// Get an [`Unrooted<T>`] referencing the same GC object as this
243    /// reference.
244    ///
245    /// # Errors
246    ///
247    /// Returns an error if this reference is no longer valid: if it is rooted
248    /// and has since been unrooted, or if it is unrooted and the store's GC
249    /// heap has since changed.
250    ///
251    /// # Panics
252    ///
253    /// Panics if this reference is associated with a different store.
254    pub fn to_unrooted(&self, store: impl AsContext) -> Result<Unrooted<T>> {
255        self.to_unrooted_(store.as_context().0)
256    }
257
258    pub(crate) fn to_unrooted_(&self, store: &StoreOpaque) -> Result<Unrooted<T>> {
259        match self {
260            MaybeRooted::Rooted(r) => r.to_unrooted_(store),
261            MaybeRooted::Unrooted(r) => {
262                r.gc_ref(store)?;
263                Ok(*r)
264            }
265        }
266    }
267
268    /// Create an [`OwnedRooted<T>`] holding onto the same GC object as this
269    /// reference.
270    ///
271    /// # Errors
272    ///
273    /// Returns an error if this reference is no longer valid.
274    ///
275    /// This function will return an [`OutOfMemory`](crate::OutOfMemory)
276    /// error when memory allocation fails. See the `OutOfMemory` type's
277    /// documentation for details on Wasmtime's out-of-memory handling.
278    ///
279    /// # Panics
280    ///
281    /// Panics if this reference is associated with a different store.
282    pub fn to_owned_rooted(&self, mut store: impl AsContextMut) -> Result<OwnedRooted<T>> {
283        match self {
284            MaybeRooted::Rooted(r) => r.to_owned_rooted(store),
285            MaybeRooted::Unrooted(r) => r.to_owned_rooted_(store.as_context_mut().0),
286        }
287    }
288
289    pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
290        match self {
291            MaybeRooted::Rooted(r) => r.comes_from_same_store(store),
292            MaybeRooted::Unrooted(r) => r.comes_from_same_store(store),
293        }
294    }
295
296    /// The referenced object, if this reference is still valid.
297    ///
298    /// The result borrows `store`, so nothing can collect garbage or
299    /// otherwise mutate the GC heap while it is in use.
300    ///
301    /// # Panics
302    ///
303    /// Panics if this reference is associated with a different store.
304    pub(crate) fn try_gc_ref<'a>(&'a self, store: &'a StoreOpaque) -> Result<&'a VMGcRef> {
305        match self {
306            MaybeRooted::Rooted(r) => r.try_gc_ref(store),
307            MaybeRooted::Unrooted(r) => r.gc_ref(store),
308        }
309    }
310
311    /// Root this reference in place, if it is unrooted, after the caller has
312    /// checked that it is valid (with `try_gc_ref`), as part of rooting several
313    /// references at once; see `Unrooted::unchecked_gc_ref` for the
314    /// conditions.
315    pub(crate) fn ensure_rooted_unchecked(&mut self, store: &mut AutoAssertNoGc<'_>) {
316        if let MaybeRooted::Unrooted(r) = self {
317            *self = MaybeRooted::Rooted(r.to_rooted_unchecked(store));
318        }
319    }
320
321    /// The referenced object, cloned for storing it somewhere, if this
322    /// reference is rooted and still valid.
323    ///
324    /// Storing a reference mutates the store, so this is an error for an
325    /// unrooted reference.
326    ///
327    /// # Panics
328    ///
329    /// Panics if this reference is associated with a different store.
330    pub(crate) fn try_clone_gc_ref(&self, store: &mut AutoAssertNoGc<'_>) -> Result<VMGcRef> {
331        self.validate_rooted()?.try_clone_gc_ref(store)
332    }
333
334    /// The raw bits of this reference, exposed to Wasm, if this reference is
335    /// rooted and still valid.
336    ///
337    /// Exposing a reference to Wasm mutates the store, so this is an error for
338    /// an unrooted reference.
339    ///
340    /// # Panics
341    ///
342    /// Panics if this reference is associated with a different store.
343    pub(crate) fn to_raw_(&self, store: &mut AutoAssertNoGc<'_>) -> Result<u32> {
344        let gc_ref = self.try_clone_gc_ref(store)?;
345        let raw = match store.optional_gc_store_mut() {
346            Some(s) => s.expose_gc_ref_to_wasm(gc_ref)?,
347            None => {
348                // NB: do not force the allocation of a GC heap just because the
349                // program is using `i31ref`s.
350                debug_assert!(gc_ref.is_i31());
351                gc_ref.as_raw_non_zero_u32()
352            }
353        };
354        Ok(raw.get())
355    }
356
357    /// The raw bits of the optional reference `this`, exposed to Wasm; zero
358    /// for null.
359    pub(crate) fn option_to_raw(
360        this: Option<&Self>,
361        store: &mut AutoAssertNoGc<'_>,
362    ) -> Result<u32> {
363        match this {
364            Some(r) => r.to_raw_(store),
365            None => Ok(0),
366        }
367    }
368}
369
370impl MaybeRooted<AnyRef> {
371    /// The type of the referenced object; see [`AnyRef::ty`].
372    pub(crate) fn ty_(&self, store: &StoreOpaque) -> Result<HeapType> {
373        AnyRef::ty_of_(store, self.try_gc_ref(store)?)
374    }
375}