wasmtime/runtime/
func.rs

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