Struct wasmi::ModuleInstance

source ·

pub struct ModuleInstance { /* private fields */ }

Expand description

A module instance is the runtime representation of a module.

It is created by instantiating a module, and collects runtime representations of all entities that are imported or defined by the module, namely:

In order to instantiate a module you need to provide entities to satisfy every module’s imports (i.e. wasm modules don’t have optional imports).

After module is instantiated you can start invoking it’s exported functions with invoke_export.

Implementations§

source §

impl ModuleInstance

source

pub fn with_externvals<'a, 'i, I: Iterator<Item = &'i ExternVal>>(
loaded_module: &'a Module,
extern_vals: I
) -> Result<NotStartedModuleRef<'a>, Error>

Instantiate a module with given external values as imports.

See new for details.

source

pub fn new<'m, I: ImportResolver>(
loaded_module: &'m Module,
imports: &I
) -> Result<NotStartedModuleRef<'m>, Error>

Instantiate a module.

Note that in case of successful instantiation this function returns a reference to a module which start function is not called. In order to complete instantiatiation start function must be called. However, there are situations where you might need to do additional setup before calling start function. For such sitations this separation might be useful.

See NotStartedModuleRef for details.

Errors

Returns Err if the module cannot be instantiated.

This can happen if one of the imports can’t be satisfied (e.g module isn’t registered in imports resolver) or there is a mismatch between requested import and provided (e.g. module requested memory with no maximum size limit, however, was provided memory with the maximum size limit).

Examples

use wasmi::{ModuleInstance, ImportsBuilder, NopExternals};

// ModuleInstance::new returns instance which `start` function isn't called.
let not_started = ModuleInstance::new(
    &module,
    &ImportsBuilder::default()
)?;
// Call `start` function if any.
let instance = not_started.run_start(&mut NopExternals)?;

If you sure that the module doesn’t have start function you can use assert_no_start to get instantiated module without calling start function.

use wasmi::{ModuleInstance, ImportsBuilder, NopExternals};

// This will panic if the module actually contain `start` function.
let not_started = ModuleInstance::new(
    &module,
    &ImportsBuilder::default()
)?.assert_no_start();

source

pub fn invoke_export<E: Externals>(
 &self,
 func_name: &str,
 args: &[RuntimeValue],
 externals: &mut E
) -> Result<Option<RuntimeValue>, Error>

Invoke exported function by a name.

This function finds exported function by a name, and calls it with provided arguments and external state.

Errors

Returns Err if:

there are no export with a given name or this export is not a function,
given arguments doesn’t match to function signature,
trap occurred at the execution time,

Examples

Invoke a function that takes two numbers and returns sum of them.

assert_eq!(
    instance.invoke_export(
        "add",
        &[RuntimeValue::I32(5), RuntimeValue::I32(3)],
        &mut NopExternals,
    ).expect("failed to execute export"),
    Some(RuntimeValue::I32(8)),
);

source