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: &Store, ty: FT, func: F) -> Function

where FT: Into<FunctionType>, F: Fn(&[Value<Function>]) -> Result<Vec<Value<Function>>, 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_native for less runtime overhead.

Examples

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

let f = Function::new(&store, &signature, |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(&store, I32_I32_TO_I32, |args| {
    let sum = args[0].unwrap_i32() + args[1].unwrap_i32();
    Ok(vec![Value::I32(sum)])
});

pub fn new_with_env<FT, F, Env>( store: &Store, ty: FT, env: Env, func: F, ) -> Function

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

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

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

Examples

#[derive(WasmerEnv, Clone)]
struct Env {
  multiplier: i32,
};
let env = Env { multiplier: 2 };

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

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

With constant signature:

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

#[derive(WasmerEnv, Clone)]
struct Env {
  multiplier: i32,
};
let env = Env { multiplier: 2 };

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

pub fn new_native<F, Args, Rets, Env>(store: &Store, func: F) -> Function

where F: HostFunction<Args, Rets, WithoutEnv, Env>, Args: WasmTypeList, Rets: WasmTypeList, Env: 'static,

Creates a new host Function from a native function.

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

Example

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

let f = Function::new_native(&store, sum);

pub fn new_native_with_env<F, Args, Rets, Env>( store: &Store, env: Env, func: F, ) -> Function

where F: HostFunction<Args, Rets, WithEnv, Env>, Args: WasmTypeList, Rets: WasmTypeList, Env: WasmerEnv + 'static,

Creates a new host Function from a native function and a provided environment.

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

Example

#[derive(WasmerEnv, Clone)]
struct Env {
    multiplier: i32,
};
let env = Env { multiplier: 2 };

fn sum_and_multiply(env: &Env, a: i32, b: i32) -> i32 {
    (a + b) * env.multiplier
}

let f = Function::new_native_with_env(&store, env, sum_and_multiply);

pub fn ty(&self) -> &FunctionType

Returns the FunctionType of the Function.

Example

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

let f = Function::new_native(&store, sum);

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

pub fn store(&self) -> &Store

Returns the Store where the Function belongs.

pub fn param_arity(&self) -> usize

Returns the number of parameters that this function takes.

Example

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

let f = Function::new_native(&store, sum);

assert_eq!(f.param_arity(), 2);

pub fn result_arity(&self) -> usize

Returns the number of results this function produces.

Example

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

let f = Function::new_native(&store, sum);

assert_eq!(f.result_arity(), 1);

pub fn call( &self, params: &[Value<Function>], ) -> Result<Box<[Value<Function>]>, 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(&[Value::I32(1), Value::I32(2)]).unwrap().to_vec(), vec![Value::I32(3)]);

pub fn native<Args, Rets>(&self) -> Result<NativeFunc<Args, Rets>, RuntimeError>

where Args: WasmTypeList, Rets: WasmTypeList,

Transform this WebAssembly function into a function with the native ABI. See NativeFunc to learn more.

Examples

let sum = instance.exports.get_function("sum").unwrap();
let sum_native = sum.native::<(i32, i32), i32>().unwrap();

assert_eq!(sum_native.call(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_native = sum.native::<(i64, i64), i32>().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_native = sum.native::<(i32, i32), i64>().unwrap();

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, formatter: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

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

fn to_export(&self) -> Export

This function is used when providedd the Extern as exportable, so it can be used while instantiating the Module.

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.

fn into_weak_instance_ref(&mut self)

Convert the extern internally to hold a weak reference to the InstanceRef. This is useful for preventing cycles, for example for data stored in a type implementing WasmerEnv.

impl From<Function> for Value<Function>

fn from(val: Function) -> Value<Function>

Converts to this type from the input type.

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

where Args: WasmTypeList, Rets: WasmTypeList,

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

Converts to this type from the input type.

impl MemoryUsage for Function

fn size_of_val(&self, visited: &mut dyn MemoryUsageTracker) -> usize

Returns the size of the referenced value in bytes.

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 WasmValueType for Function

unsafe fn write_value_to(&self, p: *mut i128)

Write the value.

unsafe fn read_value_from( store: &(dyn Any + 'static), p: *const i128, ) -> Function

Read the value.

impl StructuralPartialEq for Function