wasmtime::component

Struct Func

Source
pub struct Func(/* private fields */);
Available on crate features runtime and component-model only.
Expand description

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§

Source§

impl Func

Source

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}");
Source

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

Get the parameter names and types for this function.

Source

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

Get the result types for this function.

Source

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.

Source

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.

Source

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.

Source

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§

Source§

impl Clone for Func

Source§

fn clone(&self) -> Func

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Func

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Copy for Func

Auto Trait Implementations§

§

impl Freeze for Func

§

impl RefUnwindSafe for Func

§

impl Send for Func

§

impl Sync for Func

§

impl Unpin for Func

§

impl UnwindSafe for Func

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.