Struct Function 

pub(crate) struct Function(pub(crate) BackendFunction);

A WebAssembly function instance.

A function instance is the runtime representation of a function. It effectively is a closure of the original function (defined in either the host or the WebAssembly module) over the runtime crate::Instance of its originating crate::Module.

The module instance is used to resolve references to other definitions during execution of the function.

Spec: https://webassembly.github.io/spec/core/exec/runtime.html#function-instances

Panics

• Closures (functions with captured environments) are not currently supported with native functions. Attempting to create a native Function with one will result in a panic. Closures as host functions tracking issue

Tuple Fields

0: BackendFunction

Implementations

impl Function

pub fn into_sys(self) -> Function

Consume self into crate::backend::sys::function::Function.

pub fn as_sys(&self) -> &Function

Convert a reference to self into a reference to crate::backend::sys::function::Function.

pub fn as_sys_mut(&mut self) -> &mut Function

Convert a mutable reference to self into a mutable reference crate::backend::sys::function::Function.

impl Function

pub fn new<FT, F>(store: &mut impl AsStoreMut, ty: FT, func: F) -> Function

where FT: Into<FunctionType>, F: Fn(&[Value]) -> Result<Vec<Value>, RuntimeError> + 'static + Send + Sync,

Creates a new host Function (dynamic) with the provided signature.

If you know the signature of the host function at compile time, consider using Function::new_typed for less runtime overhead.

pub fn new_with_env<FT, F, T>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, ty: FT, func: F, ) -> Function

where T: Send + 'static, FT: Into<FunctionType>, F: Fn(FunctionEnvMut<'_, T>, &[Value]) -> Result<Vec<Value>, RuntimeError> + 'static + Send + Sync,

Creates a new host Function (dynamic) with the provided signature.

If you know the signature of the host function at compile time, consider using Function::new_typed_with_env for less runtime overhead.

Takes a FunctionEnv that is passed into func. If that is not required, Function::new might be an option as well.

Examples

let signature = FunctionType::new(vec![Type::I32, Type::I32], vec![Type::I32]);

let f = Function::new_with_env(&mut store, &env, &signature, |_env, args| {
    let sum = args[0].unwrap_i32() + args[1].unwrap_i32();
    Ok(vec![Value::I32(sum)])
});

With constant signature:

const I32_I32_TO_I32: ([Type; 2], [Type; 1]) = ([Type::I32, Type::I32], [Type::I32]);

let f = Function::new_with_env(&mut store, &env, I32_I32_TO_I32, |_env, args| {
    let sum = args[0].unwrap_i32() + args[1].unwrap_i32();
    Ok(vec![Value::I32(sum)])
});

pub fn new_typed<F, Args, Rets>( store: &mut impl AsStoreMut, func: F, ) -> Function

where F: HostFunction<(), Args, Rets, WithoutEnv> + 'static + Send + Sync, Args: WasmTypeList, Rets: WasmTypeList,

Creates a new host Function from a native function.

pub fn new_typed_with_env<T, F, Args, Rets>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, func: F, ) -> Function

where T: Send + 'static, F: HostFunction<T, Args, Rets, WithEnv> + 'static + Send + Sync, Args: WasmTypeList, Rets: WasmTypeList,

Creates a new host Function with an environment from a typed function.

The function signature is automatically retrieved using the Rust typing system.

Example

fn sum(_env: FunctionEnvMut<()>, a: i32, b: i32) -> i32 {
    a + b
}

let f = Function::new_typed_with_env(&mut store, &env, sum);

pub fn new_async<FT, F, Fut>( store: &mut impl AsStoreMut, ty: FT, func: F, ) -> Function

where FT: Into<FunctionType>, F: Fn(&[Value]) -> Fut + 'static, Fut: Future<Output = Result<Vec<Value>, RuntimeError>> + 'static,

Creates a new async host Function (dynamic) with the provided signature.

If you know the signature of the host function at compile time, consider using Self::new_typed_async for less runtime overhead.

The provided closure returns a future that resolves to the function results. When invoked synchronously (via Function::call) the future will run to completion immediately, provided it doesn’t suspend. When invoked through Function::call_async, the future may suspend and resume as needed.

pub fn new_with_env_async<FT, F, Fut, T>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, ty: FT, func: F, ) -> Function

where T: 'static, FT: Into<FunctionType>, F: Fn(AsyncFunctionEnvMut<T>, &[Value]) -> Fut + 'static, Fut: Future<Output = Result<Vec<Value>, RuntimeError>> + 'static,

Creates a new async host Function (dynamic) with the provided signature and environment.

If you know the signature of the host function at compile time, consider using Self::new_typed_with_env_async for less runtime overhead.

Takes an AsyncFunctionEnvMut that is passed into func. If that is not required, Self::new_async might be an option as well.

pub fn new_typed_async<F, Args, Rets>( store: &mut impl AsStoreMut, func: F, ) -> Function

where Rets: WasmTypeList + 'static, Args: WasmTypeList + 'static, F: AsyncHostFunction<(), Args, Rets, WithoutEnv> + 'static,

Creates a new async host Function from a native typed function.

The future can return either the raw result tuple or any type that implements IntoResult for the result tuple (e.g. Result<Rets, E>).

pub fn new_typed_with_env_async<T, F, Args, Rets>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, func: F, ) -> Function

where T: 'static, Rets: WasmTypeList + 'static, Args: WasmTypeList + 'static, F: AsyncHostFunction<T, Args, Rets, WithEnv> + 'static,

Creates a new async host Function with an environment from a typed function.

pub fn ty(&self, store: &impl AsStoreRef) -> FunctionType

Returns the [FunctionType] of the Function.

Example

fn sum(_env: FunctionEnvMut<()>, a: i32, b: i32) -> i32 {
    a + b
}

let f = Function::new_typed_with_env(&mut store, &env, sum);

assert_eq!(f.ty(&mut store).params(), vec![Type::I32, Type::I32]);
assert_eq!(f.ty(&mut store).results(), vec![Type::I32]);

pub fn param_arity(&self, store: &impl AsStoreRef) -> usize

Returns the number of parameters that this function takes.

Example

fn sum(_env: FunctionEnvMut<()>, a: i32, b: i32) -> i32 {
    a + b
}

let f = Function::new_typed_with_env(&mut store, &env, sum);

assert_eq!(f.param_arity(&mut store), 2);

pub fn result_arity(&self, store: &impl AsStoreRef) -> usize

Returns the number of results this function produces.

Example

fn sum(_env: FunctionEnvMut<()>, a: i32, b: i32) -> i32 {
    a + b
}

let f = Function::new_typed_with_env(&mut store, &env, sum);

assert_eq!(f.result_arity(&mut store), 1);

pub fn call( &self, store: &mut impl AsStoreMut, params: &[Value], ) -> Result<Box<[Value]>, RuntimeError>

Call the function.

Depending on where the Function is defined, it will call it.

1. If the function is defined inside a WebAssembly, it will call the trampoline for the function signature.
2. If the function is defined in the host (in a native way), it will call the trampoline.

Examples

let sum = instance.exports.get_function("sum").unwrap();

assert_eq!(sum.call(&mut store, &[Value::I32(1), Value::I32(2)]).unwrap().to_vec(), vec![Value::I32(3)]);

pub fn call_async( &self, store: &impl AsStoreAsync, params: Vec<Value>, ) -> impl Future<Output = Result<Box<[Value]>, RuntimeError>> + 'static

Calls the function asynchronously.

The returned future drives execution of the WebAssembly function on a coroutine stack. Host functions created with Function::new_async may suspend execution by awaiting futures, and their completion will resume the Wasm instance according to the JSPI proposal.

pub fn typed<Args, Rets>( &self, store: &impl AsStoreRef, ) -> Result<TypedFunction<Args, Rets>, RuntimeError>

where Args: WasmTypeList, Rets: WasmTypeList,

Transform this WebAssembly function into a typed function. See TypedFunction to learn more.

Examples

let sum = instance.exports.get_function("sum").unwrap();
let sum_typed: TypedFunction<(i32, i32), i32> = sum.typed(&mut store).unwrap();

assert_eq!(sum_typed.call(&mut store, 1, 2).unwrap(), 3);

Errors

If the Args generic parameter does not match the exported function an error will be raised:

let sum = instance.exports.get_function("sum").unwrap();

// This results in an error: `RuntimeError`
let sum_typed : TypedFunction<(i64, i64), i32> = sum.typed(&mut store).unwrap();

If the Rets generic parameter does not match the exported function an error will be raised:

let sum = instance.exports.get_function("sum").unwrap();

// This results in an error: `RuntimeError`
let sum_typed: TypedFunction<(i32, i32), i64> = sum.typed(&mut store).unwrap();

pub fn is_from_store(&self, store: &impl AsStoreRef) -> bool

Checks whether this Function can be used with the given store.

Trait Implementations

impl Clone for Function

fn clone(&self) -> Function

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Function

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

Formats the value using the given formatter.

impl<'a> Exportable<'a> for Function

fn get_self_from_extern( _extern: &'a Extern, ) -> Result<&'a Function, ExportError>

Implementation of how to get the export corresponding to the implementing type from an Instance by name.

impl From<Function> for Extern

fn from(r: Function) -> Extern

Converts to this type from the input type.

impl From<Function> for Value

fn from(val: Function) -> Value

Converts to this type from the input type.

impl<Args, Rets> From<TypedFunction<Args, Rets>> for Function

where Args: WasmTypeList, Rets: WasmTypeList,

fn from(other: TypedFunction<Args, Rets>) -> Function

Converts to this type from the input type.

impl NativeWasmType for Function

const WASM_TYPE: Type = Type::FuncRef

Type for this NativeWasmType.

type Abi = usize

The ABI for this type (i32, i64, f32, f64)

impl PartialEq for Function

fn eq(&self, other: &Function) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Function

impl StructuralPartialEq for Function