wasmtime/runtime/
func.rs

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