Struct wasmer::Function

source ·

pub struct Function(pub(crate) Function);

Expand description

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

Tuple Fields§

§0: Function

Implementations§

source §

impl Function

source

pub fn new<FT, F>(store: &mut impl AsStoreMut, ty: FT, func: F) -> Selfwhere 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.

source

pub fn new_with_env<FT, F, T: Send + 'static>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, ty: FT, func: F ) -> Selfwhere 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)])
});

source

pub fn new_typed<F, Args, Rets>(store: &mut impl AsStoreMut, func: F) -> Selfwhere F: HostFunction<(), Args, Rets, WithoutEnv> + 'static + Send + Sync, Args: WasmTypeList, Rets: WasmTypeList,

Creates a new host Function from a native function.

source

pub fn new_typed_with_env<T: Send + 'static, F, Args, Rets>( store: &mut impl AsStoreMut, env: &FunctionEnv<T>, func: F ) -> Selfwhere 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);

source

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]);

source

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

source

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

source

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.

If the function is defined inside a WebAssembly, it will call the trampoline for the function signature.
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)]);

source

pub(crate) fn vm_funcref(&self, store: &impl AsStoreRef) -> VMFuncRef

source

pub(crate) unsafe fn from_vm_funcref( store: &mut impl AsStoreMut, funcref: VMFuncRef ) -> Self

source

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();

source