Struct wasmer::Function

pub struct Function { /* fields omitted */ }

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) -> Self where
    FT: Into<FunctionType>,
    F: Fn(&[Val]) -> Result<Vec<Val>, 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
) -> Self where
    FT: Into<FunctionType>,
    F: Fn(&Env, &[Val]) -> Result<Vec<Val>, RuntimeError> + 'static + Send + Sync,
    Env: Sized + 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) -> Self where
    F: HostFunction<Args, Rets, WithoutEnv, Env>,
    Args: WasmTypeList,
    Rets: WasmTypeList,
    Env: Sized + '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
) -> Self where
    F: HostFunction<Args, Rets, WithEnv, Env>,
    Args: WasmTypeList,
    Rets: WasmTypeList,
    Env: Sized + 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: &[Val]) -> Result<Box<[Val]>, 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

pub fn clone(&self) -> Function

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Function

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

Formats the value using the given formatter.

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

pub fn to_export(&self) -> Export

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

pub 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

pub fn from(r: Function) -> Self

Performs the conversion.

impl From<Function> for Val

pub fn from(val: Function) -> Self

Performs the conversion.

impl<Args, Rets> From<NativeFunc<Args, Rets>> for Function where
    Args: WasmTypeList,
    Rets: WasmTypeList, 

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

Performs the conversion.

impl PartialEq<Function> for Function

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralPartialEq for Function