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}