Struct wasmtime::Instance

pub struct Instance { /* fields omitted */ }

An instantiated WebAssembly module.

This type represents the instantiation of a Module. Once instantiated you can access the exports which are of type Extern and provide the ability to call functions, set globals, read memory, etc. This is where all the fun stuff happens!

An Instance is created from two inputs, a Module and a list of imports, provided as a list of Extern values. The Module is the wasm code that was compiled and we're instantiating, and the Extern imports are how we're satisfying the imports of the module provided. On successful instantiation an Instance will automatically invoke the wasm start function.

When interacting with any wasm code you'll want to make an Instance to call any code or execute anything!

Methods

impl Instance

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

Creates a new Instance from the previously compiled Module and list of imports specified.

This method instantiates the module provided with the imports, following the procedure in the core specification to instantiate. Instantiation can fail for a number of reasons (many specified below), but if successful the start function will be automatically run (if provided) and then the Instance will be returned.

Providing Imports

The imports array here is a bit tricky. The entries in the list of imports are intended to correspond 1:1 with the list of imports returned by Module::imports. Before calling Instance::new you'll want to inspect the return value of Module::imports and, for each import type, create an Extern which corresponds to that type. These Extern values are all then collected into a list and passed to this function.

Note that this function is intentionally relatively low level. It is the intention that we'll soon provide a higher level API which will be much more ergonomic for instantiating modules. If you need the full power of customization of imports, though, this is the method for you!

Errors

This function can fail for a number of reasons, including, but not limited to:

• The number of imports provided doesn't match the number of imports returned by the module's Module::imports method.
• The type of any Extern doesn't match the corresponding ExternType entry that it maps to.
• The start function in the instance, if present, traps.
• Module/instance resource limits are exceeded.

When instantiation fails it's recommended to inspect the return value to see why it failed, or bubble it upwards. If you'd like to specifically check for trap errors, you can use error.downcast::<Trap>().

pub fn store(&self) -> &Store

Returns the associated Store that this Instance is compiled into.

This is the Store that generally serves as a sort of global cache for various instance-related things.

pub fn module(&self) -> &Module

Returns the associated Module that this Instance instantiated.

The corresponding Module here is a static version of this Instance which can be used to learn information such as naming information about various functions.

pub fn exports(&self) -> &[Extern]

Returns the list of exported items from this Instance.

Note that the exports here do not have names associated with them, they're simply the values that are exported. To learn the value of each export you'll need to consult Module::exports. The list returned here maps 1:1 with the list that Module::exports returns, and ExportType contains the name of each export.

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

Looks up an exported Extern value by name.

This method will search the module for an export named name and return the value, if found.

Returns None if there was no export named name.

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 InstanceExt for Instance

unsafe fn set_signal_handler<H>(&self, handler: H) where
    H: 'static + Fn(c_int, *const siginfo_t, *const c_void) -> bool, 

The signal handler must be async-signal-safe.