Struct Function

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

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 Instance of its originating 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

Implementations

impl Function

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

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: 'static>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, ty: FT, func: F, ) -> Self

where 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) -> Self

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: 'static, F, Args, Rets>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, func: F, ) -> Self

where 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 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 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 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 copy 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

Formats the value using the given formatter.

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

fn get_self_from_extern(_extern: &'a Extern) -> Result<&'a Self, 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) -> Self

Converts to this type from the input type.

impl From<Function> for Value

fn from(val: Function) -> Self

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

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