pub struct Func(/* private fields */);
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
impl Func
sourcepub fn typed<Params, Return>(
&self,
store: impl AsContext,
) -> Result<TypedFunc<Params, Return>>
pub fn typed<Params, Return>( &self, store: impl AsContext, ) -> Result<TypedFunc<Params, Return>>
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}");
sourcepub fn params(&self, store: impl AsContext) -> Box<[Type]>
pub fn params(&self, store: impl AsContext) -> Box<[Type]>
Get the parameter types for this function.
sourcepub fn results(&self, store: impl AsContext) -> Box<[Type]>
pub fn results(&self, store: impl AsContext) -> Box<[Type]>
Get the result types for this function.
sourcepub fn call(
&self,
store: impl AsContextMut,
params: &[Val],
results: &mut [Val],
) -> Result<()>
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 typeresults
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.
sourcepub async fn call_async<T>(
&self,
store: impl AsContextMut<Data = T>,
params: &[Val],
results: &mut [Val],
) -> Result<()>where
T: Send,
pub async fn call_async<T>(
&self,
store: impl AsContextMut<Data = T>,
params: &[Val],
results: &mut [Val],
) -> Result<()>where
T: Send,
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.
sourcepub fn post_return(&self, store: impl AsContextMut) -> Result<()>
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.
sourcepub async fn post_return_async<T: Send>(
&self,
store: impl AsContextMut<Data = T>,
) -> Result<()>
pub async fn post_return_async<T: Send>( &self, store: impl AsContextMut<Data = T>, ) -> Result<()>
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§
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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