Struct wasmtime::component::TypedFunc

pub struct TypedFunc<Params, Return> { /* private fields */ }

A statically-typed version of Func which takes Params as input and returns Return.

This is an efficient way to invoke a WebAssembly component where if the inputs and output are statically known this can eschew the vast majority of machinery and checks when calling WebAssembly. This is the most optimized way to call a WebAssembly component.

Note that like Func this is a pointer within a Store and usage will panic if used with the wrong store.

This type is primarily created with the Func::typed API.

See ComponentType for more information about supported types.

Implementations

impl<Params, Return> TypedFunc<Params, Return>

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

pub unsafe fn new_unchecked(func: Func) -> TypedFunc<Params, Return>

Creates a new TypedFunc from the provided component Func, unsafely asserting that the underlying function takes Params as input and returns Return.

Unsafety

This is an unsafe function because it does not verify that the Func provided actually implements this signature. It’s up to the caller to have performed some other sort of check to ensure that the signature is correct.

pub fn func(&self) -> &Func

Returns the underlying un-typed Func that this TypedFunc references.

pub fn call(&self, store: impl AsContextMut, params: Params) -> Result<Return>

Calls the underlying WebAssembly component function using the provided params as input.

This method is used to enter into a component. Execution happens within the store provided. The params are copied into WebAssembly memory as appropriate and a core wasm function is invoked.

Post-return

In the component model each function can have a “post return” specified which allows cleaning up the arguments returned to the host. For example if WebAssembly returns a string to the host then it might be a uniquely allocated string which, after the host finishes processing it, needs to be deallocated in the wasm instance’s own linear memory to prevent memory leaks in wasm itself. The post-return canonical abi option is used to configured this.

To accommodate this feature of the component model after invoking a function via TypedFunc::call you must next invoke TypedFunc::post_return. Note that the return value of the function should be processed between these two function calls. The return value continues to be usable from an embedder’s perspective after post_return is called, but after post_return is invoked it may no longer retain the same value that the wasm module originally returned.

Also note that TypedFunc::post_return must be invoked irrespective of whether the canonical ABI option post-return was configured or not. This means that embedders must unconditionally call TypedFunc::post_return when a function returns. If this function call returns an error, however, then TypedFunc::post_return is not required.

Errors

This function can return an error for a number of reasons:

• If the wasm itself traps during execution.
• If the wasm traps while copying arguments into memory.
• If the wasm provides bad allocation pointers when copying arguments into memory.
• If the wasm returns a value which violates the canonical ABI.
• If this function’s instances cannot be entered, for example if the instance is currently calling a host function.
• If a previous function call occurred and the corresponding post_return hasn’t been invoked yet.

In general there are many ways that things could go wrong when copying types in and out of a wasm module with the canonical ABI, and certain error conditions are specific to certain types. For example a WebAssembly module can’t return an invalid char. When allocating space for this host to copy a string into the returned pointer must be in-bounds in memory.

If an error happens then the error should contain detailed enough information to understand which part of the canonical ABI went wrong and what to inspect.

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<T>( &self, store: impl AsContextMut<Data = T>, params: Params, ) -> Result<Return>

where T: Send, Params: Send + Sync, Return: Send + Sync,

Exactly like Self::call, except for use on asynchronous stores.

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<()>

See Func::post_return

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

See Func::post_return_async

Trait Implementations

impl<Params, Return> Clone for TypedFunc<Params, Return>

fn clone(&self) -> TypedFunc<Params, Return>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Params, Return> Copy for TypedFunc<Params, Return>