Struct soroban_wasmi::Instance

pub struct Instance(/* private fields */);

An instantiated WebAssembly Module.

This type represents an instantiation of a Module. It primarily allows to access its exports to call functions, get or set globals, read or write memory, etc.

When interacting with any Wasm code you will want to create an Instance in order to execute anything.

Instances are owned by a Store. Create new instances using Linker::instantiate.

Implementations

impl Instance

pub fn new( store: impl AsContextMut, module: &Module, imports: &[Extern], ) -> Result<Instance, Error>

Creates a new Instance from the pre-compiled Module and the list of imports.

Uses the official [Wasm instantiation prodecure] in order to resolve and type-check the provided imports and match them with the required imports of the Module.

Note

• This function intentionally is rather low-level for Instance creation. Please use the Linker type for a more high-level API for Wasm module instantiation with name-based resolution.
• Wasm module instantiation implies running the Wasm start function which is not to be confused with WASI’s _start function.

Usage

The imports are intended to correspond 1:1 with the required imports as returned by Module::imports. For each import type returned by Module::imports, create an Extern which corresponds to that type. Collect the Extern values created this way into a list and pass them to this function.

Errors

• If the number of provided imports does not match the number of imports required by the Module.
• If the type of any provided Extern does not match the corresponding required ExternType.
• If the start function, that is run at the end of the Wasm module instantiation, traps.
• If Wasm module or instance related resource limits are exceeded.

Panics

If any Extern does not originate from the provided store.

pub fn get_export(&self, store: impl AsContext, name: &str) -> Option<Extern>

Returns the value exported to the given name if any.

Panics

Panics if store does not own this Instance.

pub fn get_func(&self, store: impl AsContext, name: &str) -> Option<Func>

Looks up an exported Func value by name.

Returns None if there was no export named name, or if there was but it wasn’t a function.

Panics

If store does not own this Instance.

pub fn get_typed_func<Params, Results>( &self, store: impl AsContext, name: &str, ) -> Result<TypedFunc<Params, Results>, Error>

where Params: WasmParams, Results: WasmResults,

Looks up an exported Func value by name.

Returns None if there was no export named name, or if there was but it wasn’t a function.

Errors

• If there is no export named name.
• If there is no exported function named name.
• If Params or Results do not match the exported function type.

Panics

If store does not own this Instance.

pub fn get_global(&self, store: impl AsContext, name: &str) -> Option<Global>

Looks up an exported Global value by name.

Returns None if there was no export named name, or if there was but it wasn’t a global variable.

Panics

If store does not own this Instance.

pub fn get_table(&self, store: impl AsContext, name: &str) -> Option<Table>

Looks up an exported Table value by name.

Returns None if there was no export named name, or if there was but it wasn’t a table.

Panics

If store does not own this Instance.

pub fn get_memory(&self, store: impl AsContext, name: &str) -> Option<Memory>

Looks up an exported Memory value by name.

Returns None if there was no export named name, or if there was but it wasn’t a table.

Panics

If store does not own this Instance.

pub fn exports<'ctx, T: 'ctx>( &self, store: impl Into<StoreContext<'ctx, T>>, ) -> ExportsIter<'ctx>

Returns an iterator over the exports of the Instance.

The order of the yielded exports is not specified.

Panics

Panics if store does not own this Instance.

Trait Implementations

impl Clone for Instance

fn clone(&self) -> Instance

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Instance

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

Formats the value using the given formatter.

impl PartialEq for Instance

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Instance

impl Eq for Instance

impl StructuralPartialEq for Instance