Struct Func 

pub struct Func { /* private fields */ }

Available on crate features runtime and component-model only.

A WebAssembly component function which can be called.

This type is the dual of wasmtime::Func for component functions. An instance of Func represents a component function from a component Instance. Like with wasmtime::Func it’s possible to call functions either synchronously or asynchronously and either typed or untyped.

Implementations

impl Func

pub fn typed<Params, Return>( &self, store: impl AsContext, ) -> Result<TypedFunc<Params, Return>>

where Params: ComponentNamedList + Lower, Return: ComponentNamedList + Lift,

Attempt to cast this Func to a statically typed TypedFunc with the provided Params and Return.

This function will perform a type-check at runtime that the Func takes Params as parameters and returns Return. If the type-check passes then a TypedFunc will be returned which can be used to invoke the function in an efficient, statically-typed, and ergonomic manner.

The Params type parameter here is a tuple of the parameters to the function. A function which takes no arguments should use (), a function with one argument should use (T,), etc. Note that all Params must also implement the Lower trait since they’re going into wasm.

The Return type parameter is the return value of this function. A return value of () means that there’s no return (similar to a Rust unit return) and otherwise a type T can be specified. Note that the Return must also implement the Lift trait since it’s coming from wasm.

Types specified here must implement the ComponentType trait. This trait is implemented for built-in types to Rust such as integer primitives, floats, Option<T>, Result<T, E>, strings, Vec<T>, and more. As parameters you’ll be passing native Rust types.

See the documentation for ComponentType for more information about supported types.

Errors

If the function does not actually take Params as its parameters or return Return then an error will be returned.

Panics

This function will panic if self is not owned by the store specified.

Examples

Calling a function which takes no parameters and has no return value:

let typed = func.typed::<(), ()>(&store)?;
typed.call(store, ())?;

Calling a function which takes one string parameter and returns a string:

let typed = func.typed::<(&str,), (String,)>(&store)?;
let ret = typed.call(&mut store, ("Hello, ",))?.0;
println!("returned string was: {}", ret);

Calling a function which takes multiple parameters and returns a boolean:

let typed = func.typed::<(u32, Option<&str>, &[u8]), (bool,)>(&store)?;
let ok: bool = typed.call(&mut store, (1, Some("hello"), b"bytes!"))?.0;
println!("return value was: {ok}");

pub fn params(&self, store: impl AsContext) -> Box<[(String, Type)]>

Get the parameter names and types for this function.

pub fn results(&self, store: impl AsContext) -> Box<[Type]>

Get the result types for this function.

pub fn call( &self, store: impl AsContextMut, params: &[Val], results: &mut [Val], ) -> Result<()>

Invokes this function with the params given and returns the result.

The params provided must match the parameters that this function takes in terms of their types and the number of parameters. Results will be written to the results slice provided if the call completes successfully. The initial types of the values in results are ignored and values are overwritten to write the result. It’s required that the size of results exactly matches the number of results that this function produces.

Note that after a function is invoked the embedder needs to invoke Func::post_return to execute any final cleanup required by the guest. This function call is required to either call the function again or to call another function.

For more detailed information see the documentation of TypedFunc::call.

Errors

Returns an error in situations including but not limited to:

• params is not the right size or if the values have the wrong type
• results is not the right size
• A trap occurs while executing the function
• The function calls a host function which returns an error

See TypedFunc::call for more information in addition to wasmtime::Func::call.

Panics

Panics if this is called on a function in an asynchronous store. This only works with functions defined within a synchronous store. Also panics if store does not own this function.

pub async fn call_async( &self, store: impl AsContextMut<Data: Send>, params: &[Val], results: &mut [Val], ) -> Result<()>

Available on crate feature async only.

Exactly like Self::call except for use on async stores.

Note that after this Func::post_return_async will be used instead of the synchronous version at Func::post_return.

Panics

Panics if this is called on a function in a synchronous store. This only works with functions defined within an asynchronous store. Also panics if store does not own this function.

pub async fn call_concurrent( self, accessor: impl AsAccessor<Data: Send>, params: &[Val], results: &mut [Val], ) -> Result<TaskExit>

Available on crate feature component-model-async only.

Start a concurrent call to this function.

Unlike Self::call and Self::call_async (both of which require exclusive access to the store until the completion of the call), calls made using this method may run concurrently with other calls to the same instance. In addition, the runtime will call the post-return function (if any) automatically when the guest task completes – no need to explicitly call Func::post_return afterward.

This returns a TaskExit representing the completion of the guest task and any transitive subtasks it might create.

Progress

For the wasm task being created in call_concurrent to make progress it must be run within the scope of run_concurrent. If there are no active calls to run_concurrent then the wasm task will appear as stalled. This is typically not a concern as an Accessor is bound by default to a scope of run_concurrent.

One situation in which this can arise, for example, is that if a run_concurrent computation finishes its async closure before all wasm tasks have completed, then there will be no scope of run_concurrent anywhere. In this situation the wasm tasks that have not yet completed will not make progress until run_concurrent is called again.

Embedders will need to ensure that this future is await’d within the scope of run_concurrent to ensure that the value can be produced during the await call.

Cancellation

Cancelling an async task created via call_concurrent, at this time, is only possible by dropping the store that the computation runs within. With #11833 implemented then it will be possible to request cancellation of a task, but that is not yet implemented. Hard-cancelling a task will only ever be possible by dropping the entire store and it is not possible to remove just one task from a store.

This async function behaves more like a “spawn” than a normal Rust async function. When this function is invoked then metadata for the function call is recorded in the store connected to the accessor argument and the wasm invocation is from then on connected to the store. If the future created by this function is dropped it does not cancel the in-progress execution of the wasm task. Dropping the future relinquishes the host’s ability to learn about the result of the task but the task will still progress and invoke callbacks and such until completion.

Panics

Panics if the store that the Accessor is derived from does not own this function.

pub fn post_return(&self, store: impl AsContextMut) -> Result<()>

Invokes the post-return canonical ABI option, if specified, after a Func::call has finished.

This function is a required method call after a Func::call completes successfully. After the embedder has finished processing the return value then this function must be invoked.

Errors

This function will return an error in the case of a WebAssembly trap happening during the execution of the post-return function, if specified.

Panics

This function will panic if it’s not called under the correct conditions. This can only be called after a previous invocation of Func::call completes successfully, and this function can only be called for the same Func that was call’d.

If this function is called when Func::call was not previously called, then it will panic. If a different Func for the same component instance was invoked then this function will also panic because the post-return needs to happen for the other function.

Panics if this is called on a function in an asynchronous store. This only works with functions defined within a synchronous store.

pub async fn post_return_async( &self, store: impl AsContextMut<Data: Send>, ) -> Result<()>

Available on crate feature async only.

Exactly like Self::post_return except for use on async stores.

Panics

Panics if this is called on a function in a synchronous store. This only works with functions defined within an asynchronous store.

Trait Implementations

impl Clone for Func

fn clone(&self) -> Func

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Func

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Copy for Func