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