Struct wasmtime::component::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<[Type]>

Get the parameter 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 asyncronous 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<T>( &self, store: impl AsContextMut<Data = T>, params: &[Val], results: &mut [Val] ) -> Result<()>

where T: Send,

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 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<T: Send>( &self, store: impl AsContextMut<Data = T> ) -> 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 copy 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