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 /// # Progress
345 ///
346 /// For the wasm task being created in `call_concurrent` to make progress it
347 /// must be run within the scope of [`run_concurrent`]. If there are no
348 /// active calls to [`run_concurrent`] then the wasm task will appear as
349 /// stalled. This is typically not a concern as an [`Accessor`] is bound
350 /// by default to a scope of [`run_concurrent`].
351 ///
352 /// One situation in which this can arise, for example, is that if a
353 /// [`run_concurrent`] computation finishes its async closure before all
354 /// wasm tasks have completed, then there will be no scope of
355 /// [`run_concurrent`] anywhere. In this situation the wasm tasks that have
356 /// not yet completed will not make progress until [`run_concurrent`] is
357 /// called again.
358 ///
359 /// Embedders will need to ensure that this future is `await`'d within the
360 /// scope of [`run_concurrent`] to ensure that the value can be produced
361 /// during the `await` call.
362 ///
363 /// # Cancellation
364 ///
365 /// Cancelling an async task created via `call_concurrent`, at this time, is
366 /// only possible by dropping the store that the computation runs within.
367 /// With [#11833] implemented then it will be possible to request
368 /// cancellation of a task, but that is not yet implemented. Hard-cancelling
369 /// a task will only ever be possible by dropping the entire store and it is
370 /// not possible to remove just one task from a store.
371 ///
372 /// This async function behaves more like a "spawn" than a normal Rust async
373 /// function. When this function is invoked then metadata for the function
374 /// call is recorded in the store connected to the `accessor` argument and
375 /// the wasm invocation is from then on connected to the store. If the
376 /// future created by this function is dropped it does not cancel the
377 /// in-progress execution of the wasm task. Dropping the future
378 /// relinquishes the host's ability to learn about the result of the task
379 /// but the task will still progress and invoke callbacks and such until
380 /// completion.
381 ///
382 /// [`run_concurrent`]: crate::Store::run_concurrent
383 /// [#11833]: https://github.com/bytecodealliance/wasmtime/issues/11833
384 /// [`Accessor`]: crate::component::Accessor
385 ///
386 /// # Panics
387 ///
388 /// Panics if the store that the [`Accessor`] is derived from does not own
389 /// this function.
390 #[cfg(feature = "component-model-async")]
391 pub async fn call_concurrent(
392 self,
393 accessor: impl AsAccessor<Data: Send>,
394 params: &[Val],
395 results: &mut [Val],
396 ) -> Result<TaskExit> {
397 self.call_concurrent_dynamic(accessor, params, results, true)
398 .await
399 }
400
401 /// Internal helper function for `call_async` and `call_concurrent`.
402 #[cfg(feature = "component-model-async")]
403 async fn call_concurrent_dynamic(
404 self,
405 accessor: impl AsAccessor<Data: Send>,
406 params: &[Val],
407 results: &mut [Val],
408 call_post_return_automatically: bool,
409 ) -> Result<TaskExit> {
410 let result = accessor.as_accessor().with(|mut store| {
411 assert!(
412 store.as_context_mut().0.async_support(),
413 "cannot use `call_concurrent` when async support is not enabled on the config"
414 );
415 self.check_params_results(store.as_context_mut(), params, results)?;
416 let prepared = self.prepare_call_dynamic(
417 store.as_context_mut(),
418 params.to_vec(),
419 call_post_return_automatically,
420 )?;
421 concurrent::queue_call(store.as_context_mut(), prepared)
422 })?;
423
424 let (run_results, rx) = result.await?;
425 assert_eq!(run_results.len(), results.len());
426 for (result, slot) in run_results.into_iter().zip(results) {
427 *slot = result;
428 }
429 Ok(TaskExit(rx))
430 }
431
432 /// Calls `concurrent::prepare_call` with monomorphized functions for
433 /// lowering the parameters and lifting the result.
434 #[cfg(feature = "component-model-async")]
435 fn prepare_call_dynamic<'a, T: Send + 'static>(
436 self,
437 mut store: StoreContextMut<'a, T>,
438 params: Vec<Val>,
439 call_post_return_automatically: bool,
440 ) -> Result<PreparedCall<Vec<Val>>> {
441 let store = store.as_context_mut();
442
443 concurrent::prepare_call(
444 store,
445 self,
446 MAX_FLAT_PARAMS,
447 true,
448 call_post_return_automatically,
449 move |func, store, params_out| {
450 func.with_lower_context(store, call_post_return_automatically, |cx, ty| {
451 Self::lower_args(cx, ¶ms, ty, params_out)
452 })
453 },
454 move |func, store, results| {
455 let max_flat = if func.abi_async(store) {
456 MAX_FLAT_PARAMS
457 } else {
458 MAX_FLAT_RESULTS
459 };
460 let results = func.with_lift_context(store, |cx, ty| {
461 Self::lift_results(cx, ty, results, max_flat)?.collect::<Result<Vec<_>>>()
462 })?;
463 Ok(Box::new(results))
464 },
465 )
466 }
467
468 fn call_impl(
469 &self,
470 mut store: impl AsContextMut,
471 params: &[Val],
472 results: &mut [Val],
473 ) -> Result<()> {
474 let mut store = store.as_context_mut();
475
476 self.check_params_results(store.as_context_mut(), params, results)?;
477
478 if self.abi_async(store.0) {
479 unreachable!(
480 "async-lifted exports should have failed validation \
481 when `component-model-async` feature disabled"
482 );
483 }
484
485 // SAFETY: the chosen representations of type parameters to `call_raw`
486 // here should be generally safe to work with:
487 //
488 // * parameters use `MaybeUninit<[MaybeUninit<ValRaw>; MAX_FLAT_PARAMS]>`
489 // which represents the maximal possible number of parameters that can
490 // be passed to lifted component functions. This is modeled with
491 // `MaybeUninit` to represent how it all starts as uninitialized and
492 // thus can't be safely read during lowering.
493 //
494 // * results are modeled as `[ValRaw; MAX_FLAT_RESULTS]` which
495 // represents the maximal size of values that can be returned. Note
496 // that if the function doesn't actually have a return value then the
497 // `ValRaw` inside the array will have undefined contents. That is
498 // safe in Rust, however, due to `ValRaw` being a `union`. The
499 // contents should dynamically not be read due to the type of the
500 // function used here matching the actual lift.
501 unsafe {
502 self.call_raw(
503 store,
504 |cx, ty, dst: &mut MaybeUninit<[MaybeUninit<ValRaw>; MAX_FLAT_PARAMS]>| {
505 // SAFETY: it's safe to assume that
506 // `MaybeUninit<array-of-maybe-uninit>` is initialized because
507 // each individual element is still considered uninitialized.
508 let dst: &mut [MaybeUninit<ValRaw>] = dst.assume_init_mut();
509 Self::lower_args(cx, params, ty, dst)
510 },
511 |cx, results_ty, src: &[ValRaw; MAX_FLAT_RESULTS]| {
512 let max_flat = MAX_FLAT_RESULTS;
513 for (result, slot) in
514 Self::lift_results(cx, results_ty, src, max_flat)?.zip(results)
515 {
516 *slot = result?;
517 }
518 Ok(())
519 },
520 )
521 }
522 }
523
524 pub(crate) fn lifted_core_func(&self, store: &mut StoreOpaque) -> NonNull<VMFuncRef> {
525 let def = {
526 let instance = self.instance.id().get(store);
527 let (_ty, def, _options) = instance.component().export_lifted_function(self.index);
528 def.clone()
529 };
530 match self.instance.lookup_vmdef(store, &def) {
531 Export::Function(f) => f.vm_func_ref(store),
532 _ => unreachable!(),
533 }
534 }
535
536 pub(crate) fn post_return_core_func(&self, store: &StoreOpaque) -> Option<NonNull<VMFuncRef>> {
537 let instance = self.instance.id().get(store);
538 let component = instance.component();
539 let (_ty, _def, options) = component.export_lifted_function(self.index);
540 let post_return = component.env_component().options[options].post_return;
541 post_return.map(|i| instance.runtime_post_return(i))
542 }
543
544 pub(crate) fn abi_async(&self, store: &StoreOpaque) -> bool {
545 let instance = self.instance.id().get(store);
546 let component = instance.component();
547 let (_ty, _def, options) = component.export_lifted_function(self.index);
548 component.env_component().options[options].async_
549 }
550
551 pub(crate) fn abi_info<'a>(
552 &self,
553 store: &'a StoreOpaque,
554 ) -> (Options, InstanceFlags, TypeFuncIndex, &'a CanonicalOptions) {
555 let vminstance = self.instance.id().get(store);
556 let component = vminstance.component();
557 let (ty, _def, options_index) = component.export_lifted_function(self.index);
558 let raw_options = &component.env_component().options[options_index];
559 let options = Options::new_index(store, self.instance, options_index);
560 (
561 options,
562 vminstance.instance_flags(raw_options.instance),
563 ty,
564 raw_options,
565 )
566 }
567
568 /// Invokes the underlying wasm function, lowering arguments and lifting the
569 /// result.
570 ///
571 /// The `lower` function and `lift` function provided here are what actually
572 /// do the lowering and lifting. The `LowerParams` and `LowerReturn` types
573 /// are what will be allocated on the stack for this function call. They
574 /// should be appropriately sized for the lowering/lifting operation
575 /// happening.
576 ///
577 /// # Safety
578 ///
579 /// The safety of this function relies on the correct definitions of the
580 /// `LowerParams` and `LowerReturn` type. They must match the type of `self`
581 /// for the params/results that are going to be produced. Additionally
582 /// these types must be representable with a sequence of `ValRaw` values.
583 unsafe fn call_raw<T, Return, LowerParams, LowerReturn>(
584 &self,
585 mut store: StoreContextMut<'_, T>,
586 lower: impl FnOnce(
587 &mut LowerContext<'_, T>,
588 InterfaceType,
589 &mut MaybeUninit<LowerParams>,
590 ) -> Result<()>,
591 lift: impl FnOnce(&mut LiftContext<'_>, InterfaceType, &LowerReturn) -> Result<Return>,
592 ) -> Result<Return>
593 where
594 LowerParams: Copy,
595 LowerReturn: Copy,
596 {
597 let export = self.lifted_core_func(store.0);
598
599 #[repr(C)]
600 union Union<Params: Copy, Return: Copy> {
601 params: Params,
602 ret: Return,
603 }
604
605 let space = &mut MaybeUninit::<Union<LowerParams, LowerReturn>>::uninit();
606
607 // Double-check the size/alignment of `space`, just in case.
608 //
609 // Note that this alone is not enough to guarantee the validity of the
610 // `unsafe` block below, but it's definitely required. In any case LLVM
611 // should be able to trivially see through these assertions and remove
612 // them in release mode.
613 let val_size = mem::size_of::<ValRaw>();
614 let val_align = mem::align_of::<ValRaw>();
615 assert!(mem::size_of_val(space) % val_size == 0);
616 assert!(mem::size_of_val(map_maybe_uninit!(space.params)) % val_size == 0);
617 assert!(mem::size_of_val(map_maybe_uninit!(space.ret)) % val_size == 0);
618 assert!(mem::align_of_val(space) == val_align);
619 assert!(mem::align_of_val(map_maybe_uninit!(space.params)) == val_align);
620 assert!(mem::align_of_val(map_maybe_uninit!(space.ret)) == val_align);
621
622 self.with_lower_context(store.as_context_mut(), false, |cx, ty| {
623 cx.enter_call();
624 lower(cx, ty, map_maybe_uninit!(space.params))
625 })?;
626
627 // SAFETY: We are providing the guarantee that all the inputs are valid.
628 // The various pointers passed in for the function are all valid since
629 // they're coming from our store, and the `params_and_results` should
630 // have the correct layout for the core wasm function we're calling.
631 // Note that this latter point relies on the correctness of this module
632 // and `ComponentType` implementations, hence `ComponentType` being an
633 // `unsafe` trait.
634 unsafe {
635 crate::Func::call_unchecked_raw(
636 &mut store,
637 export,
638 NonNull::new(core::ptr::slice_from_raw_parts_mut(
639 space.as_mut_ptr().cast(),
640 mem::size_of_val(space) / mem::size_of::<ValRaw>(),
641 ))
642 .unwrap(),
643 )?;
644 }
645
646 // SAFETY: We're relying on the correctness of the structure of
647 // `LowerReturn` and the type-checking performed to acquire the
648 // `TypedFunc` to make this safe. It should be the case that
649 // `LowerReturn` is the exact representation of the return value when
650 // interpreted as `[ValRaw]`, and additionally they should have the
651 // correct types for the function we just called (which filled in the
652 // return values).
653 let ret: &LowerReturn = unsafe { map_maybe_uninit!(space.ret).assume_init_ref() };
654
655 // Lift the result into the host while managing post-return state
656 // here as well.
657 //
658 // After a successful lift the return value of the function, which
659 // is currently required to be 0 or 1 values according to the
660 // canonical ABI, is saved within the `Store`'s `FuncData`. This'll
661 // later get used in post-return.
662 // flags.set_needs_post_return(true);
663 let val = self.with_lift_context(store.0, |cx, ty| lift(cx, ty, ret))?;
664
665 // SAFETY: it's a contract of this function that `LowerReturn` is an
666 // appropriate representation of the result of this function.
667 let ret_slice = unsafe { storage_as_slice(ret) };
668
669 self.instance.id().get_mut(store.0).post_return_arg_set(
670 self.index,
671 match ret_slice.len() {
672 0 => ValRaw::i32(0),
673 1 => ret_slice[0],
674 _ => unreachable!(),
675 },
676 );
677 return Ok(val);
678 }
679
680 /// Invokes the `post-return` canonical ABI option, if specified, after a
681 /// [`Func::call`] has finished.
682 ///
683 /// This function is a required method call after a [`Func::call`] completes
684 /// successfully. After the embedder has finished processing the return
685 /// value then this function must be invoked.
686 ///
687 /// # Errors
688 ///
689 /// This function will return an error in the case of a WebAssembly trap
690 /// happening during the execution of the `post-return` function, if
691 /// specified.
692 ///
693 /// # Panics
694 ///
695 /// This function will panic if it's not called under the correct
696 /// conditions. This can only be called after a previous invocation of
697 /// [`Func::call`] completes successfully, and this function can only
698 /// be called for the same [`Func`] that was `call`'d.
699 ///
700 /// If this function is called when [`Func::call`] was not previously
701 /// called, then it will panic. If a different [`Func`] for the same
702 /// component instance was invoked then this function will also panic
703 /// because the `post-return` needs to happen for the other function.
704 ///
705 /// Panics if this is called on a function in an asynchronous store.
706 /// This only works with functions defined within a synchronous store.
707 #[inline]
708 pub fn post_return(&self, mut store: impl AsContextMut) -> Result<()> {
709 let store = store.as_context_mut();
710 assert!(
711 !store.0.async_support(),
712 "must use `post_return_async` when async support is enabled on the config"
713 );
714 self.post_return_impl(store)
715 }
716
717 /// Exactly like [`Self::post_return`] except for use on async stores.
718 ///
719 /// # Panics
720 ///
721 /// Panics if this is called on a function in a synchronous store. This
722 /// only works with functions defined within an asynchronous store.
723 #[cfg(feature = "async")]
724 pub async fn post_return_async(&self, mut store: impl AsContextMut<Data: Send>) -> Result<()> {
725 let mut store = store.as_context_mut();
726 assert!(
727 store.0.async_support(),
728 "cannot use `post_return_async` without enabling async support in the config"
729 );
730 // Future optimization opportunity: conditionally use a fiber here since
731 // some func's post_return will not need the async context (i.e. end up
732 // calling async host functionality)
733 store.on_fiber(|store| self.post_return_impl(store)).await?
734 }
735
736 fn post_return_impl(&self, mut store: impl AsContextMut) -> Result<()> {
737 let mut store = store.as_context_mut();
738
739 let index = self.index;
740 let vminstance = self.instance.id().get(store.0);
741 let component = vminstance.component();
742 let (_ty, _def, options) = component.export_lifted_function(index);
743 let post_return = self.post_return_core_func(store.0);
744 let mut flags =
745 vminstance.instance_flags(component.env_component().options[options].instance);
746 let mut instance = self.instance.id().get_mut(store.0);
747 let post_return_arg = instance.as_mut().post_return_arg_take(index);
748
749 unsafe {
750 // First assert that the instance is in a "needs post return" state.
751 // This will ensure that the previous action on the instance was a
752 // function call above. This flag is only set after a component
753 // function returns so this also can't be called (as expected)
754 // during a host import for example.
755 //
756 // Note, though, that this assert is not sufficient because it just
757 // means some function on this instance needs its post-return
758 // called. We need a precise post-return for a particular function
759 // which is the second assert here (the `.expect`). That will assert
760 // that this function itself needs to have its post-return called.
761 //
762 // The theory at least is that these two asserts ensure component
763 // model semantics are upheld where the host properly calls
764 // `post_return` on the right function despite the call being a
765 // separate step in the API.
766 assert!(
767 flags.needs_post_return(),
768 "post_return can only be called after a function has previously been called",
769 );
770 let post_return_arg = post_return_arg.expect("calling post_return on wrong function");
771
772 // This is a sanity-check assert which shouldn't ever trip.
773 assert!(!flags.may_enter());
774
775 // Unset the "needs post return" flag now that post-return is being
776 // processed. This will cause future invocations of this method to
777 // panic, even if the function call below traps.
778 flags.set_needs_post_return(false);
779
780 // Post return functions are forbidden from calling imports or
781 // intrinsics.
782 flags.set_may_leave(false);
783
784 // If the function actually had a `post-return` configured in its
785 // canonical options that's executed here.
786 //
787 // Note that if this traps (returns an error) this function
788 // intentionally leaves the instance in a "poisoned" state where it
789 // can no longer be entered because `may_enter` is `false`.
790 if let Some(func) = post_return {
791 crate::Func::call_unchecked_raw(
792 &mut store,
793 func,
794 NonNull::new(core::ptr::slice_from_raw_parts(&post_return_arg, 1).cast_mut())
795 .unwrap(),
796 )?;
797 }
798
799 // And finally if everything completed successfully then the "may
800 // enter" and "may leave" flags are set to `true` again here which
801 // enables further use of the component.
802 flags.set_may_enter(true);
803 flags.set_may_leave(true);
804
805 let (calls, host_table, _, instance) = store
806 .0
807 .component_resource_state_with_instance(self.instance);
808 ResourceTables {
809 host_table: Some(host_table),
810 calls,
811 guest: Some(instance.guest_tables()),
812 }
813 .exit_call()?;
814 }
815 Ok(())
816 }
817
818 fn lower_args<T>(
819 cx: &mut LowerContext<'_, T>,
820 params: &[Val],
821 params_ty: InterfaceType,
822 dst: &mut [MaybeUninit<ValRaw>],
823 ) -> Result<()> {
824 let params_ty = match params_ty {
825 InterfaceType::Tuple(i) => &cx.types[i],
826 _ => unreachable!(),
827 };
828 if params_ty.abi.flat_count(MAX_FLAT_PARAMS).is_some() {
829 let dst = &mut dst.iter_mut();
830
831 params
832 .iter()
833 .zip(params_ty.types.iter())
834 .try_for_each(|(param, ty)| param.lower(cx, *ty, dst))
835 } else {
836 Self::store_args(cx, ¶ms_ty, params, dst)
837 }
838 }
839
840 fn store_args<T>(
841 cx: &mut LowerContext<'_, T>,
842 params_ty: &TypeTuple,
843 args: &[Val],
844 dst: &mut [MaybeUninit<ValRaw>],
845 ) -> Result<()> {
846 let size = usize::try_from(params_ty.abi.size32).unwrap();
847 let ptr = cx.realloc(0, 0, params_ty.abi.align32, size)?;
848 let mut offset = ptr;
849 for (ty, arg) in params_ty.types.iter().zip(args) {
850 let abi = cx.types.canonical_abi(ty);
851 arg.store(cx, *ty, abi.next_field32_size(&mut offset))?;
852 }
853
854 dst[0].write(ValRaw::i64(ptr as i64));
855
856 Ok(())
857 }
858
859 fn lift_results<'a, 'b>(
860 cx: &'a mut LiftContext<'b>,
861 results_ty: InterfaceType,
862 src: &'a [ValRaw],
863 max_flat: usize,
864 ) -> Result<Box<dyn Iterator<Item = Result<Val>> + 'a>> {
865 let results_ty = match results_ty {
866 InterfaceType::Tuple(i) => &cx.types[i],
867 _ => unreachable!(),
868 };
869 if results_ty.abi.flat_count(max_flat).is_some() {
870 let mut flat = src.iter();
871 Ok(Box::new(
872 results_ty
873 .types
874 .iter()
875 .map(move |ty| Val::lift(cx, *ty, &mut flat)),
876 ))
877 } else {
878 let iter = Self::load_results(cx, results_ty, &mut src.iter())?;
879 Ok(Box::new(iter))
880 }
881 }
882
883 fn load_results<'a, 'b>(
884 cx: &'a mut LiftContext<'b>,
885 results_ty: &'a TypeTuple,
886 src: &mut core::slice::Iter<'_, ValRaw>,
887 ) -> Result<impl Iterator<Item = Result<Val>> + use<'a, 'b>> {
888 // FIXME(#4311): needs to read an i64 for memory64
889 let ptr = usize::try_from(src.next().unwrap().get_u32())?;
890 if ptr % usize::try_from(results_ty.abi.align32)? != 0 {
891 bail!("return pointer not aligned");
892 }
893
894 let bytes = cx
895 .memory()
896 .get(ptr..)
897 .and_then(|b| b.get(..usize::try_from(results_ty.abi.size32).unwrap()))
898 .ok_or_else(|| anyhow::anyhow!("pointer out of bounds of memory"))?;
899
900 let mut offset = 0;
901 Ok(results_ty.types.iter().map(move |ty| {
902 let abi = cx.types.canonical_abi(ty);
903 let offset = abi.next_field32_size(&mut offset);
904 Val::load(cx, *ty, &bytes[offset..][..abi.size32 as usize])
905 }))
906 }
907
908 #[cfg(feature = "component-model-async")]
909 pub(crate) fn instance(self) -> Instance {
910 self.instance
911 }
912
913 #[cfg(feature = "component-model-async")]
914 pub(crate) fn index(self) -> ExportIndex {
915 self.index
916 }
917
918 /// Creates a `LowerContext` using the configuration values of this lifted
919 /// function.
920 ///
921 /// The `lower` closure provided should perform the actual lowering and
922 /// return the result of the lowering operation which is then returned from
923 /// this function as well.
924 fn with_lower_context<T>(
925 self,
926 mut store: StoreContextMut<T>,
927 may_enter: bool,
928 lower: impl FnOnce(&mut LowerContext<T>, InterfaceType) -> Result<()>,
929 ) -> Result<()> {
930 let types = self.instance.id().get(store.0).component().types().clone();
931 let (options, mut flags, ty, _) = self.abi_info(store.0);
932
933 // Test the "may enter" flag which is a "lock" on this instance.
934 // This is immediately set to `false` afterwards and note that
935 // there's no on-cleanup setting this flag back to true. That's an
936 // intentional design aspect where if anything goes wrong internally
937 // from this point on the instance is considered "poisoned" and can
938 // never be entered again. The only time this flag is set to `true`
939 // again is after post-return logic has completed successfully.
940 unsafe {
941 if !flags.may_enter() {
942 bail!(crate::Trap::CannotEnterComponent);
943 }
944 flags.set_may_enter(false);
945 }
946
947 // Perform the actual lowering, where while this is running the
948 // component is forbidden from calling imports.
949 unsafe {
950 debug_assert!(flags.may_leave());
951 flags.set_may_leave(false);
952 }
953 let mut cx = LowerContext::new(store.as_context_mut(), &options, &types, self.instance);
954 let result = lower(&mut cx, InterfaceType::Tuple(types[ty].params));
955 unsafe { flags.set_may_leave(true) };
956 result?;
957
958 // If this is an async function and `may_enter == true` then we're
959 // allowed to reenter the component at this point, and otherwise flag a
960 // post-return call being required as we're about to enter wasm and
961 // afterwards need a post-return.
962 unsafe {
963 if may_enter && options.async_() {
964 flags.set_may_enter(true);
965 } else {
966 flags.set_needs_post_return(true);
967 }
968 }
969
970 Ok(())
971 }
972
973 /// Creates a `LiftContext` using the configuration values with this lifted
974 /// function.
975 ///
976 /// The closure `lift` provided should actually perform the lift itself and
977 /// the result of that closure is returned from this function call as well.
978 fn with_lift_context<R>(
979 self,
980 store: &mut StoreOpaque,
981 lift: impl FnOnce(&mut LiftContext, InterfaceType) -> Result<R>,
982 ) -> Result<R> {
983 let (options, _flags, ty, _) = self.abi_info(store);
984 let mut cx = LiftContext::new(store, &options, self.instance);
985 let ty = InterfaceType::Tuple(cx.types[ty].results);
986 lift(&mut cx, ty)
987 }
988}
989
990/// Represents the completion of a task created using
991/// `[Typed]Func::call_concurrent`.
992///
993/// In general, a guest task may continue running after returning a value.
994/// Moreover, any given guest task may create its own subtasks before or after
995/// returning and may exit before some or all of those subtasks have finished
996/// running. In that case, the still-running subtasks will be "reparented" to
997/// the nearest surviving caller, which may be the original host call. The
998/// future returned by `TaskExit::block` will resolve once all transitive
999/// subtasks created directly or indirectly by the original call to
1000/// `Instance::call_concurrent` have exited.
1001#[cfg(feature = "component-model-async")]
1002pub struct TaskExit(futures::channel::oneshot::Receiver<()>);
1003
1004#[cfg(feature = "component-model-async")]
1005impl TaskExit {
1006 /// Returns a future which will resolve once all transitive subtasks created
1007 /// directly or indirectly by the original call to
1008 /// `Instance::call_concurrent` have exited.
1009 pub async fn block(self, accessor: impl AsAccessor<Data: Send>) {
1010 // The current implementation makes no use of `accessor`, but future
1011 // implementations might (e.g. by using a more efficient mechanism than
1012 // a oneshot channel).
1013 _ = accessor;
1014
1015 // We don't care whether the sender sent us a value or was dropped
1016 // first; either one counts as a notification, so we ignore the result
1017 // once the future resolves:
1018 _ = self.0.await;
1019 }
1020}