Struct soroban_wasmi::Func

pub struct Func(/* private fields */);

A Wasm or host function reference.

Implementations

impl Func

pub fn new<T>( ctx: impl AsContextMut<UserState = T>, ty: FuncType, func: impl Fn(Caller<'_, T>, &[Value], &mut [Value]) -> Result<(), Trap> + Send + Sync + 'static ) -> Self

Creates a new Func with the given arguments.

This is typically used to create a host-defined function to pass as an import to a Wasm module.

• ty: the signature that the given closure adheres to, used to indicate what the inputs and outputs are.
• func: the native code invoked whenever this Func will be called. The closure is provided a Caller as its first argument which allows it to query information about the Instance that is assocaited to the call.

Note

• The given FuncType ty must match the parameters and results otherwise the resulting host Func might trap during execution.
• It is the responsibility of the caller of Func::new to guarantee that the correct amount and types of results are written into the results buffer from the func closure. If an incorrect amount of results or types of results is written into the buffer then the remaining computation may fail in unexpected ways. This footgun can be avoided by using the typed Func::wrap method instead.
• Prefer using Func::wrap over this method if possible since Func instances created using this constructor have runtime overhead for every invokation that can be avoided by using Func::wrap.

pub fn wrap<T, Params, Results>( ctx: impl AsContextMut<UserState = T>, func: impl IntoFunc<T, Params, Results> ) -> Self

Creates a new host function from the given closure.

pub fn ty(&self, ctx: impl AsContext) -> FuncType

Returns the function type of the Func.

pub fn call<T>( &self, ctx: impl AsContextMut<UserState = T>, inputs: &[Value], outputs: &mut [Value] ) -> Result<(), Error>

Calls the Wasm or host function with the given inputs.

The result is written back into the outputs buffer.

Errors

• If the function returned a Trap.
• If the types of the inputs do not match the expected types for the function signature of self.
• If the number of input values does not match the expected number of inputs required by the function signature of self.
• If the number of output values does not match the expected number of outputs required by the function signature of self.

pub fn call_resumable<T>( &self, ctx: impl AsContextMut<UserState = T>, inputs: &[Value], outputs: &mut [Value] ) -> Result<ResumableCall, Error>

Calls the Wasm or host function with the given inputs.

The result is written back into the outputs buffer.

Returns a resumable handle to the function invocation upon enountering host errors with which it is possible to handle the error and continue the execution as if no error occured.

Note

This is a non-standard WebAssembly API and might not be available at other WebAssembly engines. Please be aware that depending on this feature might mean a lock-in to wasmi for users.

Errors

• If the function returned a Wasm Trap.
• If the types of the inputs do not match the expected types for the function signature of self.
• If the number of input values does not match the expected number of inputs required by the function signature of self.
• If the number of output values does not match the expected number of outputs required by the function signature of self.

pub fn typed<Params, Results>( &self, ctx: impl AsContext ) -> Result<TypedFunc<Params, Results>, Error>

where Params: WasmParams, Results: WasmResults,

Creates a new TypedFunc from this Func.

Note

This performs static type checks given Params as parameter types to Func and Results as result types of Func so that those type checks can be avoided when calling the created TypedFunc.

Errors

If the function signature of self does not match Params and Results as parameter types and result types respectively.

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 From<Func> for Extern

fn from(func: Func) -> Self

Converts to this type from the input type.

impl From<Func> for FuncRef

fn from(func: Func) -> Self

Converts to this type from the input type.

impl From<Func> for Value

fn from(func: Func) -> Self

Converts to this type from the input type.

impl Copy for Func