Skip to main content

wasmtime/runtime/
values.rs

1use crate::store::{AutoAssertNoGc, StoreOpaque};
2use crate::{
3    AnyRef, ArrayRef, AsContext, AsContextMut, EqRef, ExnRef, ExternRef, Func, HeapTopType,
4    HeapType, MaybeRooted, RefType, Rooted, StructRef, Unrooted, V128, ValType, prelude::*,
5};
6use core::ptr;
7
8pub use crate::runtime::vm::ValRaw;
9
10/// A stub implementation for continuation references.
11///
12/// This is a placeholder until continuation objects are fully integrated
13/// with the GC system (see #10248).
14#[derive(Debug, Clone, Copy)]
15pub struct ContRef;
16
17/// Possible runtime values that a WebAssembly module can either consume or
18/// produce.
19///
20/// Note that we inline the `enum Ref { ... }` variants into `enum Val { ... }`
21/// here as a size optimization.
22#[derive(Debug, Clone, Copy)]
23pub enum Val {
24    // NB: the ordering here is intended to match the ordering in
25    // `ValType` to improve codegen when learning the type of a value.
26    //
27    /// A 32-bit integer.
28    I32(i32),
29
30    /// A 64-bit integer.
31    I64(i64),
32
33    /// A 32-bit float.
34    ///
35    /// Note that the raw bits of the float are stored here, and you can use
36    /// `f32::from_bits` to create an `f32` value.
37    F32(u32),
38
39    /// A 64-bit float.
40    ///
41    /// Note that the raw bits of the float are stored here, and you can use
42    /// `f64::from_bits` to create an `f64` value.
43    F64(u64),
44
45    /// A 128-bit number.
46    V128(V128),
47
48    /// A function reference.
49    FuncRef(Option<Func>),
50
51    /// An external reference.
52    ExternRef(Option<MaybeRooted<ExternRef>>),
53
54    /// An internal reference.
55    AnyRef(Option<MaybeRooted<AnyRef>>),
56
57    /// An exception reference.
58    ExnRef(Option<MaybeRooted<ExnRef>>),
59
60    /// A continuation reference.
61    ///
62    /// Note: This is currently a stub implementation as continuation objects
63    /// are not yet fully integrated with the GC system. See #10248.
64    ContRef(Option<ContRef>),
65}
66
67macro_rules! accessors {
68    ($bind:ident $(($variant:ident($ty:ty) $get:ident $unwrap:ident $cvt:expr))*) => ($(
69        /// Attempt to access the underlying value of this `Val`, returning
70        /// `None` if it is not the correct type.
71        #[inline]
72        pub fn $get(&self) -> Option<$ty> {
73            if let Val::$variant($bind) = self {
74                Some($cvt)
75            } else {
76                None
77            }
78        }
79
80        /// Returns the underlying value of this `Val`, panicking if it's the
81        /// wrong type.
82        ///
83        /// # Panics
84        ///
85        /// Panics if `self` is not of the right type.
86        #[inline]
87        pub fn $unwrap(&self) -> $ty {
88            self.$get().expect(concat!("expected ", stringify!($ty)))
89        }
90    )*)
91}
92
93impl Val {
94    /// Returns the null reference for the given heap type.
95    #[inline]
96    pub fn null_ref(heap_type: &HeapType) -> Val {
97        Ref::null(&heap_type).into()
98    }
99
100    /// Returns the null function reference value.
101    ///
102    /// The return value has type `(ref null nofunc)` aka `nullfuncref` and is a
103    /// subtype of all function references.
104    #[inline]
105    pub const fn null_func_ref() -> Val {
106        Val::FuncRef(None)
107    }
108
109    /// Returns the null external reference value.
110    ///
111    /// The return value has type `(ref null noextern)` aka `nullexternref` and
112    /// is a subtype of all external references.
113    #[inline]
114    pub const fn null_extern_ref() -> Val {
115        Val::ExternRef(None)
116    }
117
118    /// Returns the null internal reference value.
119    ///
120    /// The return value has type `(ref null none)` aka `nullref` and is a
121    /// subtype of all internal references.
122    #[inline]
123    pub const fn null_any_ref() -> Val {
124        Val::AnyRef(None)
125    }
126
127    /// Returns the default value for the given type, if any exists.
128    ///
129    /// Returns `None` if there is no default value for the given type (for
130    /// example, non-nullable reference types do not have a default value).
131    pub fn default_for_ty(ty: &ValType) -> Option<Val> {
132        match ty {
133            ValType::I32 => Some(Val::I32(0)),
134            ValType::I64 => Some(Val::I64(0)),
135            ValType::F32 => Some(Val::F32(0)),
136            ValType::F64 => Some(Val::F64(0)),
137            ValType::V128 => Some(Val::V128(V128::from(0))),
138            ValType::Ref(ref_ty) => {
139                if ref_ty.is_nullable() {
140                    Some(Val::null_ref(ref_ty.heap_type()))
141                } else {
142                    None
143                }
144            }
145        }
146    }
147
148    /// Returns the corresponding [`ValType`] for this `Val`.
149    ///
150    /// # Errors
151    ///
152    /// Returns an error if this value is a GC reference that has since been
153    /// unrooted.
154    ///
155    /// # Panics
156    ///
157    /// Panics if this value is associated with a different store.
158    #[inline]
159    pub fn ty(&self, store: impl AsContext) -> Result<ValType> {
160        self.load_ty(&store.as_context().0)
161    }
162
163    #[inline]
164    pub(crate) fn load_ty(&self, store: &StoreOpaque) -> Result<ValType> {
165        Ok(match self {
166            Val::I32(_) => ValType::I32,
167            Val::I64(_) => ValType::I64,
168            Val::F32(_) => ValType::F32,
169            Val::F64(_) => ValType::F64,
170            Val::V128(_) => ValType::V128,
171            Val::ExternRef(Some(e)) => {
172                e.try_gc_ref(store)?;
173                ValType::Ref(RefType::new(false, HeapType::Extern))
174            }
175            Val::ExternRef(None) => ValType::NULLEXTERNREF,
176            Val::FuncRef(None) => ValType::NULLFUNCREF,
177            Val::FuncRef(Some(f)) => ValType::Ref(RefType::new(
178                false,
179                HeapType::ConcreteFunc(f.load_ty(store)),
180            )),
181            Val::AnyRef(None) => ValType::NULLREF,
182            Val::AnyRef(Some(a)) => ValType::Ref(RefType::new(false, a.ty_(store)?)),
183            Val::ExnRef(None) => ValType::NULLEXNREF,
184            Val::ExnRef(Some(e)) => {
185                e.try_gc_ref(store)?;
186                ValType::Ref(RefType::new(false, HeapType::Exn))
187            }
188            Val::ContRef(_) => {
189                // TODO(#10248): Return proper continuation reference type when available
190                return Err(crate::format_err!(
191                    "continuation references not yet supported in embedder API"
192                ));
193            }
194        })
195    }
196
197    /// Does this value match the given type?
198    ///
199    /// Returns an error is an underlying `Rooted` has been unrooted.
200    ///
201    /// # Panics
202    ///
203    /// Panics if this value is not associated with the given store.
204    pub fn matches_ty(&self, store: impl AsContext, ty: &ValType) -> Result<bool> {
205        self._matches_ty(&store.as_context().0, ty)
206    }
207
208    pub(crate) fn _matches_ty(&self, store: &StoreOpaque, ty: &ValType) -> Result<bool> {
209        assert!(self.comes_from_same_store(store));
210        assert!(ty.comes_from_same_engine(store.engine()));
211        Ok(match (self, ty) {
212            (Val::I32(_), ValType::I32)
213            | (Val::I64(_), ValType::I64)
214            | (Val::F32(_), ValType::F32)
215            | (Val::F64(_), ValType::F64)
216            | (Val::V128(_), ValType::V128) => true,
217
218            (Val::FuncRef(f), ValType::Ref(ref_ty)) => Ref::from(*f)._matches_ty(store, ref_ty)?,
219            (Val::ExternRef(e), ValType::Ref(ref_ty)) => {
220                Ref::from(*e)._matches_ty(store, ref_ty)?
221            }
222            (Val::AnyRef(a), ValType::Ref(ref_ty)) => Ref::from(*a)._matches_ty(store, ref_ty)?,
223            (Val::ExnRef(e), ValType::Ref(ref_ty)) => Ref::from(*e)._matches_ty(store, ref_ty)?,
224
225            (Val::I32(_), _)
226            | (Val::I64(_), _)
227            | (Val::F32(_), _)
228            | (Val::F64(_), _)
229            | (Val::V128(_), _)
230            | (Val::FuncRef(_), _)
231            | (Val::ExternRef(_), _)
232            | (Val::AnyRef(_), _)
233            | (Val::ExnRef(_), _)
234            | (Val::ContRef(_), _) => false,
235        })
236    }
237
238    pub(crate) fn ensure_matches_ty(&self, store: &StoreOpaque, ty: &ValType) -> Result<()> {
239        if !self.comes_from_same_store(store) {
240            bail!("value used with wrong store")
241        }
242        if !ty.comes_from_same_engine(store.engine()) {
243            bail!("type used with wrong engine")
244        }
245        if self._matches_ty(store, ty)? {
246            Ok(())
247        } else {
248            let actual_ty = self.load_ty(store)?;
249            bail!("type mismatch: expected {ty}, found {actual_ty}")
250        }
251    }
252
253    /// Convenience method to convert this [`Val`] into a [`ValRaw`].
254    ///
255    /// Returns an error if this value is a GC reference and the GC reference
256    /// has been unrooted.
257    ///
258    /// # Safety
259    ///
260    /// The returned [`ValRaw`] does not carry type information and is only safe
261    /// to use within the context of this store itself. For more information see
262    /// [`ExternRef::to_raw`] and [`Func::to_raw`].
263    pub fn to_raw(&self, mut store: impl AsContextMut) -> Result<ValRaw> {
264        let mut store = AutoAssertNoGc::new(store.as_context_mut().0);
265        self.to_raw_(&mut store)
266    }
267
268    pub(crate) fn to_raw_(&self, store: &mut AutoAssertNoGc) -> Result<ValRaw> {
269        match self {
270            Val::I32(i) => Ok(ValRaw::i32(*i)),
271            Val::I64(i) => Ok(ValRaw::i64(*i)),
272            Val::F32(u) => Ok(ValRaw::f32(*u)),
273            Val::F64(u) => Ok(ValRaw::f64(*u)),
274            Val::V128(b) => Ok(ValRaw::v128(b.as_u128())),
275            Val::ExternRef(e) => Ok(ValRaw::externref(MaybeRooted::option_to_raw(
276                e.as_ref(),
277                store,
278            )?)),
279            Val::AnyRef(e) => Ok(ValRaw::anyref(MaybeRooted::option_to_raw(
280                e.as_ref(),
281                store,
282            )?)),
283            Val::ExnRef(e) => Ok(ValRaw::exnref(MaybeRooted::option_to_raw(
284                e.as_ref(),
285                store,
286            )?)),
287            Val::FuncRef(f) => Ok(ValRaw::funcref(match f {
288                Some(f) => f.to_raw_(store),
289                None => ptr::null_mut(),
290            })),
291            Val::ContRef(_) => {
292                // TODO(#10248): Implement proper continuation reference to_raw conversion
293                Err(crate::format_err!(
294                    "continuation references not yet supported in to_raw conversion"
295                ))
296            }
297        }
298    }
299
300    /// Convenience method to convert a [`ValRaw`] into a [`Val`].
301    ///
302    /// GC references are rooted in the current LIFO rooting scope
303    /// ([`MaybeRooted::Rooted`]), since nothing else keeps a raw value's
304    /// object alive.
305    ///
306    /// # Unsafety
307    ///
308    /// This method is unsafe for the reasons that [`ExternRef::from_raw`] and
309    /// [`Func::from_raw`] are unsafe. Additionally there's no guarantee
310    /// otherwise that `raw` should have the type `ty` specified.
311    pub unsafe fn from_raw(mut store: impl AsContextMut, raw: ValRaw, ty: ValType) -> Val {
312        let mut store = AutoAssertNoGc::new(store.as_context_mut().0);
313        // SAFETY: `_from_raw` has the same contract as this function.
314        unsafe { Self::_from_raw(&mut store, raw, &ty) }
315    }
316
317    /// Same as [`Self::from_raw`], but with a monomorphic store.
318    pub(crate) unsafe fn _from_raw(
319        store: &mut AutoAssertNoGc<'_>,
320        raw: ValRaw,
321        ty: &ValType,
322    ) -> Val {
323        match ty {
324            ValType::I32 => Val::I32(raw.get_i32()),
325            ValType::I64 => Val::I64(raw.get_i64()),
326            ValType::F32 => Val::F32(raw.get_f32()),
327            ValType::F64 => Val::F64(raw.get_f64()),
328            ValType::V128 => Val::V128(raw.get_v128().into()),
329            ValType::Ref(ref_ty) => {
330                let ref_ = match ref_ty.heap_type() {
331                    // SAFETY: it's a safety contract of this function that the
332                    // funcref is valid and owned by the provided store.
333                    HeapType::Func | HeapType::ConcreteFunc(_) => unsafe {
334                        Func::_from_raw(store, raw.get_funcref()).into()
335                    },
336
337                    HeapType::NoFunc => Ref::Func(None),
338
339                    HeapType::NoCont | HeapType::ConcreteCont(_) | HeapType::Cont => {
340                        // TODO(#10248): Required to support stack switching in the embedder API.
341                        unimplemented!()
342                    }
343
344                    HeapType::Extern => ExternRef::_from_raw(store, raw.get_externref()).into(),
345
346                    HeapType::NoExtern => Ref::Extern(None),
347
348                    HeapType::Any
349                    | HeapType::Eq
350                    | HeapType::I31
351                    | HeapType::Array
352                    | HeapType::ConcreteArray(_)
353                    | HeapType::Struct
354                    | HeapType::ConcreteStruct(_) => {
355                        AnyRef::_from_raw(store, raw.get_anyref()).into()
356                    }
357
358                    HeapType::Exn => ExnRef::_from_raw(store, raw.get_exnref()).into(),
359                    HeapType::NoExn => Ref::Exn(None),
360
361                    HeapType::None => Ref::Any(None),
362                };
363                assert!(
364                    ref_ty.is_nullable() || !ref_.is_null(),
365                    "if the type is not nullable, we shouldn't get null; got \
366                     type = {ref_ty}, ref = {ref_:?}"
367                );
368                ref_.into()
369            }
370        }
371    }
372
373    /// Like [`Self::_from_raw`], but GC references are returned as unrooted
374    /// references, without changing the store's GC heap.
375    ///
376    /// # Safety
377    ///
378    /// Same as [`Self::from_raw`].
379    pub(crate) unsafe fn from_raw_unrooted_(
380        store: &mut StoreOpaque,
381        raw: ValRaw,
382        ty: &ValType,
383    ) -> Val {
384        let ref_ty = match ty {
385            ValType::I32 => return Val::I32(raw.get_i32()),
386            ValType::I64 => return Val::I64(raw.get_i64()),
387            ValType::F32 => return Val::F32(raw.get_f32()),
388            ValType::F64 => return Val::F64(raw.get_f64()),
389            ValType::V128 => return Val::V128(raw.get_v128().into()),
390            ValType::Ref(ref_ty) => ref_ty,
391        };
392        let ref_ = match ref_ty.heap_type().top() {
393            // SAFETY: it's a safety contract of this function that the funcref
394            // is valid and owned by the provided store.
395            HeapTopType::Func => unsafe { Func::_from_raw(store, raw.get_funcref()).into() },
396            HeapTopType::Extern => Ref::from(Unrooted::<ExternRef>::from_raw_u32(
397                store,
398                raw.get_externref(),
399            )),
400            HeapTopType::Any => {
401                Ref::from(Unrooted::<AnyRef>::from_raw_u32(store, raw.get_anyref()))
402            }
403            HeapTopType::Exn => {
404                Ref::from(Unrooted::<ExnRef>::from_raw_u32(store, raw.get_exnref()))
405            }
406            HeapTopType::Cont => {
407                // TODO(#10248): Required to support stack switching in the embedder API.
408                unimplemented!()
409            }
410        };
411        assert!(
412            ref_ty.is_nullable() || !ref_.is_null(),
413            "if the type is not nullable, we shouldn't get null; got \
414             type = {ref_ty}, ref = {ref_:?}"
415        );
416        ref_.into()
417    }
418
419    accessors! {
420        e
421        (I32(i32) i32 unwrap_i32 *e)
422        (I64(i64) i64 unwrap_i64 *e)
423        (F32(f32) f32 unwrap_f32 f32::from_bits(*e))
424        (F64(f64) f64 unwrap_f64 f64::from_bits(*e))
425        (FuncRef(Option<&Func>) func_ref unwrap_func_ref e.as_ref())
426        (ExternRef(Option<&MaybeRooted<ExternRef>>) extern_ref unwrap_extern_ref e.as_ref())
427        (AnyRef(Option<&MaybeRooted<AnyRef>>) any_ref unwrap_any_ref e.as_ref())
428        (V128(V128) v128 unwrap_v128 *e)
429    }
430
431    /// Get this value's underlying reference, if any.
432    #[inline]
433    pub fn ref_(self) -> Option<Ref> {
434        match self {
435            Val::FuncRef(f) => Some(Ref::Func(f)),
436            Val::ExternRef(e) => Some(Ref::Extern(e)),
437            Val::AnyRef(a) => Some(Ref::Any(a)),
438            Val::ExnRef(e) => Some(Ref::Exn(e)),
439            Val::I32(_) | Val::I64(_) | Val::F32(_) | Val::F64(_) | Val::V128(_) => None,
440            Val::ContRef(_) => None, // TODO(#10248): Return proper Ref::Cont when available
441        }
442    }
443
444    /// Attempt to access the underlying `externref` value of this `Val`.
445    ///
446    /// If this is not an `externref`, then `None` is returned.
447    ///
448    /// If this is a null `externref`, then `Some(None)` is returned.
449    ///
450    /// If this is a non-null `externref`, then `Some(Some(..))` is returned.
451    #[inline]
452    pub fn externref(&self) -> Option<Option<&MaybeRooted<ExternRef>>> {
453        match self {
454            Val::ExternRef(None) => Some(None),
455            Val::ExternRef(Some(e)) => Some(Some(e)),
456            _ => None,
457        }
458    }
459
460    /// Returns the underlying `externref` value of this `Val`, panicking if it's the
461    /// wrong type.
462    ///
463    /// If this is a null `externref`, then `None` is returned.
464    ///
465    /// If this is a non-null `externref`, then `Some(..)` is returned.
466    ///
467    /// # Panics
468    ///
469    /// Panics if `self` is not a (nullable) `externref`.
470    #[inline]
471    pub fn unwrap_externref(&self) -> Option<&MaybeRooted<ExternRef>> {
472        self.externref().expect("expected externref")
473    }
474
475    /// Attempt to access the underlying `anyref` value of this `Val`.
476    ///
477    /// If this is not an `anyref`, then `None` is returned.
478    ///
479    /// If this is a null `anyref`, then `Some(None)` is returned.
480    ///
481    /// If this is a non-null `anyref`, then `Some(Some(..))` is returned.
482    #[inline]
483    pub fn anyref(&self) -> Option<Option<&MaybeRooted<AnyRef>>> {
484        match self {
485            Val::AnyRef(None) => Some(None),
486            Val::AnyRef(Some(e)) => Some(Some(e)),
487            _ => None,
488        }
489    }
490
491    /// Returns the underlying `anyref` value of this `Val`, panicking if it's the
492    /// wrong type.
493    ///
494    /// If this is a null `anyref`, then `None` is returned.
495    ///
496    /// If this is a non-null `anyref`, then `Some(..)` is returned.
497    ///
498    /// # Panics
499    ///
500    /// Panics if `self` is not a (nullable) `anyref`.
501    #[inline]
502    pub fn unwrap_anyref(&self) -> Option<&MaybeRooted<AnyRef>> {
503        self.anyref().expect("expected anyref")
504    }
505
506    /// Attempt to access the underlying `exnref` value of this `Val`.
507    ///
508    /// If this is not an `exnref`, then `None` is returned.
509    ///
510    /// If this is a null `exnref`, then `Some(None)` is returned.
511    ///
512    /// If this is a non-null `exnref`, then `Some(Some(..))` is returned.
513    #[inline]
514    pub fn exnref(&self) -> Option<Option<&MaybeRooted<ExnRef>>> {
515        match self {
516            Val::ExnRef(None) => Some(None),
517            Val::ExnRef(Some(e)) => Some(Some(e)),
518            _ => None,
519        }
520    }
521
522    /// Returns the underlying `exnref` value of this `Val`, panicking if it's the
523    /// wrong type.
524    ///
525    /// If this is a null `exnref`, then `None` is returned.
526    ///
527    /// If this is a non-null `exnref`, then `Some(..)` is returned.
528    ///
529    /// # Panics
530    ///
531    /// Panics if `self` is not a (nullable) `exnref`.
532    #[inline]
533    pub fn unwrap_exnref(&self) -> Option<&MaybeRooted<ExnRef>> {
534        self.exnref().expect("expected exnref")
535    }
536
537    /// Attempt to access the underlying `funcref` value of this `Val`.
538    ///
539    /// If this is not an `funcref`, then `None` is returned.
540    ///
541    /// If this is a null `funcref`, then `Some(None)` is returned.
542    ///
543    /// If this is a non-null `funcref`, then `Some(Some(..))` is returned.
544    #[inline]
545    pub fn funcref(&self) -> Option<Option<&Func>> {
546        match self {
547            Val::FuncRef(None) => Some(None),
548            Val::FuncRef(Some(f)) => Some(Some(f)),
549            _ => None,
550        }
551    }
552
553    /// Returns the underlying `funcref` value of this `Val`, panicking if it's the
554    /// wrong type.
555    ///
556    /// If this is a null `funcref`, then `None` is returned.
557    ///
558    /// If this is a non-null `funcref`, then `Some(..)` is returned.
559    ///
560    /// # Panics
561    ///
562    /// Panics if `self` is not a (nullable) `funcref`.
563    #[inline]
564    pub fn unwrap_funcref(&self) -> Option<&Func> {
565        self.funcref().expect("expected funcref")
566    }
567
568    /// Root any unrooted GC reference in this value, in place, in the current
569    /// LIFO rooting scope.
570    ///
571    /// Afterwards, any GC reference in this value is a
572    /// [`MaybeRooted::Rooted`], and so stays valid until that scope exits.
573    /// Values that are not GC references, or that are already rooted, are left
574    /// unchanged.
575    ///
576    /// Rooting a reference invalidates every other unrooted reference into the
577    /// store's GC heap; use [`Val::ensure_all_rooted`] to root several values
578    /// at once.
579    ///
580    /// # Errors
581    ///
582    /// Returns an error if this value holds an unrooted GC reference that is
583    /// no longer valid.
584    ///
585    /// # Panics
586    ///
587    /// Panics if this value is associated with a different store.
588    pub fn ensure_rooted(&mut self, mut store: impl AsContextMut) -> Result<()> {
589        self.ensure_rooted_(store.as_context_mut().0)
590    }
591
592    pub(crate) fn ensure_rooted_(&mut self, store: &mut StoreOpaque) -> Result<()> {
593        match self {
594            Val::ExternRef(Some(r)) => {
595                r.ensure_rooted_(store)?;
596            }
597            Val::AnyRef(Some(r)) => {
598                r.ensure_rooted_(store)?;
599            }
600            Val::ExnRef(Some(r)) => {
601                r.ensure_rooted_(store)?;
602            }
603            // TODO: handle continuation references here once they are GC objects.
604            Val::I32(_)
605            | Val::I64(_)
606            | Val::F32(_)
607            | Val::F64(_)
608            | Val::V128(_)
609            | Val::FuncRef(_)
610            | Val::ExternRef(None)
611            | Val::AnyRef(None)
612            | Val::ExnRef(None)
613            | Val::ContRef(_) => {}
614        }
615        Ok(())
616    }
617
618    /// Root, in place, every GC reference in `vals` that is not rooted
619    /// already, in the current LIFO rooting scope; see [`Val::ensure_rooted`].
620    ///
621    /// Any single rooting operation, such as [`Val::ensure_rooted`],
622    /// changes the store's GC heap, and so invalidates *every*
623    /// unrooted reference into it, not just the one that was
624    /// rooted. Rooting a list of values one at a time therefore fails
625    /// at the second unrooted reference. This function solves for
626    /// that use-case by providing a batched rooting operation.
627    ///
628    /// See also [`Rooted::to_all_rooted`] and
629    /// [`OwnedRooted::to_all_owned_rooted`](crate::OwnedRooted::to_all_owned_rooted) for lists of [`Unrooted`]
630    /// references.
631    ///
632    /// # Errors
633    ///
634    /// Returns an error, and roots nothing, if any of `vals` holds an unrooted
635    /// GC reference that is no longer valid.
636    ///
637    /// # Panics
638    ///
639    /// Panics if any of `vals` is associated with a different store.
640    pub fn ensure_all_rooted(mut store: impl AsContextMut, vals: &mut [Val]) -> Result<()> {
641        let store = store.as_context_mut().0;
642        for val in vals.iter() {
643            match val {
644                Val::ExternRef(Some(r)) => {
645                    r.try_gc_ref(store)?;
646                }
647                Val::AnyRef(Some(r)) => {
648                    r.try_gc_ref(store)?;
649                }
650                Val::ExnRef(Some(r)) => {
651                    r.try_gc_ref(store)?;
652                }
653                // TODO: handle continuation references here once they are GC objects.
654                Val::I32(_)
655                | Val::I64(_)
656                | Val::F32(_)
657                | Val::F64(_)
658                | Val::V128(_)
659                | Val::FuncRef(_)
660                | Val::ExternRef(None)
661                | Val::AnyRef(None)
662                | Val::ExnRef(None)
663                | Val::ContRef(_) => {}
664            }
665        }
666        let mut store = AutoAssertNoGc::new(store);
667        for val in vals {
668            match val {
669                Val::ExternRef(Some(r)) => r.ensure_rooted_unchecked(&mut store),
670                Val::AnyRef(Some(r)) => r.ensure_rooted_unchecked(&mut store),
671                Val::ExnRef(Some(r)) => r.ensure_rooted_unchecked(&mut store),
672                // TODO: handle continuation references here once they are GC objects.
673                Val::I32(_)
674                | Val::I64(_)
675                | Val::F32(_)
676                | Val::F64(_)
677                | Val::V128(_)
678                | Val::FuncRef(_)
679                | Val::ExternRef(None)
680                | Val::AnyRef(None)
681                | Val::ExnRef(None)
682                | Val::ContRef(_) => {}
683            }
684        }
685        Ok(())
686    }
687
688    /// Return an error if this value holds a GC reference that is not rooted.
689    ///
690    /// APIs that take GC values to store or pass along, such as
691    /// [`StructRef::new`] or [`Func::call`], use this to check that their
692    /// values are rooted; see [`Val::ensure_rooted`].
693    ///
694    /// # Errors
695    ///
696    /// Returns an error if this value holds an unrooted GC reference.
697    pub fn validate_rooted(&self) -> Result<()> {
698        match self {
699            Val::ExternRef(Some(r)) => {
700                r.validate_rooted()?;
701            }
702            Val::AnyRef(Some(r)) => {
703                r.validate_rooted()?;
704            }
705            Val::ExnRef(Some(r)) => {
706                r.validate_rooted()?;
707            }
708            // TODO: handle continuation references here once they are GC objects.
709            Val::I32(_)
710            | Val::I64(_)
711            | Val::F32(_)
712            | Val::F64(_)
713            | Val::V128(_)
714            | Val::FuncRef(_)
715            | Val::ExternRef(None)
716            | Val::AnyRef(None)
717            | Val::ExnRef(None)
718            | Val::ContRef(_) => {}
719        }
720        Ok(())
721    }
722
723    /// Get a copy of this value in which any GC reference is rooted; see
724    /// [`Val::ensure_rooted`].
725    ///
726    /// # Errors
727    ///
728    /// Returns an error if this value holds an unrooted GC reference that is
729    /// no longer valid.
730    ///
731    /// # Panics
732    ///
733    /// Panics if this value is associated with a different store.
734    pub fn to_rooted(&self, store: impl AsContextMut) -> Result<Val> {
735        let mut val = *self;
736        val.ensure_rooted(store)?;
737        Ok(val)
738    }
739
740    /// Get a copy of this value in which any GC reference is unrooted, and so
741    /// valid until the store's GC heap next changes; see [`Unrooted`].
742    ///
743    /// # Errors
744    ///
745    /// Returns an error if this value holds a GC reference that is no longer
746    /// valid.
747    ///
748    /// # Panics
749    ///
750    /// Panics if this value is associated with a different store.
751    pub fn to_unrooted(&self, store: impl AsContext) -> Result<Val> {
752        let store = store.as_context().0;
753        Ok(match self {
754            Val::ExternRef(Some(r)) => Val::from(r.to_unrooted_(store)?),
755            Val::AnyRef(Some(r)) => Val::from(r.to_unrooted_(store)?),
756            Val::ExnRef(Some(r)) => Val::from(r.to_unrooted_(store)?),
757            // TODO: handle continuation references here once they are GC objects.
758            Val::I32(_)
759            | Val::I64(_)
760            | Val::F32(_)
761            | Val::F64(_)
762            | Val::V128(_)
763            | Val::FuncRef(_)
764            | Val::ExternRef(None)
765            | Val::AnyRef(None)
766            | Val::ExnRef(None)
767            | Val::ContRef(_) => *self,
768        })
769    }
770
771    #[inline]
772    pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
773        match self {
774            Val::FuncRef(Some(f)) => f.comes_from_same_store(store),
775            Val::FuncRef(None) => true,
776
777            Val::ExternRef(Some(x)) => x.comes_from_same_store(store),
778            Val::ExternRef(None) => true,
779
780            Val::AnyRef(Some(a)) => a.comes_from_same_store(store),
781            Val::AnyRef(None) => true,
782
783            Val::ExnRef(Some(e)) => e.comes_from_same_store(store),
784            Val::ExnRef(None) => true,
785
786            // Integers, floats, and vectors have no association with any
787            // particular store, so they're always considered as "yes I came
788            // from that store",
789            Val::I32(_) | Val::I64(_) | Val::F32(_) | Val::F64(_) | Val::V128(_) => true,
790
791            // Continuation references are not yet associated with stores
792            Val::ContRef(_) => true, // TODO(#10248): Proper store association when implemented
793        }
794    }
795}
796
797impl From<i32> for Val {
798    #[inline]
799    fn from(val: i32) -> Val {
800        Val::I32(val)
801    }
802}
803
804impl From<i64> for Val {
805    #[inline]
806    fn from(val: i64) -> Val {
807        Val::I64(val)
808    }
809}
810
811impl From<f32> for Val {
812    #[inline]
813    fn from(val: f32) -> Val {
814        Val::F32(val.to_bits())
815    }
816}
817
818impl From<f64> for Val {
819    #[inline]
820    fn from(val: f64) -> Val {
821        Val::F64(val.to_bits())
822    }
823}
824
825impl From<Ref> for Val {
826    #[inline]
827    fn from(val: Ref) -> Val {
828        match val {
829            Ref::Extern(e) => Val::ExternRef(e),
830            Ref::Func(f) => Val::FuncRef(f),
831            Ref::Any(a) => Val::AnyRef(a),
832            Ref::Exn(e) => Val::ExnRef(e),
833        }
834    }
835}
836
837impl From<Rooted<ExternRef>> for Val {
838    #[inline]
839    fn from(val: Rooted<ExternRef>) -> Val {
840        Val::ExternRef(Some(val.into()))
841    }
842}
843
844impl From<Option<Rooted<ExternRef>>> for Val {
845    #[inline]
846    fn from(val: Option<Rooted<ExternRef>>) -> Val {
847        Val::ExternRef(val.map(Into::into))
848    }
849}
850
851impl From<MaybeRooted<ExternRef>> for Val {
852    #[inline]
853    fn from(val: MaybeRooted<ExternRef>) -> Val {
854        Val::ExternRef(Some(val))
855    }
856}
857
858impl From<Option<MaybeRooted<ExternRef>>> for Val {
859    #[inline]
860    fn from(val: Option<MaybeRooted<ExternRef>>) -> Val {
861        Val::ExternRef(val)
862    }
863}
864
865impl From<Unrooted<ExternRef>> for Val {
866    #[inline]
867    fn from(val: Unrooted<ExternRef>) -> Val {
868        Val::ExternRef(Some(val.into()))
869    }
870}
871
872impl From<Option<Unrooted<ExternRef>>> for Val {
873    #[inline]
874    fn from(val: Option<Unrooted<ExternRef>>) -> Val {
875        Val::ExternRef(val.map(Into::into))
876    }
877}
878
879impl From<Rooted<AnyRef>> for Val {
880    #[inline]
881    fn from(val: Rooted<AnyRef>) -> Val {
882        Val::AnyRef(Some(val.into()))
883    }
884}
885
886impl From<Option<Rooted<AnyRef>>> for Val {
887    #[inline]
888    fn from(val: Option<Rooted<AnyRef>>) -> Val {
889        Val::AnyRef(val.map(Into::into))
890    }
891}
892
893impl From<MaybeRooted<AnyRef>> for Val {
894    #[inline]
895    fn from(val: MaybeRooted<AnyRef>) -> Val {
896        Val::AnyRef(Some(val))
897    }
898}
899
900impl From<Option<MaybeRooted<AnyRef>>> for Val {
901    #[inline]
902    fn from(val: Option<MaybeRooted<AnyRef>>) -> Val {
903        Val::AnyRef(val)
904    }
905}
906
907impl From<Unrooted<AnyRef>> for Val {
908    #[inline]
909    fn from(val: Unrooted<AnyRef>) -> Val {
910        Val::AnyRef(Some(val.into()))
911    }
912}
913
914impl From<Option<Unrooted<AnyRef>>> for Val {
915    #[inline]
916    fn from(val: Option<Unrooted<AnyRef>>) -> Val {
917        Val::AnyRef(val.map(Into::into))
918    }
919}
920
921impl From<Rooted<EqRef>> for Val {
922    #[inline]
923    fn from(val: Rooted<EqRef>) -> Val {
924        Val::AnyRef(Some(val.into()))
925    }
926}
927
928impl From<Option<Rooted<EqRef>>> for Val {
929    #[inline]
930    fn from(val: Option<Rooted<EqRef>>) -> Val {
931        Val::AnyRef(val.map(Into::into))
932    }
933}
934
935impl From<MaybeRooted<EqRef>> for Val {
936    #[inline]
937    fn from(val: MaybeRooted<EqRef>) -> Val {
938        Val::AnyRef(Some(val.into()))
939    }
940}
941
942impl From<Option<MaybeRooted<EqRef>>> for Val {
943    #[inline]
944    fn from(val: Option<MaybeRooted<EqRef>>) -> Val {
945        Val::AnyRef(val.map(Into::into))
946    }
947}
948
949impl From<Unrooted<EqRef>> for Val {
950    #[inline]
951    fn from(val: Unrooted<EqRef>) -> Val {
952        Val::AnyRef(Some(val.into()))
953    }
954}
955
956impl From<Option<Unrooted<EqRef>>> for Val {
957    #[inline]
958    fn from(val: Option<Unrooted<EqRef>>) -> Val {
959        Val::AnyRef(val.map(Into::into))
960    }
961}
962
963impl From<Rooted<StructRef>> for Val {
964    #[inline]
965    fn from(val: Rooted<StructRef>) -> Val {
966        Val::AnyRef(Some(val.into()))
967    }
968}
969
970impl From<Option<Rooted<StructRef>>> for Val {
971    #[inline]
972    fn from(val: Option<Rooted<StructRef>>) -> Val {
973        Val::AnyRef(val.map(Into::into))
974    }
975}
976
977impl From<MaybeRooted<StructRef>> for Val {
978    #[inline]
979    fn from(val: MaybeRooted<StructRef>) -> Val {
980        Val::AnyRef(Some(val.into()))
981    }
982}
983
984impl From<Option<MaybeRooted<StructRef>>> for Val {
985    #[inline]
986    fn from(val: Option<MaybeRooted<StructRef>>) -> Val {
987        Val::AnyRef(val.map(Into::into))
988    }
989}
990
991impl From<Unrooted<StructRef>> for Val {
992    #[inline]
993    fn from(val: Unrooted<StructRef>) -> Val {
994        Val::AnyRef(Some(val.into()))
995    }
996}
997
998impl From<Option<Unrooted<StructRef>>> for Val {
999    #[inline]
1000    fn from(val: Option<Unrooted<StructRef>>) -> Val {
1001        Val::AnyRef(val.map(Into::into))
1002    }
1003}
1004
1005impl From<Rooted<ArrayRef>> for Val {
1006    #[inline]
1007    fn from(val: Rooted<ArrayRef>) -> Val {
1008        Val::AnyRef(Some(val.into()))
1009    }
1010}
1011
1012impl From<Option<Rooted<ArrayRef>>> for Val {
1013    #[inline]
1014    fn from(val: Option<Rooted<ArrayRef>>) -> Val {
1015        Val::AnyRef(val.map(Into::into))
1016    }
1017}
1018
1019impl From<MaybeRooted<ArrayRef>> for Val {
1020    #[inline]
1021    fn from(val: MaybeRooted<ArrayRef>) -> Val {
1022        Val::AnyRef(Some(val.into()))
1023    }
1024}
1025
1026impl From<Option<MaybeRooted<ArrayRef>>> for Val {
1027    #[inline]
1028    fn from(val: Option<MaybeRooted<ArrayRef>>) -> Val {
1029        Val::AnyRef(val.map(Into::into))
1030    }
1031}
1032
1033impl From<Unrooted<ArrayRef>> for Val {
1034    #[inline]
1035    fn from(val: Unrooted<ArrayRef>) -> Val {
1036        Val::AnyRef(Some(val.into()))
1037    }
1038}
1039
1040impl From<Option<Unrooted<ArrayRef>>> for Val {
1041    #[inline]
1042    fn from(val: Option<Unrooted<ArrayRef>>) -> Val {
1043        Val::AnyRef(val.map(Into::into))
1044    }
1045}
1046
1047impl From<Rooted<ExnRef>> for Val {
1048    #[inline]
1049    fn from(val: Rooted<ExnRef>) -> Val {
1050        Val::ExnRef(Some(val.into()))
1051    }
1052}
1053
1054impl From<Option<Rooted<ExnRef>>> for Val {
1055    #[inline]
1056    fn from(val: Option<Rooted<ExnRef>>) -> Val {
1057        Val::ExnRef(val.map(Into::into))
1058    }
1059}
1060
1061impl From<MaybeRooted<ExnRef>> for Val {
1062    #[inline]
1063    fn from(val: MaybeRooted<ExnRef>) -> Val {
1064        Val::ExnRef(Some(val))
1065    }
1066}
1067
1068impl From<Option<MaybeRooted<ExnRef>>> for Val {
1069    #[inline]
1070    fn from(val: Option<MaybeRooted<ExnRef>>) -> Val {
1071        Val::ExnRef(val)
1072    }
1073}
1074
1075impl From<Unrooted<ExnRef>> for Val {
1076    #[inline]
1077    fn from(val: Unrooted<ExnRef>) -> Val {
1078        Val::ExnRef(Some(val.into()))
1079    }
1080}
1081
1082impl From<Option<Unrooted<ExnRef>>> for Val {
1083    #[inline]
1084    fn from(val: Option<Unrooted<ExnRef>>) -> Val {
1085        Val::ExnRef(val.map(Into::into))
1086    }
1087}
1088
1089impl From<Func> for Val {
1090    #[inline]
1091    fn from(val: Func) -> Val {
1092        Val::FuncRef(Some(val))
1093    }
1094}
1095
1096impl From<Option<Func>> for Val {
1097    #[inline]
1098    fn from(val: Option<Func>) -> Val {
1099        Val::FuncRef(val)
1100    }
1101}
1102
1103impl From<u128> for Val {
1104    #[inline]
1105    fn from(val: u128) -> Val {
1106        Val::V128(val.into())
1107    }
1108}
1109
1110impl From<V128> for Val {
1111    #[inline]
1112    fn from(val: V128) -> Val {
1113        Val::V128(val)
1114    }
1115}
1116
1117/// A reference.
1118///
1119/// References come in three broad flavors:
1120///
1121/// 1. Function references. These are references to a function that can be
1122///    invoked.
1123///
1124/// 2. External references. These are references to data that is external
1125///    and opaque to the Wasm guest, provided by the host.
1126///
1127/// 3. Internal references. These are references to allocations inside the
1128///    Wasm's heap, such as structs and arrays. These are part of the GC
1129///    proposal, and not yet implemented in Wasmtime.
1130///
1131/// At the Wasm level, there are nullable and non-nullable variants of each type
1132/// of reference. Both variants are represented with `Ref` at the Wasmtime API
1133/// level. For example, values of both `(ref extern)` and `(ref null extern)`
1134/// types will be represented as `Ref::Extern(Option<ExternRef>)` in the
1135/// Wasmtime API. Nullable references are represented as `Option<Ref>` where
1136/// null references are represented as `None`. Wasm can construct null
1137/// references via the `ref.null <heap-type>` instruction.
1138///
1139/// References are non-forgable: Wasm cannot create invalid references, for
1140/// example, by claiming that the integer `0xbad1bad2` is actually a reference.
1141#[derive(Debug, Clone)]
1142pub enum Ref {
1143    // NB: We have a variant for each of the type hierarchies defined in Wasm,
1144    // and push the `Option` that provides nullability into each variant. This
1145    // allows us to get the most-precise type of any reference value, whether it
1146    // is null or not, without any additional metadata.
1147    //
1148    // Consider if we instead had the nullability inside `Val::Ref` and each of
1149    // the `Ref` variants did not have an `Option`:
1150    //
1151    //     enum Val {
1152    //         Ref(Option<Ref>),
1153    //         // Etc...
1154    //     }
1155    //     enum Ref {
1156    //         Func(Func),
1157    //         External(ExternRef),
1158    //         // Etc...
1159    //     }
1160    //
1161    // In this scenario, what type would we return from `Val::ty` for
1162    // `Val::Ref(None)`? Because Wasm has multiple separate type hierarchies,
1163    // there is no single common bottom type for all the different kinds of
1164    // references. So in this scenario, `Val::Ref(None)` doesn't have enough
1165    // information to reconstruct the value's type. That's a problem for us
1166    // because we need to get a value's type at various times all over the code
1167    // base.
1168    //
1169    /// A first-class reference to a WebAssembly function.
1170    ///
1171    /// The host, or the Wasm guest, can invoke this function.
1172    ///
1173    /// The host can create function references via [`Func::new`] or
1174    /// [`Func::wrap`].
1175    ///
1176    /// The Wasm guest can create non-null function references via the
1177    /// `ref.func` instruction, or null references via the `ref.null func`
1178    /// instruction.
1179    Func(Option<Func>),
1180
1181    /// A reference to an value outside of the Wasm heap.
1182    ///
1183    /// These references are opaque to the Wasm itself. Wasm can't create
1184    /// non-null external references, nor do anything with them accept pass them
1185    /// around as function arguments and returns and place them into globals and
1186    /// tables.
1187    ///
1188    /// Wasm can create null external references via the `ref.null extern`
1189    /// instruction.
1190    Extern(Option<MaybeRooted<ExternRef>>),
1191
1192    /// An internal reference.
1193    ///
1194    /// The `AnyRef` type represents WebAssembly `anyref` values. These can be
1195    /// references to `struct`s and `array`s or inline/unboxed 31-bit
1196    /// integers.
1197    ///
1198    /// Unlike `externref`, Wasm guests can directly allocate `anyref`s, and
1199    /// does not need to rely on the host to do that.
1200    Any(Option<MaybeRooted<AnyRef>>),
1201
1202    /// An exception-object reference.
1203    ///
1204    /// The `ExnRef` type represents WebAssembly `exnref`
1205    /// values. These are references to exception objects as caught by
1206    /// `catch_ref` clauses on `try_table` instructions, or as
1207    /// allocated via the host API.
1208    Exn(Option<MaybeRooted<ExnRef>>),
1209}
1210
1211impl From<Func> for Ref {
1212    #[inline]
1213    fn from(f: Func) -> Ref {
1214        Ref::Func(Some(f))
1215    }
1216}
1217
1218impl From<Option<Func>> for Ref {
1219    #[inline]
1220    fn from(f: Option<Func>) -> Ref {
1221        Ref::Func(f)
1222    }
1223}
1224
1225impl From<Rooted<ExternRef>> for Ref {
1226    #[inline]
1227    fn from(e: Rooted<ExternRef>) -> Ref {
1228        Ref::Extern(Some(e.into()))
1229    }
1230}
1231
1232impl From<Option<Rooted<ExternRef>>> for Ref {
1233    #[inline]
1234    fn from(e: Option<Rooted<ExternRef>>) -> Ref {
1235        Ref::Extern(e.map(Into::into))
1236    }
1237}
1238
1239impl From<MaybeRooted<ExternRef>> for Ref {
1240    #[inline]
1241    fn from(e: MaybeRooted<ExternRef>) -> Ref {
1242        Ref::Extern(Some(e))
1243    }
1244}
1245
1246impl From<Option<MaybeRooted<ExternRef>>> for Ref {
1247    #[inline]
1248    fn from(e: Option<MaybeRooted<ExternRef>>) -> Ref {
1249        Ref::Extern(e)
1250    }
1251}
1252
1253impl From<Unrooted<ExternRef>> for Ref {
1254    #[inline]
1255    fn from(e: Unrooted<ExternRef>) -> Ref {
1256        Ref::Extern(Some(e.into()))
1257    }
1258}
1259
1260impl From<Option<Unrooted<ExternRef>>> for Ref {
1261    #[inline]
1262    fn from(e: Option<Unrooted<ExternRef>>) -> Ref {
1263        Ref::Extern(e.map(Into::into))
1264    }
1265}
1266
1267impl From<Rooted<AnyRef>> for Ref {
1268    #[inline]
1269    fn from(e: Rooted<AnyRef>) -> Ref {
1270        Ref::Any(Some(e.into()))
1271    }
1272}
1273
1274impl From<Option<Rooted<AnyRef>>> for Ref {
1275    #[inline]
1276    fn from(e: Option<Rooted<AnyRef>>) -> Ref {
1277        Ref::Any(e.map(Into::into))
1278    }
1279}
1280
1281impl From<MaybeRooted<AnyRef>> for Ref {
1282    #[inline]
1283    fn from(e: MaybeRooted<AnyRef>) -> Ref {
1284        Ref::Any(Some(e))
1285    }
1286}
1287
1288impl From<Option<MaybeRooted<AnyRef>>> for Ref {
1289    #[inline]
1290    fn from(e: Option<MaybeRooted<AnyRef>>) -> Ref {
1291        Ref::Any(e)
1292    }
1293}
1294
1295impl From<Unrooted<AnyRef>> for Ref {
1296    #[inline]
1297    fn from(e: Unrooted<AnyRef>) -> Ref {
1298        Ref::Any(Some(e.into()))
1299    }
1300}
1301
1302impl From<Option<Unrooted<AnyRef>>> for Ref {
1303    #[inline]
1304    fn from(e: Option<Unrooted<AnyRef>>) -> Ref {
1305        Ref::Any(e.map(Into::into))
1306    }
1307}
1308
1309impl From<Rooted<EqRef>> for Ref {
1310    #[inline]
1311    fn from(e: Rooted<EqRef>) -> Ref {
1312        Ref::Any(Some(e.into()))
1313    }
1314}
1315
1316impl From<Option<Rooted<EqRef>>> for Ref {
1317    #[inline]
1318    fn from(e: Option<Rooted<EqRef>>) -> Ref {
1319        Ref::Any(e.map(Into::into))
1320    }
1321}
1322
1323impl From<MaybeRooted<EqRef>> for Ref {
1324    #[inline]
1325    fn from(e: MaybeRooted<EqRef>) -> Ref {
1326        Ref::Any(Some(e.into()))
1327    }
1328}
1329
1330impl From<Option<MaybeRooted<EqRef>>> for Ref {
1331    #[inline]
1332    fn from(e: Option<MaybeRooted<EqRef>>) -> Ref {
1333        Ref::Any(e.map(Into::into))
1334    }
1335}
1336
1337impl From<Unrooted<EqRef>> for Ref {
1338    #[inline]
1339    fn from(e: Unrooted<EqRef>) -> Ref {
1340        Ref::Any(Some(e.into()))
1341    }
1342}
1343
1344impl From<Option<Unrooted<EqRef>>> for Ref {
1345    #[inline]
1346    fn from(e: Option<Unrooted<EqRef>>) -> Ref {
1347        Ref::Any(e.map(Into::into))
1348    }
1349}
1350
1351impl From<Rooted<StructRef>> for Ref {
1352    #[inline]
1353    fn from(e: Rooted<StructRef>) -> Ref {
1354        Ref::Any(Some(e.into()))
1355    }
1356}
1357
1358impl From<Option<Rooted<StructRef>>> for Ref {
1359    #[inline]
1360    fn from(e: Option<Rooted<StructRef>>) -> Ref {
1361        Ref::Any(e.map(Into::into))
1362    }
1363}
1364
1365impl From<MaybeRooted<StructRef>> for Ref {
1366    #[inline]
1367    fn from(e: MaybeRooted<StructRef>) -> Ref {
1368        Ref::Any(Some(e.into()))
1369    }
1370}
1371
1372impl From<Option<MaybeRooted<StructRef>>> for Ref {
1373    #[inline]
1374    fn from(e: Option<MaybeRooted<StructRef>>) -> Ref {
1375        Ref::Any(e.map(Into::into))
1376    }
1377}
1378
1379impl From<Unrooted<StructRef>> for Ref {
1380    #[inline]
1381    fn from(e: Unrooted<StructRef>) -> Ref {
1382        Ref::Any(Some(e.into()))
1383    }
1384}
1385
1386impl From<Option<Unrooted<StructRef>>> for Ref {
1387    #[inline]
1388    fn from(e: Option<Unrooted<StructRef>>) -> Ref {
1389        Ref::Any(e.map(Into::into))
1390    }
1391}
1392
1393impl From<Rooted<ArrayRef>> for Ref {
1394    #[inline]
1395    fn from(e: Rooted<ArrayRef>) -> Ref {
1396        Ref::Any(Some(e.into()))
1397    }
1398}
1399
1400impl From<Option<Rooted<ArrayRef>>> for Ref {
1401    #[inline]
1402    fn from(e: Option<Rooted<ArrayRef>>) -> Ref {
1403        Ref::Any(e.map(Into::into))
1404    }
1405}
1406
1407impl From<MaybeRooted<ArrayRef>> for Ref {
1408    #[inline]
1409    fn from(e: MaybeRooted<ArrayRef>) -> Ref {
1410        Ref::Any(Some(e.into()))
1411    }
1412}
1413
1414impl From<Option<MaybeRooted<ArrayRef>>> for Ref {
1415    #[inline]
1416    fn from(e: Option<MaybeRooted<ArrayRef>>) -> Ref {
1417        Ref::Any(e.map(Into::into))
1418    }
1419}
1420
1421impl From<Unrooted<ArrayRef>> for Ref {
1422    #[inline]
1423    fn from(e: Unrooted<ArrayRef>) -> Ref {
1424        Ref::Any(Some(e.into()))
1425    }
1426}
1427
1428impl From<Option<Unrooted<ArrayRef>>> for Ref {
1429    #[inline]
1430    fn from(e: Option<Unrooted<ArrayRef>>) -> Ref {
1431        Ref::Any(e.map(Into::into))
1432    }
1433}
1434
1435impl From<Rooted<ExnRef>> for Ref {
1436    #[inline]
1437    fn from(e: Rooted<ExnRef>) -> Ref {
1438        Ref::Exn(Some(e.into()))
1439    }
1440}
1441
1442impl From<Option<Rooted<ExnRef>>> for Ref {
1443    #[inline]
1444    fn from(e: Option<Rooted<ExnRef>>) -> Ref {
1445        Ref::Exn(e.map(Into::into))
1446    }
1447}
1448
1449impl From<MaybeRooted<ExnRef>> for Ref {
1450    #[inline]
1451    fn from(e: MaybeRooted<ExnRef>) -> Ref {
1452        Ref::Exn(Some(e))
1453    }
1454}
1455
1456impl From<Option<MaybeRooted<ExnRef>>> for Ref {
1457    #[inline]
1458    fn from(e: Option<MaybeRooted<ExnRef>>) -> Ref {
1459        Ref::Exn(e)
1460    }
1461}
1462
1463impl From<Unrooted<ExnRef>> for Ref {
1464    #[inline]
1465    fn from(e: Unrooted<ExnRef>) -> Ref {
1466        Ref::Exn(Some(e.into()))
1467    }
1468}
1469
1470impl From<Option<Unrooted<ExnRef>>> for Ref {
1471    #[inline]
1472    fn from(e: Option<Unrooted<ExnRef>>) -> Ref {
1473        Ref::Exn(e.map(Into::into))
1474    }
1475}
1476
1477impl Ref {
1478    /// Create a null reference to the given heap type.
1479    #[inline]
1480    pub fn null(heap_type: &HeapType) -> Self {
1481        match heap_type.top() {
1482            HeapTopType::Any => Ref::Any(None),
1483            HeapTopType::Extern => Ref::Extern(None),
1484            HeapTopType::Func => Ref::Func(None),
1485            HeapTopType::Exn => Ref::Exn(None),
1486            HeapTopType::Cont => unimplemented!("embedding API for `(ref cont)`"),
1487        }
1488    }
1489
1490    /// Is this a null reference?
1491    #[inline]
1492    pub fn is_null(&self) -> bool {
1493        match self {
1494            Ref::Any(None) | Ref::Extern(None) | Ref::Func(None) | Ref::Exn(None) => true,
1495            Ref::Any(Some(_)) | Ref::Extern(Some(_)) | Ref::Func(Some(_)) | Ref::Exn(Some(_)) => {
1496                false
1497            }
1498        }
1499    }
1500
1501    /// Is this a non-null reference?
1502    #[inline]
1503    pub fn is_non_null(&self) -> bool {
1504        !self.is_null()
1505    }
1506
1507    /// Is this an `extern` reference?
1508    #[inline]
1509    pub fn is_extern(&self) -> bool {
1510        matches!(self, Ref::Extern(_))
1511    }
1512
1513    /// Get the underlying `extern` reference, if any.
1514    ///
1515    /// Returns `None` if this `Ref` is not an `extern` reference, eg it is a
1516    /// `func` reference.
1517    ///
1518    /// Returns `Some(None)` if this `Ref` is a null `extern` reference.
1519    ///
1520    /// Returns `Some(Some(_))` if this `Ref` is a non-null `extern` reference.
1521    #[inline]
1522    pub fn as_extern(&self) -> Option<Option<&MaybeRooted<ExternRef>>> {
1523        match self {
1524            Ref::Extern(e) => Some(e.as_ref()),
1525            _ => None,
1526        }
1527    }
1528
1529    /// Get the underlying `extern` reference, panicking if this is a different
1530    /// kind of reference.
1531    ///
1532    /// Returns `None` if this `Ref` is a null `extern` reference.
1533    ///
1534    /// Returns `Some(_)` if this `Ref` is a non-null `extern` reference.
1535    #[inline]
1536    pub fn unwrap_extern(&self) -> Option<&MaybeRooted<ExternRef>> {
1537        self.as_extern()
1538            .expect("Ref::unwrap_extern on non-extern reference")
1539    }
1540
1541    /// Is this an `any` reference?
1542    #[inline]
1543    pub fn is_any(&self) -> bool {
1544        matches!(self, Ref::Any(_))
1545    }
1546
1547    /// Get the underlying `any` reference, if any.
1548    ///
1549    /// Returns `None` if this `Ref` is not an `any` reference, eg it is a
1550    /// `func` reference.
1551    ///
1552    /// Returns `Some(None)` if this `Ref` is a null `any` reference.
1553    ///
1554    /// Returns `Some(Some(_))` if this `Ref` is a non-null `any` reference.
1555    #[inline]
1556    pub fn as_any(&self) -> Option<Option<&MaybeRooted<AnyRef>>> {
1557        match self {
1558            Ref::Any(e) => Some(e.as_ref()),
1559            _ => None,
1560        }
1561    }
1562
1563    /// Get the underlying `any` reference, panicking if this is a different
1564    /// kind of reference.
1565    ///
1566    /// Returns `None` if this `Ref` is a null `any` reference.
1567    ///
1568    /// Returns `Some(_)` if this `Ref` is a non-null `any` reference.
1569    #[inline]
1570    pub fn unwrap_any(&self) -> Option<&MaybeRooted<AnyRef>> {
1571        self.as_any().expect("Ref::unwrap_any on non-any reference")
1572    }
1573
1574    /// Is this an `exn` reference?
1575    #[inline]
1576    pub fn is_exn(&self) -> bool {
1577        matches!(self, Ref::Exn(_))
1578    }
1579
1580    /// Get the underlying `exn` reference, if any.
1581    ///
1582    /// Returns `None` if this `Ref` is not an `exn` reference, eg it is a
1583    /// `func` reference.
1584    ///
1585    /// Returns `Some(None)` if this `Ref` is a null `exn` reference.
1586    ///
1587    /// Returns `Some(Some(_))` if this `Ref` is a non-null `exn` reference.
1588    #[inline]
1589    pub fn as_exn(&self) -> Option<Option<&MaybeRooted<ExnRef>>> {
1590        match self {
1591            Ref::Exn(e) => Some(e.as_ref()),
1592            _ => None,
1593        }
1594    }
1595
1596    /// Get the underlying `exn` reference, panicking if this is a different
1597    /// kind of reference.
1598    ///
1599    /// Returns `None` if this `Ref` is a null `exn` reference.
1600    ///
1601    /// Returns `Some(_)` if this `Ref` is a non-null `exn` reference.
1602    #[inline]
1603    pub fn unwrap_exn(&self) -> Option<&MaybeRooted<ExnRef>> {
1604        self.as_exn().expect("Ref::unwrap_exn on non-exn reference")
1605    }
1606
1607    /// Is this a `func` reference?
1608    #[inline]
1609    pub fn is_func(&self) -> bool {
1610        matches!(self, Ref::Func(_))
1611    }
1612
1613    /// Get the underlying `func` reference, if any.
1614    ///
1615    /// Returns `None` if this `Ref` is not an `func` reference, eg it is an
1616    /// `extern` reference.
1617    ///
1618    /// Returns `Some(None)` if this `Ref` is a null `func` reference.
1619    ///
1620    /// Returns `Some(Some(_))` if this `Ref` is a non-null `func` reference.
1621    #[inline]
1622    pub fn as_func(&self) -> Option<Option<&Func>> {
1623        match self {
1624            Ref::Func(f) => Some(f.as_ref()),
1625            _ => None,
1626        }
1627    }
1628
1629    /// Get the underlying `func` reference, panicking if this is a different
1630    /// kind of reference.
1631    ///
1632    /// Returns `None` if this `Ref` is a null `func` reference.
1633    ///
1634    /// Returns `Some(_)` if this `Ref` is a non-null `func` reference.
1635    #[inline]
1636    pub fn unwrap_func(&self) -> Option<&Func> {
1637        self.as_func()
1638            .expect("Ref::unwrap_func on non-func reference")
1639    }
1640
1641    /// Get the type of this reference.
1642    ///
1643    /// # Errors
1644    ///
1645    /// Return an error if this reference has been unrooted.
1646    ///
1647    /// # Panics
1648    ///
1649    /// Panics if this reference is associated with a different store.
1650    pub fn ty(&self, store: impl AsContext) -> Result<RefType> {
1651        self.load_ty(&store.as_context().0)
1652    }
1653
1654    pub(crate) fn load_ty(&self, store: &StoreOpaque) -> Result<RefType> {
1655        assert!(self.comes_from_same_store(store));
1656        Ok(RefType::new(
1657            self.is_null(),
1658            // NB: We choose the most-specific heap type we can here and let
1659            // subtyping do its thing if callers are matching against a
1660            // `HeapType::Func`.
1661            match self {
1662                Ref::Extern(None) => HeapType::NoExtern,
1663                Ref::Extern(Some(e)) => {
1664                    e.try_gc_ref(store)?;
1665                    HeapType::Extern
1666                }
1667
1668                Ref::Func(None) => HeapType::NoFunc,
1669                Ref::Func(Some(f)) => HeapType::ConcreteFunc(f.load_ty(store)),
1670
1671                Ref::Any(None) => HeapType::None,
1672                Ref::Any(Some(a)) => a.ty_(store)?,
1673
1674                Ref::Exn(None) => HeapType::NoExn,
1675                Ref::Exn(Some(e)) => {
1676                    e.try_gc_ref(store)?;
1677                    HeapType::Exn
1678                }
1679            },
1680        ))
1681    }
1682
1683    /// Does this reference value match the given type?
1684    ///
1685    /// Returns an error if the underlying `Rooted` has been unrooted.
1686    ///
1687    /// # Panics
1688    ///
1689    /// Panics if this reference is not associated with the given store.
1690    pub fn matches_ty(&self, store: impl AsContext, ty: &RefType) -> Result<bool> {
1691        self._matches_ty(&store.as_context().0, ty)
1692    }
1693
1694    pub(crate) fn _matches_ty(&self, store: &StoreOpaque, ty: &RefType) -> Result<bool> {
1695        assert!(self.comes_from_same_store(store));
1696        assert!(ty.comes_from_same_engine(store.engine()));
1697        if self.is_null() && !ty.is_nullable() {
1698            return Ok(false);
1699        }
1700        Ok(match (self, ty.heap_type()) {
1701            (Ref::Extern(Some(e)), HeapType::Extern) => {
1702                e.try_gc_ref(store)?;
1703                true
1704            }
1705            (Ref::Extern(None), HeapType::Extern) => true,
1706            (Ref::Extern(None), HeapType::NoExtern) => true,
1707            (Ref::Extern(_), _) => false,
1708
1709            (Ref::Func(_), HeapType::Func) => true,
1710            (Ref::Func(None), HeapType::NoFunc | HeapType::ConcreteFunc(_)) => true,
1711            (Ref::Func(Some(f)), HeapType::ConcreteFunc(func_ty)) => f._matches_ty(store, func_ty),
1712            (Ref::Func(_), _) => false,
1713
1714            (Ref::Any(Some(a)), ty) => a.ty_(store)?.matches(ty),
1715            (
1716                Ref::Any(None),
1717                HeapType::Any
1718                | HeapType::None
1719                | HeapType::I31
1720                | HeapType::ConcreteStruct(_)
1721                | HeapType::Struct
1722                | HeapType::ConcreteArray(_)
1723                | HeapType::Array
1724                | HeapType::Eq,
1725            ) => true,
1726            (Ref::Any(None), _) => false,
1727
1728            (Ref::Exn(Some(e)), HeapType::Exn) => {
1729                e.try_gc_ref(store)?;
1730                true
1731            }
1732            (Ref::Exn(None), HeapType::Exn) => true,
1733            (Ref::Exn(None), HeapType::NoExn) => true,
1734            (Ref::Exn(_), _) => false,
1735        })
1736    }
1737
1738    pub(crate) fn ensure_matches_ty(&self, store: &StoreOpaque, ty: &RefType) -> Result<()> {
1739        if !self.comes_from_same_store(store) {
1740            bail!("reference used with wrong store")
1741        }
1742        if !ty.comes_from_same_engine(store.engine()) {
1743            bail!("type used with wrong engine")
1744        }
1745        if self._matches_ty(store, ty)? {
1746            Ok(())
1747        } else {
1748            let actual_ty = self.load_ty(store)?;
1749            bail!("type mismatch: expected {ty}, found {actual_ty}")
1750        }
1751    }
1752
1753    /// Root this reference, in place, if it is an unrooted GC reference; see
1754    /// [`Val::ensure_rooted`].
1755    ///
1756    /// # Errors
1757    ///
1758    /// Returns an error if this is an unrooted GC reference that is no longer
1759    /// valid.
1760    ///
1761    /// # Panics
1762    ///
1763    /// Panics if this reference is associated with a different store.
1764    pub fn ensure_rooted(&mut self, mut store: impl AsContextMut) -> Result<()> {
1765        let store = store.as_context_mut().0;
1766        match self {
1767            Ref::Extern(Some(r)) => {
1768                r.ensure_rooted_(store)?;
1769            }
1770            Ref::Any(Some(r)) => {
1771                r.ensure_rooted_(store)?;
1772            }
1773            Ref::Exn(Some(r)) => {
1774                r.ensure_rooted_(store)?;
1775            }
1776            Ref::Extern(None) | Ref::Any(None) | Ref::Exn(None) | Ref::Func(_) => {}
1777        }
1778        Ok(())
1779    }
1780
1781    /// Return an error if this is a GC reference that is not rooted; see
1782    /// [`Val::validate_rooted`].
1783    ///
1784    /// # Errors
1785    ///
1786    /// Returns an error if this is an unrooted GC reference.
1787    pub fn validate_rooted(&self) -> Result<()> {
1788        match self {
1789            Ref::Extern(Some(r)) => {
1790                r.validate_rooted()?;
1791            }
1792            Ref::Any(Some(r)) => {
1793                r.validate_rooted()?;
1794            }
1795            Ref::Exn(Some(r)) => {
1796                r.validate_rooted()?;
1797            }
1798            Ref::Extern(None) | Ref::Any(None) | Ref::Exn(None) | Ref::Func(_) => {}
1799        }
1800        Ok(())
1801    }
1802
1803    /// Get a copy of this reference that is rooted if it is a GC reference;
1804    /// see [`Ref::ensure_rooted`].
1805    ///
1806    /// # Errors
1807    ///
1808    /// Returns an error if this is an unrooted GC reference that is no longer
1809    /// valid.
1810    ///
1811    /// # Panics
1812    ///
1813    /// Panics if this reference is associated with a different store.
1814    pub fn to_rooted(&self, store: impl AsContextMut) -> Result<Ref> {
1815        let mut r = self.clone();
1816        r.ensure_rooted(store)?;
1817        Ok(r)
1818    }
1819
1820    /// Get a copy of this reference that is unrooted if it is a GC reference;
1821    /// see [`Val::to_unrooted`].
1822    ///
1823    /// # Errors
1824    ///
1825    /// Returns an error if this is a GC reference that is no longer valid.
1826    ///
1827    /// # Panics
1828    ///
1829    /// Panics if this reference is associated with a different store.
1830    pub fn to_unrooted(&self, store: impl AsContext) -> Result<Ref> {
1831        let store = store.as_context().0;
1832        Ok(match self {
1833            Ref::Extern(Some(r)) => Ref::from(r.to_unrooted_(store)?),
1834            Ref::Any(Some(r)) => Ref::from(r.to_unrooted_(store)?),
1835            Ref::Exn(Some(r)) => Ref::from(r.to_unrooted_(store)?),
1836            Ref::Extern(None) | Ref::Any(None) | Ref::Exn(None) | Ref::Func(_) => self.clone(),
1837        })
1838    }
1839
1840    pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
1841        match self {
1842            Ref::Func(Some(f)) => f.comes_from_same_store(store),
1843            Ref::Func(None) => true,
1844            Ref::Extern(Some(x)) => x.comes_from_same_store(store),
1845            Ref::Extern(None) => true,
1846            Ref::Any(Some(a)) => a.comes_from_same_store(store),
1847            Ref::Any(None) => true,
1848            Ref::Exn(Some(e)) => e.comes_from_same_store(store),
1849            Ref::Exn(None) => true,
1850        }
1851    }
1852}
1853
1854#[cfg(test)]
1855mod tests {
1856    use crate::*;
1857
1858    #[test]
1859    fn size_of_val() {
1860        // Try to keep tabs on the size of `Val` and make sure we don't grow its
1861        // size.
1862        let expected = if cfg!(target_arch = "x86_64")
1863            || cfg!(target_arch = "aarch64")
1864            || cfg!(target_arch = "s390x")
1865            || cfg!(target_arch = "riscv64")
1866            || cfg!(target_arch = "arm")
1867        {
1868            32
1869        } else if cfg!(target_arch = "x86") {
1870            28
1871        } else {
1872            panic!("unsupported architecture")
1873        };
1874        assert_eq!(std::mem::size_of::<Val>(), expected);
1875    }
1876
1877    #[test]
1878    fn size_of_ref() {
1879        // Try to keep tabs on the size of `Ref` and make sure we don't grow its
1880        // size.
1881        let expected = if cfg!(target_arch = "x86_64")
1882            || cfg!(target_arch = "aarch64")
1883            || cfg!(target_arch = "s390x")
1884            || cfg!(target_arch = "riscv64")
1885            || cfg!(target_arch = "arm")
1886        {
1887            32
1888        } else if cfg!(target_arch = "x86") {
1889            28
1890        } else {
1891            panic!("unsupported architecture")
1892        };
1893        assert_eq!(std::mem::size_of::<Ref>(), expected);
1894    }
1895
1896    #[test]
1897    #[should_panic]
1898    fn val_matches_ty_wrong_engine() {
1899        let e1 = Engine::default();
1900        let e2 = Engine::default();
1901
1902        let t1 = FuncType::new(&e1, None, None);
1903        let t2 = FuncType::new(&e2, None, None);
1904
1905        let mut s1 = Store::new(&e1, ());
1906        let f = Func::new(&mut s1, t1.clone(), |_caller, _args, _results| Ok(()));
1907
1908        // Should panic.
1909        let _ = Val::FuncRef(Some(f)).matches_ty(
1910            &s1,
1911            &ValType::Ref(RefType::new(true, HeapType::ConcreteFunc(t2))),
1912        );
1913    }
1914
1915    #[test]
1916    #[should_panic]
1917    fn ref_matches_ty_wrong_engine() {
1918        let e1 = Engine::default();
1919        let e2 = Engine::default();
1920
1921        let t1 = FuncType::new(&e1, None, None);
1922        let t2 = FuncType::new(&e2, None, None);
1923
1924        let mut s1 = Store::new(&e1, ());
1925        let f = Func::new(&mut s1, t1.clone(), |_caller, _args, _results| Ok(()));
1926
1927        // Should panic.
1928        let _ = Ref::Func(Some(f)).matches_ty(&s1, &RefType::new(true, HeapType::ConcreteFunc(t2)));
1929    }
1930}