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