Skip to main content

wasmtime/runtime/gc/
none_ref.rs

1use crate::prelude::*;
2use crate::{
3    HeapType, Ref, RefType, Result, Val, ValRaw, ValType, WasmTy,
4    store::{AutoAssertNoGc, StoreOpaque},
5};
6use core::convert::Infallible;
7use core::mem::MaybeUninit;
8
9/// A reference to the abstract `none` heap value.
10///
11/// The are no instances of `(ref none)`: it is an uninhabited type.
12///
13/// There is precisely one instance of `(ref null none)`, aka `nullref`: the
14/// null reference.
15///
16/// This `NoneRef` Rust type's sole purpose is for use with
17/// [`Func::wrap`][crate::Func::wrap]- and
18/// [`Func::typed`][crate::Func::typed]-style APIs for statically typing a
19/// function as taking or returning a `(ref null none)` (aka `Option<NoneRef>`)
20/// which is always `None`.
21///
22/// # Example
23///
24/// ```
25/// # use wasmtime::*;
26/// # fn _foo() -> Result<()> {
27/// let mut config = Config::new();
28/// config.wasm_function_references(true);
29/// config.wasm_gc(true);
30/// let engine = Engine::new(&config)?;
31///
32/// let module = Module::new(
33///     &engine,
34///     r#"
35///         (module
36///             (func (export "f") (param (ref null none))
37///                 ;; If the reference is null, return.
38///                 local.get 0
39///                 ref.is_null none
40///                 br_if 0
41///
42///                 ;; If the reference was not null (which is impossible)
43///                 ;; then raise a trap.
44///                 unreachable
45///             )
46///         )
47///     "#,
48/// )?;
49///
50/// let mut store = Store::new(&engine, ());
51/// let instance = Instance::new(&mut store, &module, &[])?;
52/// let f = instance.get_func(&mut store, "f").unwrap();
53///
54/// // We can cast a `(ref null none)`-taking function into a typed function that
55/// // takes an `Option<NoneRef>` via the `Func::typed` method.
56/// let f = f.typed::<Option<NoneRef>, ()>(&store)?;
57///
58/// // We can call the typed function, passing the null `none` reference.
59/// let result = f.call(&mut store, NoneRef::null());
60///
61/// // The function should not have trapped, because the reference we gave it was
62/// // null (as it had to be, since `NoneRef` is uninhabited).
63/// assert!(result.is_ok());
64/// # Ok(())
65/// # }
66/// ```
67#[derive(Copy, Clone, Debug, PartialEq, Eq)]
68pub struct NoneRef {
69    _inner: Infallible,
70}
71
72impl NoneRef {
73    /// Get the null `(ref null none)` (aka `nullexternref`) reference.
74    #[inline]
75    pub fn null() -> Option<Self> {
76        None
77    }
78
79    /// Get the null `(ref null none)` (aka `nullexternref`) reference as a
80    /// [`Ref`].
81    #[inline]
82    pub fn null_ref() -> Ref {
83        Ref::Extern(None)
84    }
85
86    /// Get the null `(ref null none)` (aka `nullexternref`) reference as a
87    /// [`Val`].
88    #[inline]
89    pub fn null_val() -> Val {
90        Val::ExternRef(None)
91    }
92}
93
94unsafe impl WasmTy for NoneRef {
95    #[inline]
96    fn valtype() -> ValType {
97        ValType::Ref(RefType::new(false, HeapType::None))
98    }
99
100    #[inline]
101    fn compatible_with_store(&self, _store: &StoreOpaque) -> bool {
102        match self._inner {}
103    }
104
105    #[inline]
106    fn dynamic_concrete_type_check(&self, _: &StoreOpaque, _: bool, _: &HeapType) -> Result<()> {
107        match self._inner {}
108    }
109
110    #[inline]
111    fn is_vmgcref_and_points_to_object(&self) -> bool {
112        match self._inner {}
113    }
114
115    fn store(self, _store: &mut AutoAssertNoGc<'_>, _ptr: &mut MaybeUninit<ValRaw>) -> Result<()> {
116        match self._inner {}
117    }
118
119    unsafe fn load(_store: &mut AutoAssertNoGc<'_>, _ptr: &ValRaw) -> Self {
120        unreachable!("NoneRef is uninhabited")
121    }
122}
123
124unsafe impl WasmTy for Option<NoneRef> {
125    #[inline]
126    fn valtype() -> ValType {
127        ValType::Ref(RefType::new(true, HeapType::None))
128    }
129
130    #[inline]
131    fn compatible_with_store(&self, _store: &StoreOpaque) -> bool {
132        true
133    }
134
135    #[inline]
136    fn dynamic_concrete_type_check(
137        &self,
138        _store: &StoreOpaque,
139        nullable: bool,
140        ty: &HeapType,
141    ) -> Result<()> {
142        if nullable {
143            // `(ref null none) <: (ref null $t)` for all struct and array
144            // types `$t`, and this method is only ever invoked with concrete
145            // types in the `any` type hierarchy, so there's no need to check
146            // for concrete function references or such here.
147            Ok(())
148        } else {
149            bail!("argument type mismatch: expected non-nullable (ref {ty}), found null reference")
150        }
151    }
152
153    #[inline]
154    fn store(self, _store: &mut AutoAssertNoGc<'_>, ptr: &mut MaybeUninit<ValRaw>) -> Result<()> {
155        ptr.write(ValRaw::externref(0));
156        Ok(())
157    }
158
159    #[inline]
160    unsafe fn load(_store: &mut AutoAssertNoGc<'_>, ptr: &ValRaw) -> Self {
161        debug_assert_eq!(ptr.get_externref(), 0);
162        None
163    }
164}