wasmtime/runtime/
func.rs

1use crate::prelude::*;
2use crate::runtime::Uninhabited;
3use crate::runtime::vm::{
4    InterpreterRef, SendSyncPtr, StoreBox, VMArrayCallHostFuncContext, VMCommonStackInformation,
5    VMContext, VMFuncRef, VMFunctionImport, VMOpaqueContext, VMStoreContext,
6};
7use crate::store::{AutoAssertNoGc, StoreId, StoreOpaque};
8use crate::type_registry::RegisteredType;
9use crate::{
10    AsContext, AsContextMut, CallHook, Engine, Extern, FuncType, Instance, ModuleExport, Ref,
11    StoreContext, StoreContextMut, Val, ValRaw, ValType,
12};
13use alloc::sync::Arc;
14use core::ffi::c_void;
15#[cfg(feature = "async")]
16use core::future::Future;
17use core::mem::{self, MaybeUninit};
18use core::ptr::NonNull;
19use wasmtime_environ::VMSharedTypeIndex;
20
21/// A reference to the abstract `nofunc` heap value.
22///
23/// The are no instances of `(ref nofunc)`: it is an uninhabited type.
24///
25/// There is precisely one instance of `(ref null nofunc)`, aka `nullfuncref`:
26/// the null reference.
27///
28/// This `NoFunc` Rust type's sole purpose is for use with [`Func::wrap`]- and
29/// [`Func::typed`]-style APIs for statically typing a function as taking or
30/// returning a `(ref null nofunc)` (aka `Option<NoFunc>`) which is always
31/// `None`.
32///
33/// # Example
34///
35/// ```
36/// # use wasmtime::*;
37/// # fn _foo() -> Result<()> {
38/// let mut config = Config::new();
39/// config.wasm_function_references(true);
40/// let engine = Engine::new(&config)?;
41///
42/// let module = Module::new(
43///     &engine,
44///     r#"
45///         (module
46///             (func (export "f") (param (ref null nofunc))
47///                 ;; If the reference is null, return.
48///                 local.get 0
49///                 ref.is_null nofunc
50///                 br_if 0
51///
52///                 ;; If the reference was not null (which is impossible)
53///                 ;; then raise a trap.
54///                 unreachable
55///             )
56///         )
57///     "#,
58/// )?;
59///
60/// let mut store = Store::new(&engine, ());
61/// let instance = Instance::new(&mut store, &module, &[])?;
62/// let f = instance.get_func(&mut store, "f").unwrap();
63///
64/// // We can cast a `(ref null nofunc)`-taking function into a typed function that
65/// // takes an `Option<NoFunc>` via the `Func::typed` method.
66/// let f = f.typed::<Option<NoFunc>, ()>(&store)?;
67///
68/// // We can call the typed function, passing the null `nofunc` reference.
69/// let result = f.call(&mut store, NoFunc::null());
70///
71/// // The function should not have trapped, because the reference we gave it was
72/// // null (as it had to be, since `NoFunc` is uninhabited).
73/// assert!(result.is_ok());
74/// # Ok(())
75/// # }
76/// ```
77#[derive(Copy, Clone, Debug, PartialEq, Eq)]
78pub struct NoFunc {
79    _inner: Uninhabited,
80}
81
82impl NoFunc {
83    /// Get the null `(ref null nofunc)` (aka `nullfuncref`) reference.
84    #[inline]
85    pub fn null() -> Option<NoFunc> {
86        None
87    }
88
89    /// Get the null `(ref null nofunc)` (aka `nullfuncref`) reference as a
90    /// [`Ref`].
91    #[inline]
92    pub fn null_ref() -> Ref {
93        Ref::Func(None)
94    }
95
96    /// Get the null `(ref null nofunc)` (aka `nullfuncref`) reference as a
97    /// [`Val`].
98    #[inline]
99    pub fn null_val() -> Val {
100        Val::FuncRef(None)
101    }
102}
103
104/// A WebAssembly function which can be called.
105///
106/// This type typically represents an exported function from a WebAssembly
107/// module instance. In this case a [`Func`] belongs to an [`Instance`] and is
108/// loaded from there. A [`Func`] may also represent a host function as well in
109/// some cases, too.
110///
111/// Functions can be called in a few different ways, either synchronous or async
112/// and either typed or untyped (more on this below). Note that host functions
113/// are normally inserted directly into a [`Linker`](crate::Linker) rather than
114/// using this directly, but both options are available.
115///
116/// # `Func` and `async`
117///
118/// Functions from the perspective of WebAssembly are always synchronous. You
119/// might have an `async` function in Rust, however, which you'd like to make
120/// available from WebAssembly. Wasmtime supports asynchronously calling
121/// WebAssembly through native stack switching. You can get some more
122/// information about [asynchronous configs](crate::Config::async_support), but
123/// from the perspective of `Func` it's important to know that whether or not
124/// your [`Store`](crate::Store) is asynchronous will dictate whether you call
125/// functions through [`Func::call`] or [`Func::call_async`] (or the typed
126/// wrappers such as [`TypedFunc::call`] vs [`TypedFunc::call_async`]).
127///
128/// # To `Func::call` or to `Func::typed().call()`
129///
130/// There's a 2x2 matrix of methods to call [`Func`]. Invocations can either be
131/// asynchronous or synchronous. They can also be statically typed or not.
132/// Whether or not an invocation is asynchronous is indicated via the method
133/// being `async` and [`call_async`](Func::call_async) being the entry point.
134/// Otherwise for statically typed or not your options are:
135///
136/// * Dynamically typed - if you don't statically know the signature of the
137///   function that you're calling you'll be using [`Func::call`] or
138///   [`Func::call_async`]. These functions take a variable-length slice of
139///   "boxed" arguments in their [`Val`] representation. Additionally the
140///   results are returned as an owned slice of [`Val`]. These methods are not
141///   optimized due to the dynamic type checks that must occur, in addition to
142///   some dynamic allocations for where to put all the arguments. While this
143///   allows you to call all possible wasm function signatures, if you're
144///   looking for a speedier alternative you can also use...
145///
146/// * Statically typed - if you statically know the type signature of the wasm
147///   function you're calling, then you'll want to use the [`Func::typed`]
148///   method to acquire an instance of [`TypedFunc`]. This structure is static proof
149///   that the underlying wasm function has the ascripted type, and type
150///   validation is only done once up-front. The [`TypedFunc::call`] and
151///   [`TypedFunc::call_async`] methods are much more efficient than [`Func::call`]
152///   and [`Func::call_async`] because the type signature is statically known.
153///   This eschews runtime checks as much as possible to get into wasm as fast
154///   as possible.
155///
156/// # Examples
157///
158/// One way to get a `Func` is from an [`Instance`] after you've instantiated
159/// it:
160///
161/// ```
162/// # use wasmtime::*;
163/// # fn main() -> anyhow::Result<()> {
164/// let engine = Engine::default();
165/// let module = Module::new(&engine, r#"(module (func (export "foo")))"#)?;
166/// let mut store = Store::new(&engine, ());
167/// let instance = Instance::new(&mut store, &module, &[])?;
168/// let foo = instance.get_func(&mut store, "foo").expect("export wasn't a function");
169///
170/// // Work with `foo` as a `Func` at this point, such as calling it
171/// // dynamically...
172/// match foo.call(&mut store, &[], &mut []) {
173///     Ok(()) => { /* ... */ }
174///     Err(trap) => {
175///         panic!("execution of `foo` resulted in a wasm trap: {}", trap);
176///     }
177/// }
178/// foo.call(&mut store, &[], &mut [])?;
179///
180/// // ... or we can make a static assertion about its signature and call it.
181/// // Our first call here can fail if the signatures don't match, and then the
182/// // second call can fail if the function traps (like the `match` above).
183/// let foo = foo.typed::<(), ()>(&store)?;
184/// foo.call(&mut store, ())?;
185/// # Ok(())
186/// # }
187/// ```
188///
189/// You can also use the [`wrap` function](Func::wrap) to create a
190/// `Func`
191///
192/// ```
193/// # use wasmtime::*;
194/// # fn main() -> anyhow::Result<()> {
195/// let mut store = Store::<()>::default();
196///
197/// // Create a custom `Func` which can execute arbitrary code inside of the
198/// // closure.
199/// let add = Func::wrap(&mut store, |a: i32, b: i32| -> i32 { a + b });
200///
201/// // Next we can hook that up to a wasm module which uses it.
202/// let module = Module::new(
203///     store.engine(),
204///     r#"
205///         (module
206///             (import "" "" (func $add (param i32 i32) (result i32)))
207///             (func (export "call_add_twice") (result i32)
208///                 i32.const 1
209///                 i32.const 2
210///                 call $add
211///                 i32.const 3
212///                 i32.const 4
213///                 call $add
214///                 i32.add))
215///     "#,
216/// )?;
217/// let instance = Instance::new(&mut store, &module, &[add.into()])?;
218/// let call_add_twice = instance.get_typed_func::<(), i32>(&mut store, "call_add_twice")?;
219///
220/// assert_eq!(call_add_twice.call(&mut store, ())?, 10);
221/// # Ok(())
222/// # }
223/// ```
224///
225/// Or you could also create an entirely dynamic `Func`!
226///
227/// ```
228/// # use wasmtime::*;
229/// # fn main() -> anyhow::Result<()> {
230/// let mut store = Store::<()>::default();
231///
232/// // Here we need to define the type signature of our `Double` function and
233/// // then wrap it up in a `Func`
234/// let double_type = wasmtime::FuncType::new(
235///     store.engine(),
236///     [wasmtime::ValType::I32].iter().cloned(),
237///     [wasmtime::ValType::I32].iter().cloned(),
238/// );
239/// let double = Func::new(&mut store, double_type, |_, params, results| {
240///     let mut value = params[0].unwrap_i32();
241///     value *= 2;
242///     results[0] = value.into();
243///     Ok(())
244/// });
245///
246/// let module = Module::new(
247///     store.engine(),
248///     r#"
249///         (module
250///             (import "" "" (func $double (param i32) (result i32)))
251///             (func $start
252///                 i32.const 1
253///                 call $double
254///                 drop)
255///             (start $start))
256///     "#,
257/// )?;
258/// let instance = Instance::new(&mut store, &module, &[double.into()])?;
259/// // .. work with `instance` if necessary
260/// # Ok(())
261/// # }
262/// ```
263#[derive(Copy, Clone, Debug)]
264#[repr(C)] // here for the C API
265pub struct Func {
266    /// The store that the below pointer belongs to.
267    ///
268    /// It's only safe to look at the contents of the pointer below when the
269    /// `StoreOpaque` matching this id is in-scope.
270    store: StoreId,
271
272    /// The raw `VMFuncRef`, whose lifetime is bound to the store this func
273    /// belongs to.
274    ///
275    /// Note that this field has an `unsafe_*` prefix to discourage use of it.
276    /// This is only safe to read/use if `self.store` is validated to belong to
277    /// an ambiently provided `StoreOpaque` or similar. Use the
278    /// `self.func_ref()` method instead of this field to perform this check.
279    unsafe_func_ref: SendSyncPtr<VMFuncRef>,
280}
281
282// Double-check that the C representation in `extern.h` matches our in-Rust
283// representation here in terms of size/alignment/etc.
284const _: () = {
285    #[repr(C)]
286    struct C(u64, *mut u8);
287    assert!(core::mem::size_of::<C>() == core::mem::size_of::<Func>());
288    assert!(core::mem::align_of::<C>() == core::mem::align_of::<Func>());
289    assert!(core::mem::offset_of!(Func, store) == 0);
290};
291
292macro_rules! for_each_function_signature {
293    ($mac:ident) => {
294        $mac!(0);
295        $mac!(1 A1);
296        $mac!(2 A1 A2);
297        $mac!(3 A1 A2 A3);
298        $mac!(4 A1 A2 A3 A4);
299        $mac!(5 A1 A2 A3 A4 A5);
300        $mac!(6 A1 A2 A3 A4 A5 A6);
301        $mac!(7 A1 A2 A3 A4 A5 A6 A7);
302        $mac!(8 A1 A2 A3 A4 A5 A6 A7 A8);
303        $mac!(9 A1 A2 A3 A4 A5 A6 A7 A8 A9);
304        $mac!(10 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10);
305        $mac!(11 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11);
306        $mac!(12 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12);
307        $mac!(13 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 A13);
308        $mac!(14 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 A13 A14);
309        $mac!(15 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 A13 A14 A15);
310        $mac!(16 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 A13 A14 A15 A16);
311        $mac!(17 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 A13 A14 A15 A16 A17);
312    };
313}
314
315mod typed;
316use crate::runtime::vm::VMStackChain;
317pub use typed::*;
318
319impl Func {
320    /// Creates a new `Func` with the given arguments, typically to create a
321    /// host-defined function to pass as an import to a module.
322    ///
323    /// * `store` - the store in which to create this [`Func`], which will own
324    ///   the return value.
325    ///
326    /// * `ty` - the signature of this function, used to indicate what the
327    ///   inputs and outputs are.
328    ///
329    /// * `func` - the native code invoked whenever this `Func` will be called.
330    ///   This closure is provided a [`Caller`] as its first argument to learn
331    ///   information about the caller, and then it's passed a list of
332    ///   parameters as a slice along with a mutable slice of where to write
333    ///   results.
334    ///
335    /// Note that the implementation of `func` must adhere to the `ty` signature
336    /// given, error or traps may occur if it does not respect the `ty`
337    /// signature. For example if the function type declares that it returns one
338    /// i32 but the `func` closures does not write anything into the results
339    /// slice then a trap may be generated.
340    ///
341    /// Additionally note that this is quite a dynamic function since signatures
342    /// are not statically known. For a more performant and ergonomic `Func`
343    /// it's recommended to use [`Func::wrap`] if you can because with
344    /// statically known signatures Wasmtime can optimize the implementation
345    /// much more.
346    ///
347    /// For more information about `Send + Sync + 'static` requirements on the
348    /// `func`, see [`Func::wrap`](#why-send--sync--static).
349    ///
350    /// # Errors
351    ///
352    /// The host-provided function here returns a
353    /// [`Result<()>`](anyhow::Result). If the function returns `Ok(())` then
354    /// that indicates that the host function completed successfully and wrote
355    /// the result into the `&mut [Val]` argument.
356    ///
357    /// If the function returns `Err(e)`, however, then this is equivalent to
358    /// the host function triggering a trap for wasm. WebAssembly execution is
359    /// immediately halted and the original caller of [`Func::call`], for
360    /// example, will receive the error returned here (possibly with
361    /// [`WasmBacktrace`](crate::WasmBacktrace) context information attached).
362    ///
363    /// For more information about errors in Wasmtime see the [`Trap`]
364    /// documentation.
365    ///
366    /// [`Trap`]: crate::Trap
367    ///
368    /// # Panics
369    ///
370    /// Panics if the given function type is not associated with this store's
371    /// engine.
372    pub fn new<T: 'static>(
373        store: impl AsContextMut<Data = T>,
374        ty: FuncType,
375        func: impl Fn(Caller<'_, T>, &[Val], &mut [Val]) -> Result<()> + Send + Sync + 'static,
376    ) -> Self {
377        assert!(ty.comes_from_same_engine(store.as_context().engine()));
378        let ty_clone = ty.clone();
379        unsafe {
380            Func::new_unchecked(store, ty, move |caller, values| {
381                Func::invoke_host_func_for_wasm(caller, &ty_clone, values, &func)
382            })
383        }
384    }
385
386    /// Creates a new [`Func`] with the given arguments, although has fewer
387    /// runtime checks than [`Func::new`].
388    ///
389    /// This function takes a callback of a different signature than
390    /// [`Func::new`], instead receiving a raw pointer with a list of [`ValRaw`]
391    /// structures. These values have no type information associated with them
392    /// so it's up to the caller to provide a function that will correctly
393    /// interpret the list of values as those coming from the `ty` specified.
394    ///
395    /// If you're calling this from Rust it's recommended to either instead use
396    /// [`Func::new`] or [`Func::wrap`]. The [`Func::wrap`] API, in particular,
397    /// is both safer and faster than this API.
398    ///
399    /// # Errors
400    ///
401    /// See [`Func::new`] for the behavior of returning an error from the host
402    /// function provided here.
403    ///
404    /// # Unsafety
405    ///
406    /// This function is not safe because it's not known at compile time that
407    /// the `func` provided correctly interprets the argument types provided to
408    /// it, or that the results it produces will be of the correct type.
409    ///
410    /// # Panics
411    ///
412    /// Panics if the given function type is not associated with this store's
413    /// engine.
414    pub unsafe fn new_unchecked<T: 'static>(
415        mut store: impl AsContextMut<Data = T>,
416        ty: FuncType,
417        func: impl Fn(Caller<'_, T>, &mut [ValRaw]) -> Result<()> + Send + Sync + 'static,
418    ) -> Self {
419        assert!(ty.comes_from_same_engine(store.as_context().engine()));
420        let store = store.as_context_mut().0;
421
422        // SAFETY: the contract required by `new_unchecked` is the same as the
423        // contract required by this function itself.
424        let host = unsafe { HostFunc::new_unchecked(store.engine(), ty, func) };
425
426        // SAFETY: the `T` used by `func` matches the `T` of the store we're
427        // inserting into via this function's type signature.
428        unsafe { host.into_func(store) }
429    }
430
431    /// Creates a new host-defined WebAssembly function which, when called,
432    /// will run the asynchronous computation defined by `func` to completion
433    /// and then return the result to WebAssembly.
434    ///
435    /// This function is the asynchronous analogue of [`Func::new`] and much of
436    /// that documentation applies to this as well. The key difference is that
437    /// `func` returns a future instead of simply a `Result`. Note that the
438    /// returned future can close over any of the arguments, but it cannot close
439    /// over the state of the closure itself. It's recommended to store any
440    /// necessary async state in the `T` of the [`Store<T>`](crate::Store) which
441    /// can be accessed through [`Caller::data`] or [`Caller::data_mut`].
442    ///
443    /// For more information on `Send + Sync + 'static`, see
444    /// [`Func::wrap`](#why-send--sync--static).
445    ///
446    /// # Panics
447    ///
448    /// This function will panic if `store` is not associated with an [async
449    /// config](crate::Config::async_support).
450    ///
451    /// Panics if the given function type is not associated with this store's
452    /// engine.
453    ///
454    /// # Errors
455    ///
456    /// See [`Func::new`] for the behavior of returning an error from the host
457    /// function provided here.
458    ///
459    /// # Examples
460    ///
461    /// ```
462    /// # use wasmtime::*;
463    /// # fn main() -> anyhow::Result<()> {
464    /// // Simulate some application-specific state as well as asynchronous
465    /// // functions to query that state.
466    /// struct MyDatabase {
467    ///     // ...
468    /// }
469    ///
470    /// impl MyDatabase {
471    ///     async fn get_row_count(&self) -> u32 {
472    ///         // ...
473    /// #       100
474    ///     }
475    /// }
476    ///
477    /// let my_database = MyDatabase {
478    ///     // ...
479    /// };
480    ///
481    /// // Using `new_async` we can hook up into calling our async
482    /// // `get_row_count` function.
483    /// let engine = Engine::new(Config::new().async_support(true))?;
484    /// let mut store = Store::new(&engine, MyDatabase {
485    ///     // ...
486    /// });
487    /// let get_row_count_type = wasmtime::FuncType::new(
488    ///     &engine,
489    ///     None,
490    ///     Some(wasmtime::ValType::I32),
491    /// );
492    /// let get = Func::new_async(&mut store, get_row_count_type, |caller, _params, results| {
493    ///     Box::new(async move {
494    ///         let count = caller.data().get_row_count().await;
495    ///         results[0] = Val::I32(count as i32);
496    ///         Ok(())
497    ///     })
498    /// });
499    /// // ...
500    /// # Ok(())
501    /// # }
502    /// ```
503    #[cfg(all(feature = "async", feature = "cranelift"))]
504    pub fn new_async<T, F>(store: impl AsContextMut<Data = T>, ty: FuncType, func: F) -> Func
505    where
506        F: for<'a> Fn(
507                Caller<'a, T>,
508                &'a [Val],
509                &'a mut [Val],
510            ) -> Box<dyn Future<Output = Result<()>> + Send + 'a>
511            + Send
512            + Sync
513            + 'static,
514        T: 'static,
515    {
516        assert!(
517            store.as_context().async_support(),
518            "cannot use `new_async` without enabling async support in the config"
519        );
520        assert!(ty.comes_from_same_engine(store.as_context().engine()));
521        return Func::new(
522            store,
523            ty,
524            move |Caller { store, caller }, params, results| {
525                store.with_blocking(|store, cx| {
526                    cx.block_on(core::pin::Pin::from(func(
527                        Caller { store, caller },
528                        params,
529                        results,
530                    )))
531                })?
532            },
533        );
534    }
535
536    /// Creates a new `Func` from a store and a funcref within that store.
537    ///
538    /// # Safety
539    ///
540    /// The safety of this function requires that `func_ref` is a valid function
541    /// pointer owned by `store`.
542    pub(crate) unsafe fn from_vm_func_ref(store: StoreId, func_ref: NonNull<VMFuncRef>) -> Func {
543        // SAFETY: given the contract of this function it's safe to read the
544        // `type_index` field.
545        unsafe {
546            debug_assert!(func_ref.as_ref().type_index != VMSharedTypeIndex::default());
547        }
548        Func {
549            store,
550            unsafe_func_ref: func_ref.into(),
551        }
552    }
553
554    /// Creates a new `Func` from the given Rust closure.
555    ///
556    /// This function will create a new `Func` which, when called, will
557    /// execute the given Rust closure. Unlike [`Func::new`] the target
558    /// function being called is known statically so the type signature can
559    /// be inferred. Rust types will map to WebAssembly types as follows:
560    ///
561    /// | Rust Argument Type                | WebAssembly Type                          |
562    /// |-----------------------------------|-------------------------------------------|
563    /// | `i32`                             | `i32`                                     |
564    /// | `u32`                             | `i32`                                     |
565    /// | `i64`                             | `i64`                                     |
566    /// | `u64`                             | `i64`                                     |
567    /// | `f32`                             | `f32`                                     |
568    /// | `f64`                             | `f64`                                     |
569    /// | `V128` on x86-64 and aarch64 only | `v128`                                    |
570    /// | `Option<Func>`                    | `funcref` aka `(ref null func)`           |
571    /// | `Func`                            | `(ref func)`                              |
572    /// | `Option<Nofunc>`                  | `nullfuncref` aka `(ref null nofunc)`     |
573    /// | `NoFunc`                          | `(ref nofunc)`                            |
574    /// | `Option<Rooted<ExternRef>>`       | `externref` aka `(ref null extern)`       |
575    /// | `Rooted<ExternRef>`               | `(ref extern)`                            |
576    /// | `Option<NoExtern>`                | `nullexternref` aka `(ref null noextern)` |
577    /// | `NoExtern`                        | `(ref noextern)`                          |
578    /// | `Option<Rooted<AnyRef>>`          | `anyref` aka `(ref null any)`             |
579    /// | `Rooted<AnyRef>`                  | `(ref any)`                               |
580    /// | `Option<Rooted<EqRef>>`           | `eqref` aka `(ref null eq)`               |
581    /// | `Rooted<EqRef>`                   | `(ref eq)`                                |
582    /// | `Option<I31>`                     | `i31ref` aka `(ref null i31)`             |
583    /// | `I31`                             | `(ref i31)`                               |
584    /// | `Option<Rooted<StructRef>>`       | `(ref null struct)`                       |
585    /// | `Rooted<StructRef>`               | `(ref struct)`                            |
586    /// | `Option<Rooted<ArrayRef>>`        | `(ref null array)`                        |
587    /// | `Rooted<ArrayRef>`                | `(ref array)`                             |
588    /// | `Option<NoneRef>`                 | `nullref` aka `(ref null none)`           |
589    /// | `NoneRef`                         | `(ref none)`                              |
590    ///
591    /// Note that anywhere a `Rooted<T>` appears, a `ManuallyRooted<T>` may also
592    /// be used.
593    ///
594    /// Any of the Rust types can be returned from the closure as well, in
595    /// addition to some extra types
596    ///
597    /// | Rust Return Type  | WebAssembly Return Type | Meaning               |
598    /// |-------------------|-------------------------|-----------------------|
599    /// | `()`              | nothing                 | no return value       |
600    /// | `T`               | `T`                     | a single return value |
601    /// | `(T1, T2, ...)`   | `T1 T2 ...`             | multiple returns      |
602    ///
603    /// Note that all return types can also be wrapped in `Result<_>` to
604    /// indicate that the host function can generate a trap as well as possibly
605    /// returning a value.
606    ///
607    /// Finally you can also optionally take [`Caller`] as the first argument of
608    /// your closure. If inserted then you're able to inspect the caller's
609    /// state, for example the [`Memory`](crate::Memory) it has exported so you
610    /// can read what pointers point to.
611    ///
612    /// Note that when using this API, the intention is to create as thin of a
613    /// layer as possible for when WebAssembly calls the function provided. With
614    /// sufficient inlining and optimization the WebAssembly will call straight
615    /// into `func` provided, with no extra fluff entailed.
616    ///
617    /// # Why `Send + Sync + 'static`?
618    ///
619    /// All host functions defined in a [`Store`](crate::Store) (including
620    /// those from [`Func::new`] and other constructors) require that the
621    /// `func` provided is `Send + Sync + 'static`. Additionally host functions
622    /// always are `Fn` as opposed to `FnMut` or `FnOnce`. This can at-a-glance
623    /// feel restrictive since the closure cannot close over as many types as
624    /// before. The reason for this, though, is to ensure that
625    /// [`Store<T>`](crate::Store) can implement both the `Send` and `Sync`
626    /// traits.
627    ///
628    /// Fear not, however, because this isn't as restrictive as it seems! Host
629    /// functions are provided a [`Caller<'_, T>`](crate::Caller) argument which
630    /// allows access to the host-defined data within the
631    /// [`Store`](crate::Store). The `T` type is not required to be any of
632    /// `Send`, `Sync`, or `'static`! This means that you can store whatever
633    /// you'd like in `T` and have it accessible by all host functions.
634    /// Additionally mutable access to `T` is allowed through
635    /// [`Caller::data_mut`].
636    ///
637    /// Most host-defined [`Func`] values provide closures that end up not
638    /// actually closing over any values. These zero-sized types will use the
639    /// context from [`Caller`] for host-defined information.
640    ///
641    /// # Errors
642    ///
643    /// The closure provided here to `wrap` can optionally return a
644    /// [`Result<T>`](anyhow::Result). Returning `Ok(t)` represents the host
645    /// function successfully completing with the `t` result. Returning
646    /// `Err(e)`, however, is equivalent to raising a custom wasm trap.
647    /// Execution of WebAssembly does not resume and the stack is unwound to the
648    /// original caller of the function where the error is returned.
649    ///
650    /// For more information about errors in Wasmtime see the [`Trap`]
651    /// documentation.
652    ///
653    /// [`Trap`]: crate::Trap
654    ///
655    /// # Examples
656    ///
657    /// First up we can see how simple wasm imports can be implemented, such
658    /// as a function that adds its two arguments and returns the result.
659    ///
660    /// ```
661    /// # use wasmtime::*;
662    /// # fn main() -> anyhow::Result<()> {
663    /// # let mut store = Store::<()>::default();
664    /// let add = Func::wrap(&mut store, |a: i32, b: i32| a + b);
665    /// let module = Module::new(
666    ///     store.engine(),
667    ///     r#"
668    ///         (module
669    ///             (import "" "" (func $add (param i32 i32) (result i32)))
670    ///             (func (export "foo") (param i32 i32) (result i32)
671    ///                 local.get 0
672    ///                 local.get 1
673    ///                 call $add))
674    ///     "#,
675    /// )?;
676    /// let instance = Instance::new(&mut store, &module, &[add.into()])?;
677    /// let foo = instance.get_typed_func::<(i32, i32), i32>(&mut store, "foo")?;
678    /// assert_eq!(foo.call(&mut store, (1, 2))?, 3);
679    /// # Ok(())
680    /// # }
681    /// ```
682    ///
683    /// We can also do the same thing, but generate a trap if the addition
684    /// overflows:
685    ///
686    /// ```
687    /// # use wasmtime::*;
688    /// # fn main() -> anyhow::Result<()> {
689    /// # let mut store = Store::<()>::default();
690    /// let add = Func::wrap(&mut store, |a: i32, b: i32| {
691    ///     match a.checked_add(b) {
692    ///         Some(i) => Ok(i),
693    ///         None => anyhow::bail!("overflow"),
694    ///     }
695    /// });
696    /// let module = Module::new(
697    ///     store.engine(),
698    ///     r#"
699    ///         (module
700    ///             (import "" "" (func $add (param i32 i32) (result i32)))
701    ///             (func (export "foo") (param i32 i32) (result i32)
702    ///                 local.get 0
703    ///                 local.get 1
704    ///                 call $add))
705    ///     "#,
706    /// )?;
707    /// let instance = Instance::new(&mut store, &module, &[add.into()])?;
708    /// let foo = instance.get_typed_func::<(i32, i32), i32>(&mut store, "foo")?;
709    /// assert_eq!(foo.call(&mut store, (1, 2))?, 3);
710    /// assert!(foo.call(&mut store, (i32::max_value(), 1)).is_err());
711    /// # Ok(())
712    /// # }
713    /// ```
714    ///
715    /// And don't forget all the wasm types are supported!
716    ///
717    /// ```
718    /// # use wasmtime::*;
719    /// # fn main() -> anyhow::Result<()> {
720    /// # let mut store = Store::<()>::default();
721    /// let debug = Func::wrap(&mut store, |a: i32, b: u32, c: f32, d: i64, e: u64, f: f64| {
722    ///
723    ///     println!("a={}", a);
724    ///     println!("b={}", b);
725    ///     println!("c={}", c);
726    ///     println!("d={}", d);
727    ///     println!("e={}", e);
728    ///     println!("f={}", f);
729    /// });
730    /// let module = Module::new(
731    ///     store.engine(),
732    ///     r#"
733    ///         (module
734    ///             (import "" "" (func $debug (param i32 i32 f32 i64 i64 f64)))
735    ///             (func (export "foo")
736    ///                 i32.const -1
737    ///                 i32.const 1
738    ///                 f32.const 2
739    ///                 i64.const -3
740    ///                 i64.const 3
741    ///                 f64.const 4
742    ///                 call $debug))
743    ///     "#,
744    /// )?;
745    /// let instance = Instance::new(&mut store, &module, &[debug.into()])?;
746    /// let foo = instance.get_typed_func::<(), ()>(&mut store, "foo")?;
747    /// foo.call(&mut store, ())?;
748    /// # Ok(())
749    /// # }
750    /// ```
751    ///
752    /// Finally if you want to get really fancy you can also implement
753    /// imports that read/write wasm module's memory
754    ///
755    /// ```
756    /// use std::str;
757    ///
758    /// # use wasmtime::*;
759    /// # fn main() -> anyhow::Result<()> {
760    /// # let mut store = Store::default();
761    /// let log_str = Func::wrap(&mut store, |mut caller: Caller<'_, ()>, ptr: i32, len: i32| {
762    ///     let mem = match caller.get_export("memory") {
763    ///         Some(Extern::Memory(mem)) => mem,
764    ///         _ => anyhow::bail!("failed to find host memory"),
765    ///     };
766    ///     let data = mem.data(&caller)
767    ///         .get(ptr as u32 as usize..)
768    ///         .and_then(|arr| arr.get(..len as u32 as usize));
769    ///     let string = match data {
770    ///         Some(data) => match str::from_utf8(data) {
771    ///             Ok(s) => s,
772    ///             Err(_) => anyhow::bail!("invalid utf-8"),
773    ///         },
774    ///         None => anyhow::bail!("pointer/length out of bounds"),
775    ///     };
776    ///     assert_eq!(string, "Hello, world!");
777    ///     println!("{}", string);
778    ///     Ok(())
779    /// });
780    /// let module = Module::new(
781    ///     store.engine(),
782    ///     r#"
783    ///         (module
784    ///             (import "" "" (func $log_str (param i32 i32)))
785    ///             (func (export "foo")
786    ///                 i32.const 4   ;; ptr
787    ///                 i32.const 13  ;; len
788    ///                 call $log_str)
789    ///             (memory (export "memory") 1)
790    ///             (data (i32.const 4) "Hello, world!"))
791    ///     "#,
792    /// )?;
793    /// let instance = Instance::new(&mut store, &module, &[log_str.into()])?;
794    /// let foo = instance.get_typed_func::<(), ()>(&mut store, "foo")?;
795    /// foo.call(&mut store, ())?;
796    /// # Ok(())
797    /// # }
798    /// ```
799    pub fn wrap<T, Params, Results>(
800        mut store: impl AsContextMut<Data = T>,
801        func: impl IntoFunc<T, Params, Results>,
802    ) -> Func
803    where
804        T: 'static,
805    {
806        let store = store.as_context_mut().0;
807        let host = HostFunc::wrap(store.engine(), func);
808
809        // SAFETY: The `T` the closure takes is the same as the `T` of the store
810        // we're inserting into via the type signature above.
811        unsafe { host.into_func(store) }
812    }
813
814    #[cfg(feature = "async")]
815    fn wrap_inner<F, T, Params, Results>(mut store: impl AsContextMut<Data = T>, func: F) -> Func
816    where
817        F: Fn(Caller<'_, T>, Params) -> Results + Send + Sync + 'static,
818        Params: WasmTyList,
819        Results: WasmRet,
820        T: 'static,
821    {
822        let store = store.as_context_mut().0;
823        let host = HostFunc::wrap_inner(store.engine(), func);
824
825        // SAFETY: The `T` the closure takes is the same as the `T` of the store
826        // we're inserting into via the type signature above.
827        unsafe { host.into_func(store) }
828    }
829
830    /// Same as [`Func::wrap`], except the closure asynchronously produces the
831    /// result and the arguments are passed within a tuple. For more information
832    /// see the [`Func`] documentation.
833    ///
834    /// # Panics
835    ///
836    /// This function will panic if called with a non-asynchronous store.
837    #[cfg(feature = "async")]
838    pub fn wrap_async<T, F, P, R>(store: impl AsContextMut<Data = T>, func: F) -> Func
839    where
840        F: for<'a> Fn(Caller<'a, T>, P) -> Box<dyn Future<Output = R> + Send + 'a>
841            + Send
842            + Sync
843            + 'static,
844        P: WasmTyList,
845        R: WasmRet,
846        T: 'static,
847    {
848        assert!(
849            store.as_context().async_support(),
850            concat!("cannot use `wrap_async` without enabling async support on the config")
851        );
852        Func::wrap_inner(store, move |Caller { store, caller }, args| {
853            match store.block_on(|store| func(Caller { store, caller }, args).into()) {
854                Ok(ret) => ret.into_fallible(),
855                Err(e) => R::fallible_from_error(e),
856            }
857        })
858    }
859
860    /// Returns the underlying wasm type that this `Func` has.
861    ///
862    /// # Panics
863    ///
864    /// Panics if `store` does not own this function.
865    pub fn ty(&self, store: impl AsContext) -> FuncType {
866        self.load_ty(&store.as_context().0)
867    }
868
869    /// Forcibly loads the type of this function from the `Engine`.
870    ///
871    /// Note that this is a somewhat expensive method since it requires taking a
872    /// lock as well as cloning a type.
873    pub(crate) fn load_ty(&self, store: &StoreOpaque) -> FuncType {
874        FuncType::from_shared_type_index(store.engine(), self.type_index(store))
875    }
876
877    /// Does this function match the given type?
878    ///
879    /// That is, is this function's type a subtype of the given type?
880    ///
881    /// # Panics
882    ///
883    /// Panics if this function is not associated with the given store or if the
884    /// function type is not associated with the store's engine.
885    pub fn matches_ty(&self, store: impl AsContext, func_ty: &FuncType) -> bool {
886        self._matches_ty(store.as_context().0, func_ty)
887    }
888
889    pub(crate) fn _matches_ty(&self, store: &StoreOpaque, func_ty: &FuncType) -> bool {
890        let actual_ty = self.load_ty(store);
891        actual_ty.matches(func_ty)
892    }
893
894    pub(crate) fn ensure_matches_ty(&self, store: &StoreOpaque, func_ty: &FuncType) -> Result<()> {
895        if !self.comes_from_same_store(store) {
896            bail!("function used with wrong store");
897        }
898        if self._matches_ty(store, func_ty) {
899            Ok(())
900        } else {
901            let actual_ty = self.load_ty(store);
902            bail!("type mismatch: expected {func_ty}, found {actual_ty}")
903        }
904    }
905
906    pub(crate) fn type_index(&self, data: &StoreOpaque) -> VMSharedTypeIndex {
907        unsafe { self.vm_func_ref(data).as_ref().type_index }
908    }
909
910    /// Invokes this function with the `params` given and writes returned values
911    /// to `results`.
912    ///
913    /// The `params` here must match the type signature of this `Func`, or an
914    /// error will occur. Additionally `results` must have the same
915    /// length as the number of results for this function. Calling this function
916    /// will synchronously execute the WebAssembly function referenced to get
917    /// the results.
918    ///
919    /// This function will return `Ok(())` if execution completed without a trap
920    /// or error of any kind. In this situation the results will be written to
921    /// the provided `results` array.
922    ///
923    /// # Errors
924    ///
925    /// Any error which occurs throughout the execution of the function will be
926    /// returned as `Err(e)`. The [`Error`](anyhow::Error) type can be inspected
927    /// for the precise error cause such as:
928    ///
929    /// * [`Trap`] - indicates that a wasm trap happened and execution was
930    ///   halted.
931    /// * [`WasmBacktrace`] - optionally included on errors for backtrace
932    ///   information of the trap/error.
933    /// * Other string-based errors to indicate issues such as type errors with
934    ///   `params`.
935    /// * Any host-originating error originally returned from a function defined
936    ///   via [`Func::new`], for example.
937    ///
938    /// Errors typically indicate that execution of WebAssembly was halted
939    /// mid-way and did not complete after the error condition happened.
940    ///
941    /// [`Trap`]: crate::Trap
942    ///
943    /// # Panics
944    ///
945    /// This function will panic if called on a function belonging to an async
946    /// store. Asynchronous stores must always use `call_async`. Also panics if
947    /// `store` does not own this function.
948    ///
949    /// [`WasmBacktrace`]: crate::WasmBacktrace
950    pub fn call(
951        &self,
952        mut store: impl AsContextMut,
953        params: &[Val],
954        results: &mut [Val],
955    ) -> Result<()> {
956        assert!(
957            !store.as_context().async_support(),
958            "must use `call_async` when async support is enabled on the config",
959        );
960        let mut store = store.as_context_mut();
961
962        self.call_impl_check_args(&mut store, params, results)?;
963
964        unsafe { self.call_impl_do_call(&mut store, params, results) }
965    }
966
967    /// Invokes this function in an "unchecked" fashion, reading parameters and
968    /// writing results to `params_and_returns`.
969    ///
970    /// This function is the same as [`Func::call`] except that the arguments
971    /// and results both use a different representation. If possible it's
972    /// recommended to use [`Func::call`] if safety isn't necessary or to use
973    /// [`Func::typed`] in conjunction with [`TypedFunc::call`] since that's
974    /// both safer and faster than this method of invoking a function.
975    ///
976    /// Note that if this function takes `externref` arguments then it will
977    /// **not** automatically GC unlike the [`Func::call`] and
978    /// [`TypedFunc::call`] functions. This means that if this function is
979    /// invoked many times with new `ExternRef` values and no other GC happens
980    /// via any other means then no values will get collected.
981    ///
982    /// # Errors
983    ///
984    /// For more information about errors see the [`Func::call`] documentation.
985    ///
986    /// # Unsafety
987    ///
988    /// This function is unsafe because the `params_and_returns` argument is not
989    /// validated at all. It must uphold invariants such as:
990    ///
991    /// * It's a valid pointer to an array
992    /// * It has enough space to store all parameters
993    /// * It has enough space to store all results (not at the same time as
994    ///   parameters)
995    /// * Parameters are initially written to the array and have the correct
996    ///   types and such.
997    /// * Reference types like `externref` and `funcref` are valid at the
998    ///   time of this call and for the `store` specified.
999    ///
1000    /// These invariants are all upheld for you with [`Func::call`] and
1001    /// [`TypedFunc::call`].
1002    pub unsafe fn call_unchecked(
1003        &self,
1004        mut store: impl AsContextMut,
1005        params_and_returns: *mut [ValRaw],
1006    ) -> Result<()> {
1007        let mut store = store.as_context_mut();
1008        let func_ref = self.vm_func_ref(store.0);
1009        let params_and_returns = NonNull::new(params_and_returns).unwrap_or(NonNull::from(&mut []));
1010
1011        // SAFETY: the safety of this function call is the same as the contract
1012        // of this function.
1013        unsafe { Self::call_unchecked_raw(&mut store, func_ref, params_and_returns) }
1014    }
1015
1016    pub(crate) unsafe fn call_unchecked_raw<T>(
1017        store: &mut StoreContextMut<'_, T>,
1018        func_ref: NonNull<VMFuncRef>,
1019        params_and_returns: NonNull<[ValRaw]>,
1020    ) -> Result<()> {
1021        // SAFETY: the safety of this function call is the same as the contract
1022        // of this function.
1023        invoke_wasm_and_catch_traps(store, |caller, vm| unsafe {
1024            VMFuncRef::array_call(func_ref, vm, caller, params_and_returns)
1025        })
1026    }
1027
1028    /// Converts the raw representation of a `funcref` into an `Option<Func>`
1029    ///
1030    /// This is intended to be used in conjunction with [`Func::new_unchecked`],
1031    /// [`Func::call_unchecked`], and [`ValRaw`] with its `funcref` field. This
1032    /// is the dual of [`Func::to_raw`].
1033    ///
1034    /// # Unsafety
1035    ///
1036    /// This function is not safe because `raw` is not validated at all. The
1037    /// caller must guarantee that `raw` is owned by the `store` provided and is
1038    /// valid within the `store`.
1039    pub unsafe fn from_raw(mut store: impl AsContextMut, raw: *mut c_void) -> Option<Func> {
1040        // SAFETY: this function's own contract is that `raw` is owned by store
1041        // to make this safe.
1042        unsafe { Self::_from_raw(store.as_context_mut().0, raw) }
1043    }
1044
1045    /// Same as `from_raw`, but with the internal `StoreOpaque` type.
1046    pub(crate) unsafe fn _from_raw(store: &mut StoreOpaque, raw: *mut c_void) -> Option<Func> {
1047        // SAFETY: this function's own contract is that `raw` is owned by store
1048        // to make this safe.
1049        unsafe {
1050            Some(Func::from_vm_func_ref(
1051                store.id(),
1052                NonNull::new(raw.cast())?,
1053            ))
1054        }
1055    }
1056
1057    /// Extracts the raw value of this `Func`, which is owned by `store`.
1058    ///
1059    /// This function returns a value that's suitable for writing into the
1060    /// `funcref` field of the [`ValRaw`] structure.
1061    ///
1062    /// # Safety
1063    ///
1064    /// The returned value is only valid for as long as the store is alive.
1065    /// This value is safe to pass to [`Func::from_raw`] so long as the same
1066    /// `store` is provided.
1067    pub fn to_raw(&self, mut store: impl AsContextMut) -> *mut c_void {
1068        self.vm_func_ref(store.as_context_mut().0).as_ptr().cast()
1069    }
1070
1071    /// Invokes this function with the `params` given, returning the results
1072    /// asynchronously.
1073    ///
1074    /// This function is the same as [`Func::call`] except that it is
1075    /// asynchronous. This is only compatible with stores associated with an
1076    /// [asynchronous config](crate::Config::async_support).
1077    ///
1078    /// It's important to note that the execution of WebAssembly will happen
1079    /// synchronously in the `poll` method of the future returned from this
1080    /// function. Wasmtime does not manage its own thread pool or similar to
1081    /// execute WebAssembly in. Future `poll` methods are generally expected to
1082    /// resolve quickly, so it's recommended that you run or poll this future
1083    /// in a "blocking context".
1084    ///
1085    /// For more information see the documentation on [asynchronous
1086    /// configs](crate::Config::async_support).
1087    ///
1088    /// # Errors
1089    ///
1090    /// For more information on errors see the [`Func::call`] documentation.
1091    ///
1092    /// # Panics
1093    ///
1094    /// Panics if this is called on a function in a synchronous store. This
1095    /// only works with functions defined within an asynchronous store. Also
1096    /// panics if `store` does not own this function.
1097    #[cfg(feature = "async")]
1098    pub async fn call_async(
1099        &self,
1100        mut store: impl AsContextMut<Data: Send>,
1101        params: &[Val],
1102        results: &mut [Val],
1103    ) -> Result<()> {
1104        let mut store = store.as_context_mut();
1105        assert!(
1106            store.0.async_support(),
1107            "cannot use `call_async` without enabling async support in the config",
1108        );
1109
1110        self.call_impl_check_args(&mut store, params, results)?;
1111
1112        let result = store
1113            .on_fiber(|store| unsafe { self.call_impl_do_call(store, params, results) })
1114            .await??;
1115        Ok(result)
1116    }
1117
1118    /// Perform dynamic checks that the arguments given to us match
1119    /// the signature of this function and are appropriate to pass to this
1120    /// function.
1121    ///
1122    /// This involves checking to make sure we have the right number and types
1123    /// of arguments as well as making sure everything is from the same `Store`.
1124    ///
1125    /// This must be called just before `call_impl_do_call`.
1126    fn call_impl_check_args<T>(
1127        &self,
1128        store: &mut StoreContextMut<'_, T>,
1129        params: &[Val],
1130        results: &mut [Val],
1131    ) -> Result<()> {
1132        let ty = self.load_ty(store.0);
1133        if ty.params().len() != params.len() {
1134            bail!(
1135                "expected {} arguments, got {}",
1136                ty.params().len(),
1137                params.len()
1138            );
1139        }
1140        if ty.results().len() != results.len() {
1141            bail!(
1142                "expected {} results, got {}",
1143                ty.results().len(),
1144                results.len()
1145            );
1146        }
1147
1148        for (ty, arg) in ty.params().zip(params) {
1149            arg.ensure_matches_ty(store.0, &ty)
1150                .context("argument type mismatch")?;
1151            if !arg.comes_from_same_store(store.0) {
1152                bail!("cross-`Store` values are not currently supported");
1153            }
1154        }
1155
1156        Ok(())
1157    }
1158
1159    /// Do the actual call into Wasm.
1160    ///
1161    /// # Safety
1162    ///
1163    /// You must have type checked the arguments by calling
1164    /// `call_impl_check_args` immediately before calling this function. It is
1165    /// only safe to call this function if that one did not return an error.
1166    unsafe fn call_impl_do_call<T>(
1167        &self,
1168        store: &mut StoreContextMut<'_, T>,
1169        params: &[Val],
1170        results: &mut [Val],
1171    ) -> Result<()> {
1172        // Store the argument values into `values_vec`.
1173        let ty = self.load_ty(store.0);
1174        let values_vec_size = params.len().max(ty.results().len());
1175        let mut values_vec = store.0.take_wasm_val_raw_storage();
1176        debug_assert!(values_vec.is_empty());
1177        values_vec.resize_with(values_vec_size, || ValRaw::v128(0));
1178        for (arg, slot) in params.iter().cloned().zip(&mut values_vec) {
1179            *slot = arg.to_raw(&mut *store)?;
1180        }
1181
1182        unsafe {
1183            self.call_unchecked(
1184                &mut *store,
1185                core::ptr::slice_from_raw_parts_mut(values_vec.as_mut_ptr(), values_vec_size),
1186            )?;
1187        }
1188
1189        for ((i, slot), val) in results.iter_mut().enumerate().zip(&values_vec) {
1190            let ty = ty.results().nth(i).unwrap();
1191            *slot = unsafe { Val::from_raw(&mut *store, *val, ty) };
1192        }
1193        values_vec.truncate(0);
1194        store.0.save_wasm_val_raw_storage(values_vec);
1195        Ok(())
1196    }
1197
1198    #[inline]
1199    pub(crate) fn vm_func_ref(&self, store: &StoreOpaque) -> NonNull<VMFuncRef> {
1200        self.store.assert_belongs_to(store.id());
1201        self.unsafe_func_ref.as_non_null()
1202    }
1203
1204    pub(crate) fn vmimport(&self, store: &StoreOpaque) -> VMFunctionImport {
1205        unsafe {
1206            let f = self.vm_func_ref(store);
1207            VMFunctionImport {
1208                // Note that this is a load-bearing `unwrap` here, but is
1209                // never expected to trip at runtime. The general problem is
1210                // that host functions do not have a `wasm_call` function so
1211                // the `VMFuncRef` type has an optional pointer there. This is
1212                // only able to be filled out when a function is "paired" with
1213                // a module where trampolines are present to fill out
1214                // `wasm_call` pointers.
1215                //
1216                // This pairing of modules doesn't happen explicitly but is
1217                // instead managed lazily throughout Wasmtime. Specifically the
1218                // way this works is one of:
1219                //
1220                // * When a host function is created the store's list of
1221                //   modules are searched for a wasm trampoline. If not found
1222                //   the `wasm_call` field is left blank.
1223                //
1224                // * When a module instantiation happens, which uses this
1225                //   function, the module will be used to fill any outstanding
1226                //   holes that it has trampolines for.
1227                //
1228                // This means that by the time we get to this point any
1229                // relevant holes should be filled out. Thus if this panic
1230                // actually triggers then it's indicative of a missing `fill`
1231                // call somewhere else.
1232                wasm_call: f.as_ref().wasm_call.unwrap(),
1233                array_call: f.as_ref().array_call,
1234                vmctx: f.as_ref().vmctx,
1235            }
1236        }
1237    }
1238
1239    pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
1240        self.store == store.id()
1241    }
1242
1243    fn invoke_host_func_for_wasm<T>(
1244        mut caller: Caller<'_, T>,
1245        ty: &FuncType,
1246        values_vec: &mut [ValRaw],
1247        func: &dyn Fn(Caller<'_, T>, &[Val], &mut [Val]) -> Result<()>,
1248    ) -> Result<()> {
1249        // Translate the raw JIT arguments in `values_vec` into a `Val` which
1250        // we'll be passing as a slice. The storage for our slice-of-`Val` we'll
1251        // be taking from the `Store`. We preserve our slice back into the
1252        // `Store` after the hostcall, ideally amortizing the cost of allocating
1253        // the storage across wasm->host calls.
1254        //
1255        // Note that we have a dynamic guarantee that `values_vec` is the
1256        // appropriate length to both read all arguments from as well as store
1257        // all results into.
1258        let mut val_vec = caller.store.0.take_hostcall_val_storage();
1259        debug_assert!(val_vec.is_empty());
1260        let nparams = ty.params().len();
1261        val_vec.reserve(nparams + ty.results().len());
1262        for (i, ty) in ty.params().enumerate() {
1263            val_vec.push(unsafe { Val::from_raw(&mut caller.store, values_vec[i], ty) })
1264        }
1265
1266        val_vec.extend((0..ty.results().len()).map(|_| Val::null_func_ref()));
1267        let (params, results) = val_vec.split_at_mut(nparams);
1268        func(caller.sub_caller(), params, results)?;
1269
1270        // Unlike our arguments we need to dynamically check that the return
1271        // values produced are correct. There could be a bug in `func` that
1272        // produces the wrong number, wrong types, or wrong stores of
1273        // values, and we need to catch that here.
1274        for (i, (ret, ty)) in results.iter().zip(ty.results()).enumerate() {
1275            ret.ensure_matches_ty(caller.store.0, &ty)
1276                .context("function attempted to return an incompatible value")?;
1277            values_vec[i] = ret.to_raw(&mut caller.store)?;
1278        }
1279
1280        // Restore our `val_vec` back into the store so it's usable for the next
1281        // hostcall to reuse our own storage.
1282        val_vec.truncate(0);
1283        caller.store.0.save_hostcall_val_storage(val_vec);
1284        Ok(())
1285    }
1286
1287    /// Attempts to extract a typed object from this `Func` through which the
1288    /// function can be called.
1289    ///
1290    /// This function serves as an alternative to [`Func::call`] and
1291    /// [`Func::call_async`]. This method performs a static type check (using
1292    /// the `Params` and `Results` type parameters on the underlying wasm
1293    /// function. If the type check passes then a `TypedFunc` object is returned,
1294    /// otherwise an error is returned describing the typecheck failure.
1295    ///
1296    /// The purpose of this relative to [`Func::call`] is that it's much more
1297    /// efficient when used to invoke WebAssembly functions. With the types
1298    /// statically known far less setup/teardown is required when invoking
1299    /// WebAssembly. If speed is desired then this function is recommended to be
1300    /// used instead of [`Func::call`] (which is more general, hence its
1301    /// slowdown).
1302    ///
1303    /// The `Params` type parameter is used to describe the parameters of the
1304    /// WebAssembly function. This can either be a single type (like `i32`), or
1305    /// a tuple of types representing the list of parameters (like `(i32, f32,
1306    /// f64)`). Additionally you can use `()` to represent that the function has
1307    /// no parameters.
1308    ///
1309    /// The `Results` type parameter is used to describe the results of the
1310    /// function. This behaves the same way as `Params`, but just for the
1311    /// results of the function.
1312    ///
1313    /// # Translating Between WebAssembly and Rust Types
1314    ///
1315    /// Translation between Rust types and WebAssembly types looks like:
1316    ///
1317    /// | WebAssembly                               | Rust                                  |
1318    /// |-------------------------------------------|---------------------------------------|
1319    /// | `i32`                                     | `i32` or `u32`                        |
1320    /// | `i64`                                     | `i64` or `u64`                        |
1321    /// | `f32`                                     | `f32`                                 |
1322    /// | `f64`                                     | `f64`                                 |
1323    /// | `externref` aka `(ref null extern)`       | `Option<Rooted<ExternRef>>`           |
1324    /// | `(ref extern)`                            | `Rooted<ExternRef>`                   |
1325    /// | `nullexternref` aka `(ref null noextern)` | `Option<NoExtern>`                    |
1326    /// | `(ref noextern)`                          | `NoExtern`                            |
1327    /// | `anyref` aka `(ref null any)`             | `Option<Rooted<AnyRef>>`              |
1328    /// | `(ref any)`                               | `Rooted<AnyRef>`                      |
1329    /// | `eqref` aka `(ref null eq)`               | `Option<Rooted<EqRef>>`               |
1330    /// | `(ref eq)`                                | `Rooted<EqRef>`                       |
1331    /// | `i31ref` aka `(ref null i31)`             | `Option<I31>`                         |
1332    /// | `(ref i31)`                               | `I31`                                 |
1333    /// | `structref` aka `(ref null struct)`       | `Option<Rooted<StructRef>>`           |
1334    /// | `(ref struct)`                            | `Rooted<StructRef>`                   |
1335    /// | `arrayref` aka `(ref null array)`         | `Option<Rooted<ArrayRef>>`            |
1336    /// | `(ref array)`                             | `Rooted<ArrayRef>`                    |
1337    /// | `nullref` aka `(ref null none)`           | `Option<NoneRef>`                     |
1338    /// | `(ref none)`                              | `NoneRef`                             |
1339    /// | `funcref` aka `(ref null func)`           | `Option<Func>`                        |
1340    /// | `(ref func)`                              | `Func`                                |
1341    /// | `(ref null <func type index>)`            | `Option<Func>`                        |
1342    /// | `(ref <func type index>)`                 | `Func`                                |
1343    /// | `nullfuncref` aka `(ref null nofunc)`     | `Option<NoFunc>`                      |
1344    /// | `(ref nofunc)`                            | `NoFunc`                              |
1345    /// | `v128`                                    | `V128` on `x86-64` and `aarch64` only |
1346    ///
1347    /// (Note that this mapping is the same as that of [`Func::wrap`], and that
1348    /// anywhere a `Rooted<T>` appears, a `ManuallyRooted<T>` may also appear).
1349    ///
1350    /// Note that once the [`TypedFunc`] return value is acquired you'll use either
1351    /// [`TypedFunc::call`] or [`TypedFunc::call_async`] as necessary to actually invoke
1352    /// the function. This method does not invoke any WebAssembly code, it
1353    /// simply performs a typecheck before returning the [`TypedFunc`] value.
1354    ///
1355    /// This method also has a convenience wrapper as
1356    /// [`Instance::get_typed_func`](crate::Instance::get_typed_func) to
1357    /// directly get a typed function value from an
1358    /// [`Instance`](crate::Instance).
1359    ///
1360    /// ## Subtyping
1361    ///
1362    /// For result types, you can always use a supertype of the WebAssembly
1363    /// function's actual declared result type. For example, if the WebAssembly
1364    /// function was declared with type `(func (result nullfuncref))` you could
1365    /// successfully call `f.typed::<(), Option<Func>>()` because `Option<Func>`
1366    /// corresponds to `funcref`, which is a supertype of `nullfuncref`.
1367    ///
1368    /// For parameter types, you can always use a subtype of the WebAssembly
1369    /// function's actual declared parameter type. For example, if the
1370    /// WebAssembly function was declared with type `(func (param (ref null
1371    /// func)))` you could successfully call `f.typed::<Func, ()>()` because
1372    /// `Func` corresponds to `(ref func)`, which is a subtype of `(ref null
1373    /// func)`.
1374    ///
1375    /// Additionally, for functions which take a reference to a concrete type as
1376    /// a parameter, you can also use the concrete type's supertype. Consider a
1377    /// WebAssembly function that takes a reference to a function with a
1378    /// concrete type: `(ref null <func type index>)`. In this scenario, there
1379    /// is no static `wasmtime::Foo` Rust type that corresponds to that
1380    /// particular Wasm-defined concrete reference type because Wasm modules are
1381    /// loaded dynamically at runtime. You *could* do `f.typed::<Option<NoFunc>,
1382    /// ()>()`, and while that is correctly typed and valid, it is often overly
1383    /// restrictive. The only value you could call the resulting typed function
1384    /// with is the null function reference, but we'd like to call it with
1385    /// non-null function references that happen to be of the correct
1386    /// type. Therefore, `f.typed<Option<Func>, ()>()` is also allowed in this
1387    /// case, even though `Option<Func>` represents `(ref null func)` which is
1388    /// the supertype, not subtype, of `(ref null <func type index>)`. This does
1389    /// imply some minimal dynamic type checks in this case, but it is supported
1390    /// for better ergonomics, to enable passing non-null references into the
1391    /// function.
1392    ///
1393    /// # Errors
1394    ///
1395    /// This function will return an error if `Params` or `Results` does not
1396    /// match the native type of this WebAssembly function.
1397    ///
1398    /// # Panics
1399    ///
1400    /// This method will panic if `store` does not own this function.
1401    ///
1402    /// # Examples
1403    ///
1404    /// An end-to-end example of calling a function which takes no parameters
1405    /// and has no results:
1406    ///
1407    /// ```
1408    /// # use wasmtime::*;
1409    /// # fn main() -> anyhow::Result<()> {
1410    /// let engine = Engine::default();
1411    /// let mut store = Store::new(&engine, ());
1412    /// let module = Module::new(&engine, r#"(module (func (export "foo")))"#)?;
1413    /// let instance = Instance::new(&mut store, &module, &[])?;
1414    /// let foo = instance.get_func(&mut store, "foo").expect("export wasn't a function");
1415    ///
1416    /// // Note that this call can fail due to the typecheck not passing, but
1417    /// // in our case we statically know the module so we know this should
1418    /// // pass.
1419    /// let typed = foo.typed::<(), ()>(&store)?;
1420    ///
1421    /// // Note that this can fail if the wasm traps at runtime.
1422    /// typed.call(&mut store, ())?;
1423    /// # Ok(())
1424    /// # }
1425    /// ```
1426    ///
1427    /// You can also pass in multiple parameters and get a result back
1428    ///
1429    /// ```
1430    /// # use wasmtime::*;
1431    /// # fn foo(add: &Func, mut store: Store<()>) -> anyhow::Result<()> {
1432    /// let typed = add.typed::<(i32, i64), f32>(&store)?;
1433    /// assert_eq!(typed.call(&mut store, (1, 2))?, 3.0);
1434    /// # Ok(())
1435    /// # }
1436    /// ```
1437    ///
1438    /// and similarly if a function has multiple results you can bind that too
1439    ///
1440    /// ```
1441    /// # use wasmtime::*;
1442    /// # fn foo(add_with_overflow: &Func, mut store: Store<()>) -> anyhow::Result<()> {
1443    /// let typed = add_with_overflow.typed::<(u32, u32), (u32, i32)>(&store)?;
1444    /// let (result, overflow) = typed.call(&mut store, (u32::max_value(), 2))?;
1445    /// assert_eq!(result, 1);
1446    /// assert_eq!(overflow, 1);
1447    /// # Ok(())
1448    /// # }
1449    /// ```
1450    pub fn typed<Params, Results>(
1451        &self,
1452        store: impl AsContext,
1453    ) -> Result<TypedFunc<Params, Results>>
1454    where
1455        Params: WasmParams,
1456        Results: WasmResults,
1457    {
1458        // Type-check that the params/results are all valid
1459        let store = store.as_context().0;
1460        let ty = self.load_ty(store);
1461        Params::typecheck(store.engine(), ty.params(), TypeCheckPosition::Param)
1462            .context("type mismatch with parameters")?;
1463        Results::typecheck(store.engine(), ty.results(), TypeCheckPosition::Result)
1464            .context("type mismatch with results")?;
1465
1466        // and then we can construct the typed version of this function
1467        // (unsafely), which should be safe since we just did the type check above.
1468        unsafe { Ok(TypedFunc::_new_unchecked(store, *self)) }
1469    }
1470
1471    /// Get a stable hash key for this function.
1472    ///
1473    /// Even if the same underlying function is added to the `StoreData`
1474    /// multiple times and becomes multiple `wasmtime::Func`s, this hash key
1475    /// will be consistent across all of these functions.
1476    #[cfg_attr(
1477        not(test),
1478        expect(dead_code, reason = "Not used yet, but added for consistency")
1479    )]
1480    pub(crate) fn hash_key(&self, store: &mut StoreOpaque) -> impl core::hash::Hash + Eq + use<> {
1481        self.vm_func_ref(store).as_ptr().addr()
1482    }
1483}
1484
1485/// Prepares for entrance into WebAssembly.
1486///
1487/// This function will set up context such that `closure` is allowed to call a
1488/// raw trampoline or a raw WebAssembly function. This *must* be called to do
1489/// things like catch traps and set up GC properly.
1490///
1491/// The `closure` provided receives a default "caller" `VMContext` parameter it
1492/// can pass to the called wasm function, if desired.
1493pub(crate) fn invoke_wasm_and_catch_traps<T>(
1494    store: &mut StoreContextMut<'_, T>,
1495    closure: impl FnMut(NonNull<VMContext>, Option<InterpreterRef<'_>>) -> bool,
1496) -> Result<()> {
1497    unsafe {
1498        // The `enter_wasm` call below will reset the store context's
1499        // `stack_chain` to a new `InitialStack`, pointing to the
1500        // stack-allocated `initial_stack_csi`.
1501        let mut initial_stack_csi = VMCommonStackInformation::running_default();
1502        // Stores some state of the runtime just before entering Wasm. Will be
1503        // restored upon exiting Wasm. Note that the `CallThreadState` that is
1504        // created by the `catch_traps` call below will store a pointer to this
1505        // stack-allocated `previous_runtime_state`.
1506        let mut previous_runtime_state =
1507            EntryStoreContext::enter_wasm(store, &mut initial_stack_csi);
1508
1509        if let Err(trap) = store.0.call_hook(CallHook::CallingWasm) {
1510            // `previous_runtime_state` implicitly dropped here
1511            return Err(trap);
1512        }
1513        let result = crate::runtime::vm::catch_traps(store, &mut previous_runtime_state, closure);
1514        core::mem::drop(previous_runtime_state);
1515        store.0.call_hook(CallHook::ReturningFromWasm)?;
1516        result.map_err(|t| crate::trap::from_runtime_box(store.0, t))
1517    }
1518}
1519
1520/// This type helps managing the state of the runtime when entering and exiting
1521/// Wasm. To this end, it contains a subset of the data in `VMStoreContext`.
1522/// Upon entering Wasm, it updates various runtime fields and their
1523/// original values saved in this struct. Upon exiting Wasm, the previous values
1524/// are restored.
1525pub(crate) struct EntryStoreContext {
1526    /// If set, contains value of `stack_limit` field to restore in
1527    /// `VMStoreContext` when exiting Wasm.
1528    pub stack_limit: Option<usize>,
1529    /// Contains value of `last_wasm_exit_pc` field to restore in
1530    /// `VMStoreContext` when exiting Wasm.
1531    pub last_wasm_exit_pc: usize,
1532    /// Contains value of `last_wasm_exit_fp` field to restore in
1533    /// `VMStoreContext` when exiting Wasm.
1534    pub last_wasm_exit_fp: usize,
1535    /// Contains value of `last_wasm_entry_fp` field to restore in
1536    /// `VMStoreContext` when exiting Wasm.
1537    pub last_wasm_entry_fp: usize,
1538    /// Contains value of `stack_chain` field to restore in
1539    /// `VMStoreContext` when exiting Wasm.
1540    pub stack_chain: VMStackChain,
1541
1542    /// We need a pointer to the runtime limits, so we can update them from
1543    /// `drop`/`exit_wasm`.
1544    vm_store_context: *const VMStoreContext,
1545}
1546
1547impl EntryStoreContext {
1548    /// This function is called to update and save state when
1549    /// WebAssembly is entered within the `Store`.
1550    ///
1551    /// This updates various fields such as:
1552    ///
1553    /// * The stack limit. This is what ensures that we limit the stack space
1554    ///   allocated by WebAssembly code and it's relative to the initial stack
1555    ///   pointer that called into wasm.
1556    ///
1557    /// It also saves the different last_wasm_* values in the `VMStoreContext`.
1558    pub fn enter_wasm<T>(
1559        store: &mut StoreContextMut<'_, T>,
1560        initial_stack_information: *mut VMCommonStackInformation,
1561    ) -> Self {
1562        let stack_limit;
1563
1564        // If this is a recursive call, e.g. our stack limit is already set, then
1565        // we may be able to skip this function.
1566        //
1567        // For synchronous stores there's nothing else to do because all wasm calls
1568        // happen synchronously and on the same stack. This means that the previous
1569        // stack limit will suffice for the next recursive call.
1570        //
1571        // For asynchronous stores then each call happens on a separate native
1572        // stack. This means that the previous stack limit is no longer relevant
1573        // because we're on a separate stack.
1574        if unsafe { *store.0.vm_store_context().stack_limit.get() } != usize::MAX
1575            && !store.0.async_support()
1576        {
1577            stack_limit = None;
1578        }
1579        // Ignore this stack pointer business on miri since we can't execute wasm
1580        // anyway and the concept of a stack pointer on miri is a bit nebulous
1581        // regardless.
1582        else if cfg!(miri) {
1583            stack_limit = None;
1584        } else {
1585            // When Cranelift has support for the host then we might be running native
1586            // compiled code meaning we need to read the actual stack pointer. If
1587            // Cranelift can't be used though then we're guaranteed to be running pulley
1588            // in which case this stack pointer isn't actually used as Pulley has custom
1589            // mechanisms for stack overflow.
1590            #[cfg(has_host_compiler_backend)]
1591            let stack_pointer = crate::runtime::vm::get_stack_pointer();
1592            #[cfg(not(has_host_compiler_backend))]
1593            let stack_pointer = {
1594                use wasmtime_environ::TripleExt;
1595                debug_assert!(store.engine().target().is_pulley());
1596                usize::MAX
1597            };
1598
1599            // Determine the stack pointer where, after which, any wasm code will
1600            // immediately trap. This is checked on the entry to all wasm functions.
1601            //
1602            // Note that this isn't 100% precise. We are requested to give wasm
1603            // `max_wasm_stack` bytes, but what we're actually doing is giving wasm
1604            // probably a little less than `max_wasm_stack` because we're
1605            // calculating the limit relative to this function's approximate stack
1606            // pointer. Wasm will be executed on a frame beneath this one (or next
1607            // to it). In any case it's expected to be at most a few hundred bytes
1608            // of slop one way or another. When wasm is typically given a MB or so
1609            // (a million bytes) the slop shouldn't matter too much.
1610            //
1611            // After we've got the stack limit then we store it into the `stack_limit`
1612            // variable.
1613            let wasm_stack_limit = stack_pointer
1614                .checked_sub(store.engine().config().max_wasm_stack)
1615                .unwrap();
1616            let prev_stack = unsafe {
1617                mem::replace(
1618                    &mut *store.0.vm_store_context().stack_limit.get(),
1619                    wasm_stack_limit,
1620                )
1621            };
1622            stack_limit = Some(prev_stack);
1623        }
1624
1625        unsafe {
1626            let last_wasm_exit_pc = *store.0.vm_store_context().last_wasm_exit_pc.get();
1627            let last_wasm_exit_fp = *store.0.vm_store_context().last_wasm_exit_fp.get();
1628            let last_wasm_entry_fp = *store.0.vm_store_context().last_wasm_entry_fp.get();
1629
1630            let stack_chain = (*store.0.vm_store_context().stack_chain.get()).clone();
1631
1632            let new_stack_chain = VMStackChain::InitialStack(initial_stack_information);
1633            *store.0.vm_store_context().stack_chain.get() = new_stack_chain;
1634
1635            let vm_store_context = store.0.vm_store_context();
1636
1637            Self {
1638                stack_limit,
1639                last_wasm_exit_pc,
1640                last_wasm_exit_fp,
1641                last_wasm_entry_fp,
1642                stack_chain,
1643                vm_store_context,
1644            }
1645        }
1646    }
1647
1648    /// This function restores the values stored in this struct. We invoke this
1649    /// function through this type's `Drop` implementation. This ensures that we
1650    /// even restore the values if we unwind the stack (e.g., because we are
1651    /// panicking out of a Wasm execution).
1652    #[inline]
1653    fn exit_wasm(&mut self) {
1654        unsafe {
1655            if let Some(limit) = self.stack_limit {
1656                *(&*self.vm_store_context).stack_limit.get() = limit;
1657            }
1658
1659            *(*self.vm_store_context).last_wasm_exit_fp.get() = self.last_wasm_exit_fp;
1660            *(*self.vm_store_context).last_wasm_exit_pc.get() = self.last_wasm_exit_pc;
1661            *(*self.vm_store_context).last_wasm_entry_fp.get() = self.last_wasm_entry_fp;
1662            *(*self.vm_store_context).stack_chain.get() = self.stack_chain.clone();
1663        }
1664    }
1665}
1666
1667impl Drop for EntryStoreContext {
1668    #[inline]
1669    fn drop(&mut self) {
1670        self.exit_wasm();
1671    }
1672}
1673
1674/// A trait implemented for types which can be returned from closures passed to
1675/// [`Func::wrap`] and friends.
1676///
1677/// This trait should not be implemented by user types. This trait may change at
1678/// any time internally. The types which implement this trait, however, are
1679/// stable over time.
1680///
1681/// For more information see [`Func::wrap`]
1682pub unsafe trait WasmRet {
1683    // Same as `WasmTy::compatible_with_store`.
1684    #[doc(hidden)]
1685    fn compatible_with_store(&self, store: &StoreOpaque) -> bool;
1686
1687    /// Stores this return value into the `ptr` specified using the rooted
1688    /// `store`.
1689    ///
1690    /// Traps are communicated through the `Result<_>` return value.
1691    ///
1692    /// # Unsafety
1693    ///
1694    /// This method is unsafe as `ptr` must have the correct length to store
1695    /// this result. This property is only checked in debug mode, not in release
1696    /// mode.
1697    #[doc(hidden)]
1698    unsafe fn store(
1699        self,
1700        store: &mut AutoAssertNoGc<'_>,
1701        ptr: &mut [MaybeUninit<ValRaw>],
1702    ) -> Result<()>;
1703
1704    #[doc(hidden)]
1705    fn func_type(engine: &Engine, params: impl Iterator<Item = ValType>) -> FuncType;
1706    #[doc(hidden)]
1707    fn may_gc() -> bool;
1708
1709    // Utilities used to convert an instance of this type to a `Result`
1710    // explicitly, used when wrapping async functions which always bottom-out
1711    // in a function that returns a trap because futures can be cancelled.
1712    #[doc(hidden)]
1713    type Fallible: WasmRet;
1714    #[doc(hidden)]
1715    fn into_fallible(self) -> Self::Fallible;
1716    #[doc(hidden)]
1717    fn fallible_from_error(error: Error) -> Self::Fallible;
1718}
1719
1720unsafe impl<T> WasmRet for T
1721where
1722    T: WasmTy,
1723{
1724    type Fallible = Result<T>;
1725
1726    fn compatible_with_store(&self, store: &StoreOpaque) -> bool {
1727        <Self as WasmTy>::compatible_with_store(self, store)
1728    }
1729
1730    unsafe fn store(
1731        self,
1732        store: &mut AutoAssertNoGc<'_>,
1733        ptr: &mut [MaybeUninit<ValRaw>],
1734    ) -> Result<()> {
1735        debug_assert!(ptr.len() > 0);
1736        // SAFETY: the contract of this function/trait combo is such that `ptr`
1737        // is valid to store this type's value, thus this lookup should be safe.
1738        unsafe { <Self as WasmTy>::store(self, store, ptr.get_unchecked_mut(0)) }
1739    }
1740
1741    fn may_gc() -> bool {
1742        T::may_gc()
1743    }
1744
1745    fn func_type(engine: &Engine, params: impl Iterator<Item = ValType>) -> FuncType {
1746        FuncType::new(engine, params, Some(<Self as WasmTy>::valtype()))
1747    }
1748
1749    fn into_fallible(self) -> Result<T> {
1750        Ok(self)
1751    }
1752
1753    fn fallible_from_error(error: Error) -> Result<T> {
1754        Err(error)
1755    }
1756}
1757
1758unsafe impl<T> WasmRet for Result<T>
1759where
1760    T: WasmRet,
1761{
1762    type Fallible = Self;
1763
1764    fn compatible_with_store(&self, store: &StoreOpaque) -> bool {
1765        match self {
1766            Ok(x) => <T as WasmRet>::compatible_with_store(x, store),
1767            Err(_) => true,
1768        }
1769    }
1770
1771    unsafe fn store(
1772        self,
1773        store: &mut AutoAssertNoGc<'_>,
1774        ptr: &mut [MaybeUninit<ValRaw>],
1775    ) -> Result<()> {
1776        // SAFETY: the safety of calling this function is the same as calling
1777        // the inner `store`.
1778        unsafe { self.and_then(|val| val.store(store, ptr)) }
1779    }
1780
1781    fn may_gc() -> bool {
1782        T::may_gc()
1783    }
1784
1785    fn func_type(engine: &Engine, params: impl Iterator<Item = ValType>) -> FuncType {
1786        T::func_type(engine, params)
1787    }
1788
1789    fn into_fallible(self) -> Result<T> {
1790        self
1791    }
1792
1793    fn fallible_from_error(error: Error) -> Result<T> {
1794        Err(error)
1795    }
1796}
1797
1798macro_rules! impl_wasm_host_results {
1799    ($n:tt $($t:ident)*) => (
1800        #[allow(non_snake_case, reason = "macro-generated code")]
1801        unsafe impl<$($t),*> WasmRet for ($($t,)*)
1802        where
1803            $($t: WasmTy,)*
1804        {
1805            type Fallible = Result<Self>;
1806
1807            #[inline]
1808            fn compatible_with_store(&self, _store: &StoreOpaque) -> bool {
1809                let ($($t,)*) = self;
1810                $( $t.compatible_with_store(_store) && )* true
1811            }
1812
1813            #[inline]
1814            unsafe fn store(
1815                self,
1816                _store: &mut AutoAssertNoGc<'_>,
1817                _ptr: &mut [MaybeUninit<ValRaw>],
1818            ) -> Result<()> {
1819                let ($($t,)*) = self;
1820                let mut _cur = 0;
1821                $(
1822                    debug_assert!(_cur < _ptr.len());
1823                    // SAFETY: `store`'s unsafe contract is that `_ptr` is
1824                    // appropriately sized and additionally safe to call `store`
1825                    // for sub-types.
1826                    unsafe {
1827                        let val = _ptr.get_unchecked_mut(_cur);
1828                        _cur += 1;
1829                        WasmTy::store($t, _store, val)?;
1830                    }
1831                )*
1832                Ok(())
1833            }
1834
1835            #[doc(hidden)]
1836            fn may_gc() -> bool {
1837                $( $t::may_gc() || )* false
1838            }
1839
1840            fn func_type(engine: &Engine, params: impl Iterator<Item = ValType>) -> FuncType {
1841                FuncType::new(
1842                    engine,
1843                    params,
1844                    IntoIterator::into_iter([$($t::valtype(),)*]),
1845                )
1846            }
1847
1848            #[inline]
1849            fn into_fallible(self) -> Result<Self> {
1850                Ok(self)
1851            }
1852
1853            #[inline]
1854            fn fallible_from_error(error: Error) -> Result<Self> {
1855                Err(error)
1856            }
1857        }
1858    )
1859}
1860
1861for_each_function_signature!(impl_wasm_host_results);
1862
1863/// Internal trait implemented for all arguments that can be passed to
1864/// [`Func::wrap`] and [`Linker::func_wrap`](crate::Linker::func_wrap).
1865///
1866/// This trait should not be implemented by external users, it's only intended
1867/// as an implementation detail of this crate.
1868pub trait IntoFunc<T, Params, Results>: Send + Sync + 'static {
1869    /// Convert this function into a `VM{Array,Native}CallHostFuncContext` and
1870    /// internal `VMFuncRef`.
1871    #[doc(hidden)]
1872    fn into_func(self, engine: &Engine) -> HostContext;
1873}
1874
1875macro_rules! impl_into_func {
1876    ($num:tt $arg:ident) => {
1877        // Implement for functions without a leading `&Caller` parameter,
1878        // delegating to the implementation below which does have the leading
1879        // `Caller` parameter.
1880        #[expect(non_snake_case, reason = "macro-generated code")]
1881        impl<T, F, $arg, R> IntoFunc<T, $arg, R> for F
1882        where
1883            F: Fn($arg) -> R + Send + Sync + 'static,
1884            $arg: WasmTy,
1885            R: WasmRet,
1886            T: 'static,
1887        {
1888            fn into_func(self, engine: &Engine) -> HostContext {
1889                let f = move |_: Caller<'_, T>, $arg: $arg| {
1890                    self($arg)
1891                };
1892
1893                f.into_func(engine)
1894            }
1895        }
1896
1897        #[expect(non_snake_case, reason = "macro-generated code")]
1898        impl<T, F, $arg, R> IntoFunc<T, (Caller<'_, T>, $arg), R> for F
1899        where
1900            F: Fn(Caller<'_, T>, $arg) -> R + Send + Sync + 'static,
1901            $arg: WasmTy,
1902            R: WasmRet,
1903            T: 'static,
1904        {
1905            fn into_func(self, engine: &Engine) -> HostContext {
1906                HostContext::from_closure(engine, move |caller: Caller<'_, T>, ($arg,)| {
1907                    self(caller, $arg)
1908                })
1909            }
1910        }
1911    };
1912    ($num:tt $($args:ident)*) => {
1913        // Implement for functions without a leading `&Caller` parameter,
1914        // delegating to the implementation below which does have the leading
1915        // `Caller` parameter.
1916        #[allow(non_snake_case, reason = "macro-generated code")]
1917        impl<T, F, $($args,)* R> IntoFunc<T, ($($args,)*), R> for F
1918        where
1919            F: Fn($($args),*) -> R + Send + Sync + 'static,
1920            $($args: WasmTy,)*
1921            R: WasmRet,
1922            T: 'static,
1923        {
1924            fn into_func(self, engine: &Engine) -> HostContext {
1925                let f = move |_: Caller<'_, T>, $($args:$args),*| {
1926                    self($($args),*)
1927                };
1928
1929                f.into_func(engine)
1930            }
1931        }
1932
1933        #[allow(non_snake_case, reason = "macro-generated code")]
1934        impl<T, F, $($args,)* R> IntoFunc<T, (Caller<'_, T>, $($args,)*), R> for F
1935        where
1936            F: Fn(Caller<'_, T>, $($args),*) -> R + Send + Sync + 'static,
1937            $($args: WasmTy,)*
1938            R: WasmRet,
1939            T: 'static,
1940        {
1941            fn into_func(self, engine: &Engine) -> HostContext {
1942                HostContext::from_closure(engine, move |caller: Caller<'_, T>, ( $( $args ),* )| {
1943                    self(caller, $( $args ),* )
1944                })
1945            }
1946        }
1947    }
1948}
1949
1950for_each_function_signature!(impl_into_func);
1951
1952/// Trait implemented for various tuples made up of types which implement
1953/// [`WasmTy`] that can be passed to [`Func::wrap_inner`] and
1954/// [`HostContext::from_closure`].
1955pub unsafe trait WasmTyList {
1956    /// Get the value type that each Type in the list represents.
1957    fn valtypes() -> impl Iterator<Item = ValType>;
1958
1959    // Load a version of `Self` from the `values` provided.
1960    //
1961    // # Safety
1962    //
1963    // This function is unsafe as it's up to the caller to ensure that `values` are
1964    // valid for this given type.
1965    #[doc(hidden)]
1966    unsafe fn load(store: &mut AutoAssertNoGc<'_>, values: &mut [MaybeUninit<ValRaw>]) -> Self;
1967
1968    #[doc(hidden)]
1969    fn may_gc() -> bool;
1970}
1971
1972macro_rules! impl_wasm_ty_list {
1973    ($num:tt $($args:ident)*) => (
1974        #[allow(non_snake_case, reason = "macro-generated code")]
1975        unsafe impl<$($args),*> WasmTyList for ($($args,)*)
1976        where
1977            $($args: WasmTy,)*
1978        {
1979            fn valtypes() -> impl Iterator<Item = ValType> {
1980                IntoIterator::into_iter([$($args::valtype(),)*])
1981            }
1982
1983            unsafe fn load(_store: &mut AutoAssertNoGc<'_>, _values: &mut [MaybeUninit<ValRaw>]) -> Self {
1984                let mut _cur = 0;
1985                ($({
1986                    debug_assert!(_cur < _values.len());
1987                    // SAFETY: this function's own contract means that `_values`
1988                    // is appropriately sized/typed for the internal loads.
1989                    unsafe {
1990                        let ptr = _values.get_unchecked(_cur).assume_init_ref();
1991                        _cur += 1;
1992                        $args::load(_store, ptr)
1993                    }
1994                },)*)
1995            }
1996
1997            fn may_gc() -> bool {
1998                $( $args::may_gc() || )* false
1999            }
2000        }
2001    );
2002}
2003
2004for_each_function_signature!(impl_wasm_ty_list);
2005
2006/// A structure representing the caller's context when creating a function
2007/// via [`Func::wrap`].
2008///
2009/// This structure can be taken as the first parameter of a closure passed to
2010/// [`Func::wrap`] or other constructors, and serves two purposes:
2011///
2012/// * First consumers can use [`Caller<'_, T>`](crate::Caller) to get access to
2013///   [`StoreContextMut<'_, T>`](crate::StoreContextMut) and/or get access to
2014///   `T` itself. This means that the [`Caller`] type can serve as a proxy to
2015///   the original [`Store`](crate::Store) itself and is used to satisfy
2016///   [`AsContext`] and [`AsContextMut`] bounds.
2017///
2018/// * Second a [`Caller`] can be used as the name implies, learning about the
2019///   caller's context, namely it's exported memory and exported functions. This
2020///   allows functions which take pointers as arguments to easily read the
2021///   memory the pointers point into, or if a function is expected to call
2022///   malloc in the wasm module to reserve space for the output you can do that.
2023///
2024/// Host functions which want access to [`Store`](crate::Store)-level state are
2025/// recommended to use this type.
2026pub struct Caller<'a, T: 'static> {
2027    pub(crate) store: StoreContextMut<'a, T>,
2028    caller: Instance,
2029}
2030
2031impl<T> Caller<'_, T> {
2032    #[cfg(feature = "async")]
2033    pub(crate) fn new(store: StoreContextMut<'_, T>, caller: Instance) -> Caller<'_, T> {
2034        Caller { store, caller }
2035    }
2036
2037    #[cfg(feature = "async")]
2038    pub(crate) fn caller(&self) -> Instance {
2039        self.caller
2040    }
2041
2042    /// Executes `f` with an appropriate `Caller`.
2043    ///
2044    /// This is the entrypoint for host functions in core wasm and converts from
2045    /// `VMContext` to `Caller`
2046    ///
2047    /// # Safety
2048    ///
2049    /// This requires that `caller` is safe to wrap up as a `Caller`,
2050    /// effectively meaning that we just entered the host from wasm.
2051    /// Additionally this `Caller`'s `T` parameter must match the actual `T` in
2052    /// the store of the vmctx of `caller`.
2053    unsafe fn with<F, R>(caller: NonNull<VMContext>, f: F) -> R
2054    where
2055        F: FnOnce(Caller<'_, T>) -> R,
2056    {
2057        // SAFETY: it's a contract of this function itself that `from_vmctx` is
2058        // safe to call. Additionally it's a contract of this function itself
2059        // that the `T` of `Caller` matches the store.
2060        unsafe {
2061            crate::runtime::vm::InstanceAndStore::from_vmctx(caller, |pair| {
2062                let (instance, store) = pair.unpack_mut();
2063                let mut store = store.unchecked_context_mut::<T>();
2064                let caller = Instance::from_wasmtime(instance.id(), store.0);
2065
2066                let (gc_lifo_scope, ret) = {
2067                    let gc_lifo_scope = store.0.gc_roots().enter_lifo_scope();
2068
2069                    let ret = f(Caller {
2070                        store: store.as_context_mut(),
2071                        caller,
2072                    });
2073
2074                    (gc_lifo_scope, ret)
2075                };
2076
2077                // Safe to recreate a mutable borrow of the store because `ret`
2078                // cannot be borrowing from the store.
2079                store.0.exit_gc_lifo_scope(gc_lifo_scope);
2080
2081                ret
2082            })
2083        }
2084    }
2085
2086    fn sub_caller(&mut self) -> Caller<'_, T> {
2087        Caller {
2088            store: self.store.as_context_mut(),
2089            caller: self.caller,
2090        }
2091    }
2092
2093    /// Looks up an export from the caller's module by the `name` given.
2094    ///
2095    /// This is a low-level function that's typically used to implement passing
2096    /// of pointers or indices between core Wasm instances, where the callee
2097    /// needs to consult the caller's exports to perform memory management and
2098    /// resolve the references.
2099    ///
2100    /// For comparison, in components, the component model handles translating
2101    /// arguments from one component instance to another and managing memory, so
2102    /// that callees don't need to be aware of their callers, which promotes
2103    /// virtualizability of APIs.
2104    ///
2105    /// # Return
2106    ///
2107    /// If an export with the `name` provided was found, then it is returned as an
2108    /// `Extern`. There are a number of situations, however, where the export may not
2109    /// be available:
2110    ///
2111    /// * The caller instance may not have an export named `name`
2112    /// * There may not be a caller available, for example if `Func` was called
2113    ///   directly from host code.
2114    ///
2115    /// It's recommended to take care when calling this API and gracefully
2116    /// handling a `None` return value.
2117    pub fn get_export(&mut self, name: &str) -> Option<Extern> {
2118        // All instances created have a `host_state` with a pointer pointing
2119        // back to themselves. If this caller doesn't have that `host_state`
2120        // then it probably means it was a host-created object like `Func::new`
2121        // which doesn't have any exports we want to return anyway.
2122        self.caller.get_export(&mut self.store, name)
2123    }
2124
2125    /// Looks up an exported [`Extern`] value by a [`ModuleExport`] value.
2126    ///
2127    /// This is similar to [`Self::get_export`] but uses a [`ModuleExport`] value to avoid
2128    /// string lookups where possible. [`ModuleExport`]s can be obtained by calling
2129    /// [`Module::get_export_index`] on the [`Module`] that an instance was instantiated with.
2130    ///
2131    /// This method will search the module for an export with a matching entity index and return
2132    /// the value, if found.
2133    ///
2134    /// Returns `None` if there was no export with a matching entity index.
2135    /// # Panics
2136    ///
2137    /// Panics if `store` does not own this instance.
2138    ///
2139    /// # Usage
2140    /// ```
2141    /// use std::str;
2142    ///
2143    /// # use wasmtime::*;
2144    /// # fn main() -> anyhow::Result<()> {
2145    /// # let mut store = Store::default();
2146    ///
2147    /// let module = Module::new(
2148    ///     store.engine(),
2149    ///     r#"
2150    ///         (module
2151    ///             (import "" "" (func $log_str (param i32 i32)))
2152    ///             (func (export "foo")
2153    ///                 i32.const 4   ;; ptr
2154    ///                 i32.const 13  ;; len
2155    ///                 call $log_str)
2156    ///             (memory (export "memory") 1)
2157    ///             (data (i32.const 4) "Hello, world!"))
2158    ///     "#,
2159    /// )?;
2160    ///
2161    /// let Some(module_export) = module.get_export_index("memory") else {
2162    ///    anyhow::bail!("failed to find `memory` export in module");
2163    /// };
2164    ///
2165    /// let log_str = Func::wrap(&mut store, move |mut caller: Caller<'_, ()>, ptr: i32, len: i32| {
2166    ///     let mem = match caller.get_module_export(&module_export) {
2167    ///         Some(Extern::Memory(mem)) => mem,
2168    ///         _ => anyhow::bail!("failed to find host memory"),
2169    ///     };
2170    ///     let data = mem.data(&caller)
2171    ///         .get(ptr as u32 as usize..)
2172    ///         .and_then(|arr| arr.get(..len as u32 as usize));
2173    ///     let string = match data {
2174    ///         Some(data) => match str::from_utf8(data) {
2175    ///             Ok(s) => s,
2176    ///             Err(_) => anyhow::bail!("invalid utf-8"),
2177    ///         },
2178    ///         None => anyhow::bail!("pointer/length out of bounds"),
2179    ///     };
2180    ///     assert_eq!(string, "Hello, world!");
2181    ///     println!("{}", string);
2182    ///     Ok(())
2183    /// });
2184    /// let instance = Instance::new(&mut store, &module, &[log_str.into()])?;
2185    /// let foo = instance.get_typed_func::<(), ()>(&mut store, "foo")?;
2186    /// foo.call(&mut store, ())?;
2187    /// # Ok(())
2188    /// # }
2189    /// ```
2190    pub fn get_module_export(&mut self, export: &ModuleExport) -> Option<Extern> {
2191        self.caller.get_module_export(&mut self.store, export)
2192    }
2193
2194    /// Access the underlying data owned by this `Store`.
2195    ///
2196    /// Same as [`Store::data`](crate::Store::data)
2197    pub fn data(&self) -> &T {
2198        self.store.data()
2199    }
2200
2201    /// Access the underlying data owned by this `Store`.
2202    ///
2203    /// Same as [`Store::data_mut`](crate::Store::data_mut)
2204    pub fn data_mut(&mut self) -> &mut T {
2205        self.store.data_mut()
2206    }
2207
2208    /// Returns the underlying [`Engine`] this store is connected to.
2209    pub fn engine(&self) -> &Engine {
2210        self.store.engine()
2211    }
2212
2213    /// Perform garbage collection.
2214    ///
2215    /// Same as [`Store::gc`](crate::Store::gc).
2216    #[cfg(feature = "gc")]
2217    pub fn gc(&mut self, why: Option<&crate::GcHeapOutOfMemory<()>>) {
2218        self.store.gc(why);
2219    }
2220
2221    /// Perform garbage collection asynchronously.
2222    ///
2223    /// Same as [`Store::gc_async`](crate::Store::gc_async).
2224    #[cfg(all(feature = "async", feature = "gc"))]
2225    pub async fn gc_async(&mut self, why: Option<&crate::GcHeapOutOfMemory<()>>) -> Result<()>
2226    where
2227        T: Send + 'static,
2228    {
2229        self.store.gc_async(why).await
2230    }
2231
2232    /// Returns the remaining fuel in the store.
2233    ///
2234    /// For more information see [`Store::get_fuel`](crate::Store::get_fuel)
2235    pub fn get_fuel(&self) -> Result<u64> {
2236        self.store.get_fuel()
2237    }
2238
2239    /// Set the amount of fuel in this store to be consumed when executing wasm code.
2240    ///
2241    /// For more information see [`Store::set_fuel`](crate::Store::set_fuel)
2242    pub fn set_fuel(&mut self, fuel: u64) -> Result<()> {
2243        self.store.set_fuel(fuel)
2244    }
2245
2246    /// Configures this `Store` to yield while executing futures every N units of fuel.
2247    ///
2248    /// For more information see
2249    /// [`Store::fuel_async_yield_interval`](crate::Store::fuel_async_yield_interval)
2250    pub fn fuel_async_yield_interval(&mut self, interval: Option<u64>) -> Result<()> {
2251        self.store.fuel_async_yield_interval(interval)
2252    }
2253}
2254
2255impl<T: 'static> AsContext for Caller<'_, T> {
2256    type Data = T;
2257    fn as_context(&self) -> StoreContext<'_, T> {
2258        self.store.as_context()
2259    }
2260}
2261
2262impl<T: 'static> AsContextMut for Caller<'_, T> {
2263    fn as_context_mut(&mut self) -> StoreContextMut<'_, T> {
2264        self.store.as_context_mut()
2265    }
2266}
2267
2268// State stored inside a `VMArrayCallHostFuncContext`.
2269struct HostFuncState<F> {
2270    // The actual host function.
2271    func: F,
2272
2273    // NB: We have to keep our `VMSharedTypeIndex` registered in the engine for
2274    // as long as this function exists.
2275    _ty: RegisteredType,
2276}
2277
2278#[doc(hidden)]
2279pub enum HostContext {
2280    Array(StoreBox<VMArrayCallHostFuncContext>),
2281}
2282
2283impl From<StoreBox<VMArrayCallHostFuncContext>> for HostContext {
2284    fn from(ctx: StoreBox<VMArrayCallHostFuncContext>) -> Self {
2285        HostContext::Array(ctx)
2286    }
2287}
2288
2289impl HostContext {
2290    fn from_closure<F, T, P, R>(engine: &Engine, func: F) -> Self
2291    where
2292        F: Fn(Caller<'_, T>, P) -> R + Send + Sync + 'static,
2293        P: WasmTyList,
2294        R: WasmRet,
2295        T: 'static,
2296    {
2297        let ty = R::func_type(engine, None::<ValType>.into_iter().chain(P::valtypes()));
2298        let type_index = ty.type_index();
2299
2300        let array_call = Self::array_call_trampoline::<T, F, P, R>;
2301
2302        let ctx = unsafe {
2303            VMArrayCallHostFuncContext::new(
2304                array_call,
2305                type_index,
2306                Box::new(HostFuncState {
2307                    func,
2308                    _ty: ty.into_registered_type(),
2309                }),
2310            )
2311        };
2312
2313        ctx.into()
2314    }
2315
2316    /// Raw entry trampoline for wasm for typed functions.
2317    ///
2318    /// # Safety
2319    ///
2320    /// The `callee_vmctx`, `caller_vmctx`, and `args` values must basically be
2321    /// "all valid" in the sense that they're from the same store, appropriately
2322    /// sized, appropriate to dereference, etc. This requires that `T` matches
2323    /// the type of the store that the vmctx values point to. The `F` parameter
2324    /// must match the state in `callee_vmctx`. The `P` and `R` type parameters
2325    /// must accurately describe the params/results store in `args`.
2326    unsafe extern "C" fn array_call_trampoline<T, F, P, R>(
2327        callee_vmctx: NonNull<VMOpaqueContext>,
2328        caller_vmctx: NonNull<VMContext>,
2329        args: NonNull<ValRaw>,
2330        args_len: usize,
2331    ) -> bool
2332    where
2333        F: Fn(Caller<'_, T>, P) -> R + 'static,
2334        P: WasmTyList,
2335        R: WasmRet,
2336        T: 'static,
2337    {
2338        // Note that this function is intentionally scoped into a
2339        // separate closure. Handling traps and panics will involve
2340        // longjmp-ing from this function which means we won't run
2341        // destructors. As a result anything requiring a destructor
2342        // should be part of this closure, and the long-jmp-ing
2343        // happens after the closure in handling the result.
2344        let run = move |mut caller: Caller<'_, T>| {
2345            let mut args =
2346                NonNull::slice_from_raw_parts(args.cast::<MaybeUninit<ValRaw>>(), args_len);
2347            // SAFETY: it's a safety contract of this function itself that
2348            // `callee_vmctx` is safe to read.
2349            let state = unsafe {
2350                let vmctx = VMArrayCallHostFuncContext::from_opaque(callee_vmctx);
2351                vmctx.as_ref().host_state()
2352            };
2353
2354            // Double-check ourselves in debug mode, but we control
2355            // the `Any` here so an unsafe downcast should also
2356            // work.
2357            //
2358            // SAFETY: all typed host functions use `HostFuncState<F>` as their
2359            // state so this should be safe to effectively do an unchecked
2360            // downcast.
2361            let state = unsafe {
2362                debug_assert!(state.is::<HostFuncState<F>>());
2363                &*(state as *const _ as *const HostFuncState<F>)
2364            };
2365            let func = &state.func;
2366
2367            let ret = 'ret: {
2368                if let Err(trap) = caller.store.0.call_hook(CallHook::CallingHost) {
2369                    break 'ret R::fallible_from_error(trap);
2370                }
2371
2372                let mut store = if P::may_gc() {
2373                    AutoAssertNoGc::new(caller.store.0)
2374                } else {
2375                    unsafe { AutoAssertNoGc::disabled(caller.store.0) }
2376                };
2377                // SAFETY: this function requires `args` to be valid and the
2378                // `WasmTyList` trait means that everything should be correctly
2379                // ascribed/typed, making this valid to load from.
2380                let params = unsafe { P::load(&mut store, args.as_mut()) };
2381                let _ = &mut store;
2382                drop(store);
2383
2384                let r = func(caller.sub_caller(), params);
2385
2386                if let Err(trap) = caller.store.0.call_hook(CallHook::ReturningFromHost) {
2387                    break 'ret R::fallible_from_error(trap);
2388                }
2389                r.into_fallible()
2390            };
2391
2392            if !ret.compatible_with_store(caller.store.0) {
2393                bail!("host function attempted to return cross-`Store` value to Wasm")
2394            } else {
2395                let mut store = if R::may_gc() {
2396                    AutoAssertNoGc::new(caller.store.0)
2397                } else {
2398                    unsafe { AutoAssertNoGc::disabled(caller.store.0) }
2399                };
2400                // SAFETY: this function requires that `args` is safe for this
2401                // type signature, and the guarantees of `WasmRet` means that
2402                // everything should be typed appropriately.
2403                let ret = unsafe { ret.store(&mut store, args.as_mut())? };
2404                Ok(ret)
2405            }
2406        };
2407
2408        // With nothing else on the stack move `run` into this
2409        // closure and then run it as part of `Caller::with`.
2410        //
2411        // SAFETY: this is an entrypoint of wasm which requires correct type
2412        // ascription of `T` itself, meaning that this should be safe to call.
2413        crate::runtime::vm::catch_unwind_and_record_trap(move || unsafe {
2414            Caller::with(caller_vmctx, run)
2415        })
2416    }
2417}
2418
2419/// Representation of a host-defined function.
2420///
2421/// This is used for `Func::new` but also for `Linker`-defined functions. For
2422/// `Func::new` this is stored within a `Store`, and for `Linker`-defined
2423/// functions they wrap this up in `Arc` to enable shared ownership of this
2424/// across many stores.
2425///
2426/// Technically this structure needs a `<T>` type parameter to connect to the
2427/// `Store<T>` itself, but that's an unsafe contract of using this for now
2428/// rather than part of the struct type (to avoid `Func<T>` in the API).
2429pub(crate) struct HostFunc {
2430    ctx: HostContext,
2431
2432    // Stored to unregister this function's signature with the engine when this
2433    // is dropped.
2434    engine: Engine,
2435}
2436
2437impl core::fmt::Debug for HostFunc {
2438    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
2439        f.debug_struct("HostFunc").finish_non_exhaustive()
2440    }
2441}
2442
2443impl HostFunc {
2444    /// Analog of [`Func::new`]
2445    ///
2446    /// # Panics
2447    ///
2448    /// Panics if the given function type is not associated with the given
2449    /// engine.
2450    pub fn new<T>(
2451        engine: &Engine,
2452        ty: FuncType,
2453        func: impl Fn(Caller<'_, T>, &[Val], &mut [Val]) -> Result<()> + Send + Sync + 'static,
2454    ) -> Self
2455    where
2456        T: 'static,
2457    {
2458        assert!(ty.comes_from_same_engine(engine));
2459        let ty_clone = ty.clone();
2460        unsafe {
2461            HostFunc::new_unchecked(engine, ty, move |caller, values| {
2462                Func::invoke_host_func_for_wasm(caller, &ty_clone, values, &func)
2463            })
2464        }
2465    }
2466
2467    /// Analog of [`Func::new_unchecked`]
2468    ///
2469    /// # Panics
2470    ///
2471    /// Panics if the given function type is not associated with the given
2472    /// engine.
2473    ///
2474    /// # Safety
2475    ///
2476    /// The `func` provided must operate according to the `ty` provided to
2477    /// ensure it's reading the correctly-typed parameters and writing the
2478    /// correctly-typed results.
2479    pub unsafe fn new_unchecked<T>(
2480        engine: &Engine,
2481        ty: FuncType,
2482        func: impl Fn(Caller<'_, T>, &mut [ValRaw]) -> Result<()> + Send + Sync + 'static,
2483    ) -> Self
2484    where
2485        T: 'static,
2486    {
2487        assert!(ty.comes_from_same_engine(engine));
2488        // SAFETY: This is only only called in the raw entrypoint of wasm
2489        // meaning that `caller_vmctx` is appropriate to read, and additionally
2490        // the later usage of `{,in}to_func` will connect `T` to an actual
2491        // store's `T` to ensure it's the same.
2492        let func = move |caller_vmctx, values: &mut [ValRaw]| unsafe {
2493            Caller::<T>::with(caller_vmctx, |mut caller| {
2494                caller.store.0.call_hook(CallHook::CallingHost)?;
2495                let result = func(caller.sub_caller(), values)?;
2496                caller.store.0.call_hook(CallHook::ReturningFromHost)?;
2497                Ok(result)
2498            })
2499        };
2500        let ctx = crate::trampoline::create_array_call_function(&ty, func)
2501            .expect("failed to create function");
2502        HostFunc::_new(engine, ctx.into())
2503    }
2504
2505    /// Analog of [`Func::wrap_inner`]
2506    #[cfg(any(feature = "component-model", feature = "async"))]
2507    pub fn wrap_inner<F, T, Params, Results>(engine: &Engine, func: F) -> Self
2508    where
2509        F: Fn(Caller<'_, T>, Params) -> Results + Send + Sync + 'static,
2510        Params: WasmTyList,
2511        Results: WasmRet,
2512        T: 'static,
2513    {
2514        let ctx = HostContext::from_closure(engine, func);
2515        HostFunc::_new(engine, ctx)
2516    }
2517
2518    /// Analog of [`Func::wrap`]
2519    pub fn wrap<T, Params, Results>(
2520        engine: &Engine,
2521        func: impl IntoFunc<T, Params, Results>,
2522    ) -> Self
2523    where
2524        T: 'static,
2525    {
2526        let ctx = func.into_func(engine);
2527        HostFunc::_new(engine, ctx)
2528    }
2529
2530    /// Requires that this function's signature is already registered within
2531    /// `Engine`. This happens automatically during the above two constructors.
2532    fn _new(engine: &Engine, ctx: HostContext) -> Self {
2533        HostFunc {
2534            ctx,
2535            engine: engine.clone(),
2536        }
2537    }
2538
2539    /// Inserts this `HostFunc` into a `Store`, returning the `Func` pointing to
2540    /// it.
2541    ///
2542    /// # Unsafety
2543    ///
2544    /// Can only be inserted into stores with a matching `T` relative to when
2545    /// this `HostFunc` was first created.
2546    pub unsafe fn to_func(self: &Arc<Self>, store: &mut StoreOpaque) -> Func {
2547        self.validate_store(store);
2548        let (funcrefs, modules) = store.func_refs_and_modules();
2549        let funcref = funcrefs.push_arc_host(self.clone(), modules);
2550        // SAFETY: this funcref was just pushed within the store, so it's safe
2551        // to say this store owns it.
2552        unsafe { Func::from_vm_func_ref(store.id(), funcref) }
2553    }
2554
2555    /// Inserts this `HostFunc` into a `Store`, returning the `Func` pointing to
2556    /// it.
2557    ///
2558    /// This function is similar to, but not equivalent, to `HostFunc::to_func`.
2559    /// Notably this function requires that the `Arc<Self>` pointer is otherwise
2560    /// rooted within the `StoreOpaque` via another means. When in doubt use
2561    /// `to_func` above as it's safer.
2562    ///
2563    /// # Unsafety
2564    ///
2565    /// Can only be inserted into stores with a matching `T` relative to when
2566    /// this `HostFunc` was first created.
2567    ///
2568    /// Additionally the `&Arc<Self>` is not cloned in this function. Instead a
2569    /// raw pointer to `Self` is stored within the `Store` for this function.
2570    /// The caller must arrange for the `Arc<Self>` to be "rooted" in the store
2571    /// provided via another means, probably by pushing to
2572    /// `StoreOpaque::rooted_host_funcs`.
2573    ///
2574    /// Similarly, the caller must arrange for `rooted_func_ref` to be rooted in
2575    /// the same store and additionally be a valid pointer.
2576    pub unsafe fn to_func_store_rooted(
2577        self: &Arc<Self>,
2578        store: &mut StoreOpaque,
2579        rooted_func_ref: Option<NonNull<VMFuncRef>>,
2580    ) -> Func {
2581        self.validate_store(store);
2582
2583        match rooted_func_ref {
2584            Some(funcref) => {
2585                // SAFETY: it's a contract of this function itself that
2586                // `funcref` is safe to read.
2587                unsafe {
2588                    debug_assert!(funcref.as_ref().wasm_call.is_some());
2589                }
2590                // SAFETY: it's a contract of this function that `funcref` is
2591                // owned by `store`.
2592                unsafe { Func::from_vm_func_ref(store.id(), funcref) }
2593            }
2594            None => {
2595                debug_assert!(self.func_ref().wasm_call.is_some());
2596
2597                // SAFETY: it's an unsafe contract of this function that we are
2598                // rooted within the store to say that the store owns a copy of
2599                // this funcref.
2600                unsafe { Func::from_vm_func_ref(store.id(), self.func_ref().into()) }
2601            }
2602        }
2603    }
2604
2605    /// Same as [`HostFunc::to_func`], different ownership.
2606    unsafe fn into_func(self, store: &mut StoreOpaque) -> Func {
2607        self.validate_store(store);
2608        let (funcrefs, modules) = store.func_refs_and_modules();
2609        let funcref = funcrefs.push_box_host(Box::new(self), modules);
2610        // SAFETY: this funcref was just pushed within `store`, so it's safe to
2611        // say it's owned by the store's id.
2612        unsafe { Func::from_vm_func_ref(store.id(), funcref) }
2613    }
2614
2615    fn validate_store(&self, store: &mut StoreOpaque) {
2616        // This assert is required to ensure that we can indeed safely insert
2617        // `self` into the `store` provided, otherwise the type information we
2618        // have listed won't be correct. This is possible to hit with the public
2619        // API of Wasmtime, and should be documented in relevant functions.
2620        assert!(
2621            Engine::same(&self.engine, store.engine()),
2622            "cannot use a store with a different engine than a linker was created with",
2623        );
2624    }
2625
2626    pub(crate) fn sig_index(&self) -> VMSharedTypeIndex {
2627        self.func_ref().type_index
2628    }
2629
2630    pub(crate) fn func_ref(&self) -> &VMFuncRef {
2631        match &self.ctx {
2632            HostContext::Array(ctx) => unsafe { ctx.get().as_ref().func_ref() },
2633        }
2634    }
2635
2636    pub(crate) fn host_ctx(&self) -> &HostContext {
2637        &self.ctx
2638    }
2639}
2640
2641#[cfg(test)]
2642mod tests {
2643    use super::*;
2644    use crate::{Module, Store};
2645
2646    #[test]
2647    #[cfg_attr(miri, ignore)]
2648    fn hash_key_is_stable_across_duplicate_store_data_entries() -> Result<()> {
2649        let mut store = Store::<()>::default();
2650        let module = Module::new(
2651            store.engine(),
2652            r#"
2653                (module
2654                    (func (export "f")
2655                        nop
2656                    )
2657                )
2658            "#,
2659        )?;
2660        let instance = Instance::new(&mut store, &module, &[])?;
2661
2662        // Each time we `get_func`, we call `Func::from_wasmtime` which adds a
2663        // new entry to `StoreData`, so `f1` and `f2` will have different
2664        // indices into `StoreData`.
2665        let f1 = instance.get_func(&mut store, "f").unwrap();
2666        let f2 = instance.get_func(&mut store, "f").unwrap();
2667
2668        // But their hash keys are the same.
2669        assert!(
2670            f1.hash_key(&mut store.as_context_mut().0)
2671                == f2.hash_key(&mut store.as_context_mut().0)
2672        );
2673
2674        // But the hash keys are different from different funcs.
2675        let instance2 = Instance::new(&mut store, &module, &[])?;
2676        let f3 = instance2.get_func(&mut store, "f").unwrap();
2677        assert!(
2678            f1.hash_key(&mut store.as_context_mut().0)
2679                != f3.hash_key(&mut store.as_context_mut().0)
2680        );
2681
2682        Ok(())
2683    }
2684}