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