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