Struct patract_wasmi::ModuleInstance

pub struct ModuleInstance { /* fields omitted */ }

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:

• functions,
• memories,
• tables,
• globals,

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

impl ModuleInstance

pub fn globals(&self) -> Ref<'_, Vec<GlobalRef>>

Access all globals. This is a non-standard API so it’s unlikely to be portable to other engines.

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.

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

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

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

Invoke exported function by a name using recycled stacks.

Errors

Same as invoke_export.

pub fn export_by_name(&self, name: &str) -> Option<ExternVal>

Find export by a name.

Returns None if there is no export with such name.

Trait Implementations

impl Debug for ModuleInstance

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

Formats the value using the given formatter.