wasmtime/runtime/component/
func.rs

1use crate::component::instance::Instance;
2use crate::component::matching::InstanceType;
3use crate::component::storage::storage_as_slice;
4use crate::component::types::Type;
5use crate::component::values::Val;
6use crate::prelude::*;
7use crate::runtime::vm::component::{ComponentInstance, InstanceFlags, ResourceTables};
8use crate::runtime::vm::{Export, VMFuncRef};
9use crate::store::StoreOpaque;
10use crate::{AsContext, AsContextMut, StoreContextMut, ValRaw};
11use anyhow::Context as _;
12use core::mem::{self, MaybeUninit};
13use core::ptr::NonNull;
14use wasmtime_environ::component::{
15    CanonicalOptions, ExportIndex, InterfaceType, MAX_FLAT_PARAMS, MAX_FLAT_RESULTS, TypeFuncIndex,
16    TypeTuple,
17};
18
19#[cfg(feature = "component-model-async")]
20use crate::component::concurrent::{self, AsAccessor, PreparedCall};
21
22mod host;
23mod options;
24mod typed;
25pub use self::host::*;
26pub use self::options::*;
27pub use self::typed::*;
28
29/// A WebAssembly component function which can be called.
30///
31/// This type is the dual of [`wasmtime::Func`](crate::Func) for component
32/// functions. An instance of [`Func`] represents a component function from a
33/// component [`Instance`](crate::component::Instance). Like with
34/// [`wasmtime::Func`](crate::Func) it's possible to call functions either
35/// synchronously or asynchronously and either typed or untyped.
36#[derive(Copy, Clone, Debug)]
37#[repr(C)] // here for the C API.
38pub struct Func {
39    instance: Instance,
40    index: ExportIndex,
41}
42
43// Double-check that the C representation in `component/instance.h` matches our
44// in-Rust representation here in terms of size/alignment/etc.
45const _: () = {
46    #[repr(C)]
47    struct T(u64, u32);
48    #[repr(C)]
49    struct C(T, u32);
50    assert!(core::mem::size_of::<C>() == core::mem::size_of::<Func>());
51    assert!(core::mem::align_of::<C>() == core::mem::align_of::<Func>());
52    assert!(core::mem::offset_of!(Func, instance) == 0);
53};
54
55impl Func {
56    pub(crate) fn from_lifted_func(instance: Instance, index: ExportIndex) -> Func {
57        Func { instance, index }
58    }
59
60    /// Attempt to cast this [`Func`] to a statically typed [`TypedFunc`] with
61    /// the provided `Params` and `Return`.
62    ///
63    /// This function will perform a type-check at runtime that the [`Func`]
64    /// takes `Params` as parameters and returns `Return`. If the type-check
65    /// passes then a [`TypedFunc`] will be returned which can be used to
66    /// invoke the function in an efficient, statically-typed, and ergonomic
67    /// manner.
68    ///
69    /// The `Params` type parameter here is a tuple of the parameters to the
70    /// function. A function which takes no arguments should use `()`, a
71    /// function with one argument should use `(T,)`, etc. Note that all
72    /// `Params` must also implement the [`Lower`] trait since they're going
73    /// into wasm.
74    ///
75    /// The `Return` type parameter is the return value of this function. A
76    /// return value of `()` means that there's no return (similar to a Rust
77    /// unit return) and otherwise a type `T` can be specified. Note that the
78    /// `Return` must also implement the [`Lift`] trait since it's coming from
79    /// wasm.
80    ///
81    /// Types specified here must implement the [`ComponentType`] trait. This
82    /// trait is implemented for built-in types to Rust such as integer
83    /// primitives, floats, `Option<T>`, `Result<T, E>`, strings, `Vec<T>`, and
84    /// more. As parameters you'll be passing native Rust types.
85    ///
86    /// See the documentation for [`ComponentType`] for more information about
87    /// supported types.
88    ///
89    /// # Errors
90    ///
91    /// If the function does not actually take `Params` as its parameters or
92    /// return `Return` then an error will be returned.
93    ///
94    /// # Panics
95    ///
96    /// This function will panic if `self` is not owned by the `store`
97    /// specified.
98    ///
99    /// # Examples
100    ///
101    /// Calling a function which takes no parameters and has no return value:
102    ///
103    /// ```
104    /// # use wasmtime::component::Func;
105    /// # use wasmtime::Store;
106    /// # fn foo(func: &Func, store: &mut Store<()>) -> anyhow::Result<()> {
107    /// let typed = func.typed::<(), ()>(&store)?;
108    /// typed.call(store, ())?;
109    /// # Ok(())
110    /// # }
111    /// ```
112    ///
113    /// Calling a function which takes one string parameter and returns a
114    /// string:
115    ///
116    /// ```
117    /// # use wasmtime::component::Func;
118    /// # use wasmtime::Store;
119    /// # fn foo(func: &Func, mut store: Store<()>) -> anyhow::Result<()> {
120    /// let typed = func.typed::<(&str,), (String,)>(&store)?;
121    /// let ret = typed.call(&mut store, ("Hello, ",))?.0;
122    /// println!("returned string was: {}", ret);
123    /// # Ok(())
124    /// # }
125    /// ```
126    ///
127    /// Calling a function which takes multiple parameters and returns a boolean:
128    ///
129    /// ```
130    /// # use wasmtime::component::Func;
131    /// # use wasmtime::Store;
132    /// # fn foo(func: &Func, mut store: Store<()>) -> anyhow::Result<()> {
133    /// let typed = func.typed::<(u32, Option<&str>, &[u8]), (bool,)>(&store)?;
134    /// let ok: bool = typed.call(&mut store, (1, Some("hello"), b"bytes!"))?.0;
135    /// println!("return value was: {ok}");
136    /// # Ok(())
137    /// # }
138    /// ```
139    pub fn typed<Params, Return>(&self, store: impl AsContext) -> Result<TypedFunc<Params, Return>>
140    where
141        Params: ComponentNamedList + Lower,
142        Return: ComponentNamedList + Lift,
143    {
144        self._typed(store.as_context().0, None)
145    }
146
147    pub(crate) fn _typed<Params, Return>(
148        &self,
149        store: &StoreOpaque,
150        instance: Option<&ComponentInstance>,
151    ) -> Result<TypedFunc<Params, Return>>
152    where
153        Params: ComponentNamedList + Lower,
154        Return: ComponentNamedList + Lift,
155    {
156        self.typecheck::<Params, Return>(store, instance)?;
157        unsafe { Ok(TypedFunc::new_unchecked(*self)) }
158    }
159
160    fn typecheck<Params, Return>(
161        &self,
162        store: &StoreOpaque,
163        instance: Option<&ComponentInstance>,
164    ) -> Result<()>
165    where
166        Params: ComponentNamedList + Lower,
167        Return: ComponentNamedList + Lift,
168    {
169        let cx = InstanceType::new(instance.unwrap_or_else(|| self.instance.id().get(store)));
170        let ty = &cx.types[self.ty(store)];
171
172        Params::typecheck(&InterfaceType::Tuple(ty.params), &cx)
173            .context("type mismatch with parameters")?;
174        Return::typecheck(&InterfaceType::Tuple(ty.results), &cx)
175            .context("type mismatch with results")?;
176
177        Ok(())
178    }
179
180    /// Get the parameter names and types for this function.
181    pub fn params(&self, store: impl AsContext) -> Box<[(String, Type)]> {
182        let store = store.as_context();
183        let instance = self.instance.id().get(store.0);
184        let types = instance.component().types();
185        let func_ty = &types[self.ty(store.0)];
186        types[func_ty.params]
187            .types
188            .iter()
189            .zip(&func_ty.param_names)
190            .map(|(ty, name)| (name.clone(), Type::from(ty, &InstanceType::new(instance))))
191            .collect()
192    }
193
194    /// Get the result types for this function.
195    pub fn results(&self, store: impl AsContext) -> Box<[Type]> {
196        let store = store.as_context();
197        let instance = self.instance.id().get(store.0);
198        let types = instance.component().types();
199        let ty = self.ty(store.0);
200        types[types[ty].results]
201            .types
202            .iter()
203            .map(|ty| Type::from(ty, &InstanceType::new(instance)))
204            .collect()
205    }
206
207    fn ty(&self, store: &StoreOpaque) -> TypeFuncIndex {
208        let instance = self.instance.id().get(store);
209        let (ty, _, _) = instance.component().export_lifted_function(self.index);
210        ty
211    }
212
213    /// Invokes this function with the `params` given and returns the result.
214    ///
215    /// The `params` provided must match the parameters that this function takes
216    /// in terms of their types and the number of parameters. Results will be
217    /// written to the `results` slice provided if the call completes
218    /// successfully. The initial types of the values in `results` are ignored
219    /// and values are overwritten to write the result. It's required that the
220    /// size of `results` exactly matches the number of results that this
221    /// function produces.
222    ///
223    /// Note that after a function is invoked the embedder needs to invoke
224    /// [`Func::post_return`] to execute any final cleanup required by the
225    /// guest. This function call is required to either call the function again
226    /// or to call another function.
227    ///
228    /// For more detailed information see the documentation of
229    /// [`TypedFunc::call`].
230    ///
231    /// # Errors
232    ///
233    /// Returns an error in situations including but not limited to:
234    ///
235    /// * `params` is not the right size or if the values have the wrong type
236    /// * `results` is not the right size
237    /// * A trap occurs while executing the function
238    /// * The function calls a host function which returns an error
239    ///
240    /// See [`TypedFunc::call`] for more information in addition to
241    /// [`wasmtime::Func::call`](crate::Func::call).
242    ///
243    /// # Panics
244    ///
245    /// Panics if this is called on a function in an asynchronous store. This
246    /// only works with functions defined within a synchronous store. Also
247    /// panics if `store` does not own this function.
248    pub fn call(
249        &self,
250        mut store: impl AsContextMut,
251        params: &[Val],
252        results: &mut [Val],
253    ) -> Result<()> {
254        let mut store = store.as_context_mut();
255        assert!(
256            !store.0.async_support(),
257            "must use `call_async` when async support is enabled on the config"
258        );
259        self.call_impl(&mut store.as_context_mut(), params, results)
260    }
261
262    /// Exactly like [`Self::call`] except for use on async stores.
263    ///
264    /// Note that after this [`Func::post_return_async`] will be used instead of
265    /// the synchronous version at [`Func::post_return`].
266    ///
267    /// # Panics
268    ///
269    /// Panics if this is called on a function in a synchronous store. This
270    /// only works with functions defined within an asynchronous store. Also
271    /// panics if `store` does not own this function.
272    #[cfg(feature = "async")]
273    pub async fn call_async(
274        &self,
275        mut store: impl AsContextMut<Data: Send>,
276        params: &[Val],
277        results: &mut [Val],
278    ) -> Result<()> {
279        let store = store.as_context_mut();
280
281        #[cfg(feature = "component-model-async")]
282        {
283            store
284                .run_concurrent_trap_on_idle(async |store| {
285                    self.call_concurrent_dynamic(store, params, results, false)
286                        .await
287                        .map(drop)
288                })
289                .await?
290        }
291        #[cfg(not(feature = "component-model-async"))]
292        {
293            assert!(
294                store.0.async_support(),
295                "cannot use `call_async` without enabling async support in the config"
296            );
297            let mut store = store;
298            store
299                .on_fiber(|store| self.call_impl(store, params, results))
300                .await?
301        }
302    }
303
304    fn check_params_results<T>(
305        &self,
306        store: StoreContextMut<T>,
307        params: &[Val],
308        results: &mut [Val],
309    ) -> Result<()> {
310        let param_tys = self.params(&store);
311        if param_tys.len() != params.len() {
312            bail!(
313                "expected {} argument(s), got {}",
314                param_tys.len(),
315                params.len(),
316            );
317        }
318
319        let result_tys = self.results(&store);
320
321        if result_tys.len() != results.len() {
322            bail!(
323                "expected {} result(s), got {}",
324                result_tys.len(),
325                results.len(),
326            );
327        }
328
329        Ok(())
330    }
331
332    /// Start a concurrent call to this function.
333    ///
334    /// Unlike [`Self::call`] and [`Self::call_async`] (both of which require
335    /// exclusive access to the store until the completion of the call), calls
336    /// made using this method may run concurrently with other calls to the same
337    /// instance.  In addition, the runtime will call the `post-return` function
338    /// (if any) automatically when the guest task completes -- no need to
339    /// explicitly call `Func::post_return` afterward.
340    ///
341    /// This returns a [`TaskExit`] representing the completion of the guest
342    /// task and any transitive subtasks it might create.
343    ///
344    /// # Panics
345    ///
346    /// Panics if the store that the [`Accessor`] is derived from does not own
347    /// this function.
348    #[cfg(feature = "component-model-async")]
349    pub async fn call_concurrent(
350        self,
351        accessor: impl AsAccessor<Data: Send>,
352        params: &[Val],
353        results: &mut [Val],
354    ) -> Result<TaskExit> {
355        self.call_concurrent_dynamic(accessor, params, results, true)
356            .await
357    }
358
359    /// Internal helper function for `call_async` and `call_concurrent`.
360    #[cfg(feature = "component-model-async")]
361    async fn call_concurrent_dynamic(
362        self,
363        accessor: impl AsAccessor<Data: Send>,
364        params: &[Val],
365        results: &mut [Val],
366        call_post_return_automatically: bool,
367    ) -> Result<TaskExit> {
368        let result = accessor.as_accessor().with(|mut store| {
369            assert!(
370                store.as_context_mut().0.async_support(),
371                "cannot use `call_concurrent` when async support is not enabled on the config"
372            );
373            self.check_params_results(store.as_context_mut(), params, results)?;
374            let prepared = self.prepare_call_dynamic(
375                store.as_context_mut(),
376                params.to_vec(),
377                call_post_return_automatically,
378            )?;
379            concurrent::queue_call(store.as_context_mut(), prepared)
380        })?;
381
382        let (run_results, rx) = result.await?;
383        assert_eq!(run_results.len(), results.len());
384        for (result, slot) in run_results.into_iter().zip(results) {
385            *slot = result;
386        }
387        Ok(TaskExit(rx))
388    }
389
390    /// Calls `concurrent::prepare_call` with monomorphized functions for
391    /// lowering the parameters and lifting the result.
392    #[cfg(feature = "component-model-async")]
393    fn prepare_call_dynamic<'a, T: Send + 'static>(
394        self,
395        mut store: StoreContextMut<'a, T>,
396        params: Vec<Val>,
397        call_post_return_automatically: bool,
398    ) -> Result<PreparedCall<Vec<Val>>> {
399        let store = store.as_context_mut();
400
401        concurrent::prepare_call(
402            store,
403            self,
404            MAX_FLAT_PARAMS,
405            true,
406            call_post_return_automatically,
407            move |func, store, params_out| {
408                func.with_lower_context(store, call_post_return_automatically, |cx, ty| {
409                    Self::lower_args(cx, &params, ty, params_out)
410                })
411            },
412            move |func, store, results| {
413                let max_flat = if func.abi_async(store) {
414                    MAX_FLAT_PARAMS
415                } else {
416                    MAX_FLAT_RESULTS
417                };
418                let results = func.with_lift_context(store, |cx, ty| {
419                    Self::lift_results(cx, ty, results, max_flat)?.collect::<Result<Vec<_>>>()
420                })?;
421                Ok(Box::new(results))
422            },
423        )
424    }
425
426    fn call_impl(
427        &self,
428        mut store: impl AsContextMut,
429        params: &[Val],
430        results: &mut [Val],
431    ) -> Result<()> {
432        let mut store = store.as_context_mut();
433
434        self.check_params_results(store.as_context_mut(), params, results)?;
435
436        if self.abi_async(store.0) {
437            unreachable!(
438                "async-lifted exports should have failed validation \
439                 when `component-model-async` feature disabled"
440            );
441        }
442
443        // SAFETY: the chosen representations of type parameters to `call_raw`
444        // here should be generally safe to work with:
445        //
446        // * parameters use `MaybeUninit<[MaybeUninit<ValRaw>; MAX_FLAT_PARAMS]>`
447        //   which represents the maximal possible number of parameters that can
448        //   be passed to lifted component functions. This is modeled with
449        //   `MaybeUninit` to represent how it all starts as uninitialized and
450        //   thus can't be safely read during lowering.
451        //
452        // * results are modeled as `[ValRaw; MAX_FLAT_RESULTS]` which
453        //   represents the maximal size of values that can be returned. Note
454        //   that if the function doesn't actually have a return value then the
455        //   `ValRaw` inside the array will have undefined contents. That is
456        //   safe in Rust, however, due to `ValRaw` being a `union`. The
457        //   contents should dynamically not be read due to the type of the
458        //   function used here matching the actual lift.
459        unsafe {
460            self.call_raw(
461                store,
462                |cx, ty, dst: &mut MaybeUninit<[MaybeUninit<ValRaw>; MAX_FLAT_PARAMS]>| {
463                    // SAFETY: it's safe to assume that
464                    // `MaybeUninit<array-of-maybe-uninit>` is initialized because
465                    // each individual element is still considered uninitialized.
466                    let dst: &mut [MaybeUninit<ValRaw>] = dst.assume_init_mut();
467                    Self::lower_args(cx, params, ty, dst)
468                },
469                |cx, results_ty, src: &[ValRaw; MAX_FLAT_RESULTS]| {
470                    let max_flat = MAX_FLAT_RESULTS;
471                    for (result, slot) in
472                        Self::lift_results(cx, results_ty, src, max_flat)?.zip(results)
473                    {
474                        *slot = result?;
475                    }
476                    Ok(())
477                },
478            )
479        }
480    }
481
482    pub(crate) fn lifted_core_func(&self, store: &mut StoreOpaque) -> NonNull<VMFuncRef> {
483        let def = {
484            let instance = self.instance.id().get(store);
485            let (_ty, def, _options) = instance.component().export_lifted_function(self.index);
486            def.clone()
487        };
488        match self.instance.lookup_vmdef(store, &def) {
489            Export::Function(f) => f.vm_func_ref(store),
490            _ => unreachable!(),
491        }
492    }
493
494    pub(crate) fn post_return_core_func(&self, store: &StoreOpaque) -> Option<NonNull<VMFuncRef>> {
495        let instance = self.instance.id().get(store);
496        let component = instance.component();
497        let (_ty, _def, options) = component.export_lifted_function(self.index);
498        let post_return = component.env_component().options[options].post_return;
499        post_return.map(|i| instance.runtime_post_return(i))
500    }
501
502    pub(crate) fn abi_async(&self, store: &StoreOpaque) -> bool {
503        let instance = self.instance.id().get(store);
504        let component = instance.component();
505        let (_ty, _def, options) = component.export_lifted_function(self.index);
506        component.env_component().options[options].async_
507    }
508
509    pub(crate) fn abi_info<'a>(
510        &self,
511        store: &'a StoreOpaque,
512    ) -> (Options, InstanceFlags, TypeFuncIndex, &'a CanonicalOptions) {
513        let vminstance = self.instance.id().get(store);
514        let component = vminstance.component();
515        let (ty, _def, options_index) = component.export_lifted_function(self.index);
516        let raw_options = &component.env_component().options[options_index];
517        let options = Options::new_index(store, self.instance, options_index);
518        (
519            options,
520            vminstance.instance_flags(raw_options.instance),
521            ty,
522            raw_options,
523        )
524    }
525
526    /// Invokes the underlying wasm function, lowering arguments and lifting the
527    /// result.
528    ///
529    /// The `lower` function and `lift` function provided here are what actually
530    /// do the lowering and lifting. The `LowerParams` and `LowerReturn` types
531    /// are what will be allocated on the stack for this function call. They
532    /// should be appropriately sized for the lowering/lifting operation
533    /// happening.
534    ///
535    /// # Safety
536    ///
537    /// The safety of this function relies on the correct definitions of the
538    /// `LowerParams` and `LowerReturn` type. They must match the type of `self`
539    /// for the params/results that are going to be produced. Additionally
540    /// these types must be representable with a sequence of `ValRaw` values.
541    unsafe fn call_raw<T, Return, LowerParams, LowerReturn>(
542        &self,
543        mut store: StoreContextMut<'_, T>,
544        lower: impl FnOnce(
545            &mut LowerContext<'_, T>,
546            InterfaceType,
547            &mut MaybeUninit<LowerParams>,
548        ) -> Result<()>,
549        lift: impl FnOnce(&mut LiftContext<'_>, InterfaceType, &LowerReturn) -> Result<Return>,
550    ) -> Result<Return>
551    where
552        LowerParams: Copy,
553        LowerReturn: Copy,
554    {
555        let export = self.lifted_core_func(store.0);
556
557        #[repr(C)]
558        union Union<Params: Copy, Return: Copy> {
559            params: Params,
560            ret: Return,
561        }
562
563        let space = &mut MaybeUninit::<Union<LowerParams, LowerReturn>>::uninit();
564
565        // Double-check the size/alignment of `space`, just in case.
566        //
567        // Note that this alone is not enough to guarantee the validity of the
568        // `unsafe` block below, but it's definitely required. In any case LLVM
569        // should be able to trivially see through these assertions and remove
570        // them in release mode.
571        let val_size = mem::size_of::<ValRaw>();
572        let val_align = mem::align_of::<ValRaw>();
573        assert!(mem::size_of_val(space) % val_size == 0);
574        assert!(mem::size_of_val(map_maybe_uninit!(space.params)) % val_size == 0);
575        assert!(mem::size_of_val(map_maybe_uninit!(space.ret)) % val_size == 0);
576        assert!(mem::align_of_val(space) == val_align);
577        assert!(mem::align_of_val(map_maybe_uninit!(space.params)) == val_align);
578        assert!(mem::align_of_val(map_maybe_uninit!(space.ret)) == val_align);
579
580        self.with_lower_context(store.as_context_mut(), false, |cx, ty| {
581            cx.enter_call();
582            lower(cx, ty, map_maybe_uninit!(space.params))
583        })?;
584
585        // SAFETY: We are providing the guarantee that all the inputs are valid.
586        // The various pointers passed in for the function are all valid since
587        // they're coming from our store, and the `params_and_results` should
588        // have the correct layout for the core wasm function we're calling.
589        // Note that this latter point relies on the correctness of this module
590        // and `ComponentType` implementations, hence `ComponentType` being an
591        // `unsafe` trait.
592        unsafe {
593            crate::Func::call_unchecked_raw(
594                &mut store,
595                export,
596                NonNull::new(core::ptr::slice_from_raw_parts_mut(
597                    space.as_mut_ptr().cast(),
598                    mem::size_of_val(space) / mem::size_of::<ValRaw>(),
599                ))
600                .unwrap(),
601            )?;
602        }
603
604        // SAFETY: We're relying on the correctness of the structure of
605        // `LowerReturn` and the type-checking performed to acquire the
606        // `TypedFunc` to make this safe. It should be the case that
607        // `LowerReturn` is the exact representation of the return value when
608        // interpreted as `[ValRaw]`, and additionally they should have the
609        // correct types for the function we just called (which filled in the
610        // return values).
611        let ret: &LowerReturn = unsafe { map_maybe_uninit!(space.ret).assume_init_ref() };
612
613        // Lift the result into the host while managing post-return state
614        // here as well.
615        //
616        // After a successful lift the return value of the function, which
617        // is currently required to be 0 or 1 values according to the
618        // canonical ABI, is saved within the `Store`'s `FuncData`. This'll
619        // later get used in post-return.
620        // flags.set_needs_post_return(true);
621        let val = self.with_lift_context(store.0, |cx, ty| lift(cx, ty, ret))?;
622
623        // SAFETY: it's a contract of this function that `LowerReturn` is an
624        // appropriate representation of the result of this function.
625        let ret_slice = unsafe { storage_as_slice(ret) };
626
627        self.instance.id().get_mut(store.0).post_return_arg_set(
628            self.index,
629            match ret_slice.len() {
630                0 => ValRaw::i32(0),
631                1 => ret_slice[0],
632                _ => unreachable!(),
633            },
634        );
635        return Ok(val);
636    }
637
638    /// Invokes the `post-return` canonical ABI option, if specified, after a
639    /// [`Func::call`] has finished.
640    ///
641    /// This function is a required method call after a [`Func::call`] completes
642    /// successfully. After the embedder has finished processing the return
643    /// value then this function must be invoked.
644    ///
645    /// # Errors
646    ///
647    /// This function will return an error in the case of a WebAssembly trap
648    /// happening during the execution of the `post-return` function, if
649    /// specified.
650    ///
651    /// # Panics
652    ///
653    /// This function will panic if it's not called under the correct
654    /// conditions. This can only be called after a previous invocation of
655    /// [`Func::call`] completes successfully, and this function can only
656    /// be called for the same [`Func`] that was `call`'d.
657    ///
658    /// If this function is called when [`Func::call`] was not previously
659    /// called, then it will panic. If a different [`Func`] for the same
660    /// component instance was invoked then this function will also panic
661    /// because the `post-return` needs to happen for the other function.
662    ///
663    /// Panics if this is called on a function in an asynchronous store.
664    /// This only works with functions defined within a synchronous store.
665    #[inline]
666    pub fn post_return(&self, mut store: impl AsContextMut) -> Result<()> {
667        let store = store.as_context_mut();
668        assert!(
669            !store.0.async_support(),
670            "must use `post_return_async` when async support is enabled on the config"
671        );
672        self.post_return_impl(store)
673    }
674
675    /// Exactly like [`Self::post_return`] except for use on async stores.
676    ///
677    /// # Panics
678    ///
679    /// Panics if this is called on a function in a synchronous store. This
680    /// only works with functions defined within an asynchronous store.
681    #[cfg(feature = "async")]
682    pub async fn post_return_async(&self, mut store: impl AsContextMut<Data: Send>) -> Result<()> {
683        let mut store = store.as_context_mut();
684        assert!(
685            store.0.async_support(),
686            "cannot use `post_return_async` without enabling async support in the config"
687        );
688        // Future optimization opportunity: conditionally use a fiber here since
689        // some func's post_return will not need the async context (i.e. end up
690        // calling async host functionality)
691        store.on_fiber(|store| self.post_return_impl(store)).await?
692    }
693
694    fn post_return_impl(&self, mut store: impl AsContextMut) -> Result<()> {
695        let mut store = store.as_context_mut();
696
697        let index = self.index;
698        let vminstance = self.instance.id().get(store.0);
699        let component = vminstance.component();
700        let (_ty, _def, options) = component.export_lifted_function(index);
701        let post_return = self.post_return_core_func(store.0);
702        let mut flags =
703            vminstance.instance_flags(component.env_component().options[options].instance);
704        let mut instance = self.instance.id().get_mut(store.0);
705        let post_return_arg = instance.as_mut().post_return_arg_take(index);
706
707        unsafe {
708            // First assert that the instance is in a "needs post return" state.
709            // This will ensure that the previous action on the instance was a
710            // function call above. This flag is only set after a component
711            // function returns so this also can't be called (as expected)
712            // during a host import for example.
713            //
714            // Note, though, that this assert is not sufficient because it just
715            // means some function on this instance needs its post-return
716            // called. We need a precise post-return for a particular function
717            // which is the second assert here (the `.expect`). That will assert
718            // that this function itself needs to have its post-return called.
719            //
720            // The theory at least is that these two asserts ensure component
721            // model semantics are upheld where the host properly calls
722            // `post_return` on the right function despite the call being a
723            // separate step in the API.
724            assert!(
725                flags.needs_post_return(),
726                "post_return can only be called after a function has previously been called",
727            );
728            let post_return_arg = post_return_arg.expect("calling post_return on wrong function");
729
730            // This is a sanity-check assert which shouldn't ever trip.
731            assert!(!flags.may_enter());
732
733            // Unset the "needs post return" flag now that post-return is being
734            // processed. This will cause future invocations of this method to
735            // panic, even if the function call below traps.
736            flags.set_needs_post_return(false);
737
738            // Post return functions are forbidden from calling imports or
739            // intrinsics.
740            flags.set_may_leave(false);
741
742            // If the function actually had a `post-return` configured in its
743            // canonical options that's executed here.
744            //
745            // Note that if this traps (returns an error) this function
746            // intentionally leaves the instance in a "poisoned" state where it
747            // can no longer be entered because `may_enter` is `false`.
748            if let Some(func) = post_return {
749                crate::Func::call_unchecked_raw(
750                    &mut store,
751                    func,
752                    NonNull::new(core::ptr::slice_from_raw_parts(&post_return_arg, 1).cast_mut())
753                        .unwrap(),
754                )?;
755            }
756
757            // And finally if everything completed successfully then the "may
758            // enter" and "may leave" flags are set to `true` again here which
759            // enables further use of the component.
760            flags.set_may_enter(true);
761            flags.set_may_leave(true);
762
763            let (calls, host_table, _, instance) = store
764                .0
765                .component_resource_state_with_instance(self.instance);
766            ResourceTables {
767                host_table: Some(host_table),
768                calls,
769                guest: Some(instance.guest_tables()),
770            }
771            .exit_call()?;
772        }
773        Ok(())
774    }
775
776    fn lower_args<T>(
777        cx: &mut LowerContext<'_, T>,
778        params: &[Val],
779        params_ty: InterfaceType,
780        dst: &mut [MaybeUninit<ValRaw>],
781    ) -> Result<()> {
782        let params_ty = match params_ty {
783            InterfaceType::Tuple(i) => &cx.types[i],
784            _ => unreachable!(),
785        };
786        if params_ty.abi.flat_count(MAX_FLAT_PARAMS).is_some() {
787            let dst = &mut dst.iter_mut();
788
789            params
790                .iter()
791                .zip(params_ty.types.iter())
792                .try_for_each(|(param, ty)| param.lower(cx, *ty, dst))
793        } else {
794            Self::store_args(cx, &params_ty, params, dst)
795        }
796    }
797
798    fn store_args<T>(
799        cx: &mut LowerContext<'_, T>,
800        params_ty: &TypeTuple,
801        args: &[Val],
802        dst: &mut [MaybeUninit<ValRaw>],
803    ) -> Result<()> {
804        let size = usize::try_from(params_ty.abi.size32).unwrap();
805        let ptr = cx.realloc(0, 0, params_ty.abi.align32, size)?;
806        let mut offset = ptr;
807        for (ty, arg) in params_ty.types.iter().zip(args) {
808            let abi = cx.types.canonical_abi(ty);
809            arg.store(cx, *ty, abi.next_field32_size(&mut offset))?;
810        }
811
812        dst[0].write(ValRaw::i64(ptr as i64));
813
814        Ok(())
815    }
816
817    fn lift_results<'a, 'b>(
818        cx: &'a mut LiftContext<'b>,
819        results_ty: InterfaceType,
820        src: &'a [ValRaw],
821        max_flat: usize,
822    ) -> Result<Box<dyn Iterator<Item = Result<Val>> + 'a>> {
823        let results_ty = match results_ty {
824            InterfaceType::Tuple(i) => &cx.types[i],
825            _ => unreachable!(),
826        };
827        if results_ty.abi.flat_count(max_flat).is_some() {
828            let mut flat = src.iter();
829            Ok(Box::new(
830                results_ty
831                    .types
832                    .iter()
833                    .map(move |ty| Val::lift(cx, *ty, &mut flat)),
834            ))
835        } else {
836            let iter = Self::load_results(cx, results_ty, &mut src.iter())?;
837            Ok(Box::new(iter))
838        }
839    }
840
841    fn load_results<'a, 'b>(
842        cx: &'a mut LiftContext<'b>,
843        results_ty: &'a TypeTuple,
844        src: &mut core::slice::Iter<'_, ValRaw>,
845    ) -> Result<impl Iterator<Item = Result<Val>> + use<'a, 'b>> {
846        // FIXME(#4311): needs to read an i64 for memory64
847        let ptr = usize::try_from(src.next().unwrap().get_u32())?;
848        if ptr % usize::try_from(results_ty.abi.align32)? != 0 {
849            bail!("return pointer not aligned");
850        }
851
852        let bytes = cx
853            .memory()
854            .get(ptr..)
855            .and_then(|b| b.get(..usize::try_from(results_ty.abi.size32).unwrap()))
856            .ok_or_else(|| anyhow::anyhow!("pointer out of bounds of memory"))?;
857
858        let mut offset = 0;
859        Ok(results_ty.types.iter().map(move |ty| {
860            let abi = cx.types.canonical_abi(ty);
861            let offset = abi.next_field32_size(&mut offset);
862            Val::load(cx, *ty, &bytes[offset..][..abi.size32 as usize])
863        }))
864    }
865
866    #[cfg(feature = "component-model-async")]
867    pub(crate) fn instance(self) -> Instance {
868        self.instance
869    }
870
871    #[cfg(feature = "component-model-async")]
872    pub(crate) fn index(self) -> ExportIndex {
873        self.index
874    }
875
876    /// Creates a `LowerContext` using the configuration values of this lifted
877    /// function.
878    ///
879    /// The `lower` closure provided should perform the actual lowering and
880    /// return the result of the lowering operation which is then returned from
881    /// this function as well.
882    fn with_lower_context<T>(
883        self,
884        mut store: StoreContextMut<T>,
885        may_enter: bool,
886        lower: impl FnOnce(&mut LowerContext<T>, InterfaceType) -> Result<()>,
887    ) -> Result<()> {
888        let types = self.instance.id().get(store.0).component().types().clone();
889        let (options, mut flags, ty, _) = self.abi_info(store.0);
890
891        // Test the "may enter" flag which is a "lock" on this instance.
892        // This is immediately set to `false` afterwards and note that
893        // there's no on-cleanup setting this flag back to true. That's an
894        // intentional design aspect where if anything goes wrong internally
895        // from this point on the instance is considered "poisoned" and can
896        // never be entered again. The only time this flag is set to `true`
897        // again is after post-return logic has completed successfully.
898        unsafe {
899            if !flags.may_enter() {
900                bail!(crate::Trap::CannotEnterComponent);
901            }
902            flags.set_may_enter(false);
903        }
904
905        // Perform the actual lowering, where while this is running the
906        // component is forbidden from calling imports.
907        unsafe {
908            debug_assert!(flags.may_leave());
909            flags.set_may_leave(false);
910        }
911        let mut cx = LowerContext::new(store.as_context_mut(), &options, &types, self.instance);
912        let result = lower(&mut cx, InterfaceType::Tuple(types[ty].params));
913        unsafe { flags.set_may_leave(true) };
914        result?;
915
916        // If this is an async function and `may_enter == true` then we're
917        // allowed to reenter the component at this point, and otherwise flag a
918        // post-return call being required as we're about to enter wasm and
919        // afterwards need a post-return.
920        unsafe {
921            if may_enter && options.async_() {
922                flags.set_may_enter(true);
923            } else {
924                flags.set_needs_post_return(true);
925            }
926        }
927
928        Ok(())
929    }
930
931    /// Creates a `LiftContext` using the configuration values with this lifted
932    /// function.
933    ///
934    /// The closure `lift` provided should actually perform the lift itself and
935    /// the result of that closure is returned from this function call as well.
936    fn with_lift_context<R>(
937        self,
938        store: &mut StoreOpaque,
939        lift: impl FnOnce(&mut LiftContext, InterfaceType) -> Result<R>,
940    ) -> Result<R> {
941        let (options, _flags, ty, _) = self.abi_info(store);
942        let mut cx = LiftContext::new(store, &options, self.instance);
943        let ty = InterfaceType::Tuple(cx.types[ty].results);
944        lift(&mut cx, ty)
945    }
946}
947
948/// Represents the completion of a task created using
949/// `[Typed]Func::call_concurrent`.
950///
951/// In general, a guest task may continue running after returning a value.
952/// Moreover, any given guest task may create its own subtasks before or after
953/// returning and may exit before some or all of those subtasks have finished
954/// running.  In that case, the still-running subtasks will be "reparented" to
955/// the nearest surviving caller, which may be the original host call.  The
956/// future returned by `TaskExit::block` will resolve once all transitive
957/// subtasks created directly or indirectly by the original call to
958/// `Instance::call_concurrent` have exited.
959#[cfg(feature = "component-model-async")]
960pub struct TaskExit(futures::channel::oneshot::Receiver<()>);
961
962#[cfg(feature = "component-model-async")]
963impl TaskExit {
964    /// Returns a future which will resolve once all transitive subtasks created
965    /// directly or indirectly by the original call to
966    /// `Instance::call_concurrent` have exited.
967    pub async fn block(self, accessor: impl AsAccessor<Data: Send>) {
968        // The current implementation makes no use of `accessor`, but future
969        // implementations might (e.g. by using a more efficient mechanism than
970        // a oneshot channel).
971        _ = accessor;
972
973        // We don't care whether the sender sent us a value or was dropped
974        // first; either one counts as a notification, so we ignore the result
975        // once the future resolves:
976        _ = self.0.await;
977    }
978}