Struct wasmer_near::Function [−][src]
pub struct Function { /* fields omitted */ }
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
Implementations
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)])
});
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,
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,
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);
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]);
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);
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);
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(&[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,
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
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
. Read more
impl<Args, Rets> From<NativeFunc<Args, Rets>> for Function where
Args: WasmTypeList,
Rets: WasmTypeList,
impl<Args, Rets> From<NativeFunc<Args, Rets>> for Function where
Args: WasmTypeList,
Rets: WasmTypeList,
Performs the conversion.
Returns the size of the referenced value in bytes. Read more
Write the value.
Read the value.
Auto Trait Implementations
impl !RefUnwindSafe for Function
impl !UnwindSafe for Function
Blanket Implementations
type ArchivedMetadata = ()
type ArchivedMetadata = ()
The archived version of the pointer metadata for this type.
pub fn pointer_metadata(
&<T as ArchivePointee>::ArchivedMetadata
) -> <T as Pointee>::Metadata
pub fn pointer_metadata(
&<T as ArchivePointee>::ArchivedMetadata
) -> <T as Pointee>::Metadata
Converts some archived metadata to the pointer metadata for itself.
Mutably borrows from an owned value. Read more