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

fn clone(&self) -> Self

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

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 Self, 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 Extern

fn from(r: Function) -> Self

Performs the conversion.

impl From<Function> for Val

fn from(val: Function) -> Self

Performs the conversion.

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

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

Performs the conversion.

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

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

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

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

This method tests for !=.

impl WasmValueType for Function

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

Write the value.

unsafe fn read_value_from(store: &dyn Any, p: *const i128) -> Self

Read the value.

impl StructuralPartialEq for Function