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