Struct wasmtime::Instance [−][src]
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!
Implementations
impl Instance[src]
impl Instance[src]pub fn new(
store: &Store,
module: &Module,
imports: &[Extern]
) -> Result<Instance, Error>[src]
store: &Store,
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.
Per the WebAssembly spec, instantiation includes running the module’s
start function, if it has one (not to be confused with the _start
function, which is not run).
Note that this is a low-level function that just performance an
instantiation. See the Linker struct for an API which provides a
convenient way to link imports and provides automatic Command and Reactor
behavior.
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
importsprovided doesn’t match the number of imports returned by themodule’sModule::importsmethod. - The type of any
Externdoesn’t match the correspondingExternTypeentry that it maps to. - The
startfunction 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 ty(&self) -> InstanceType[src]
Returns the type signature of this instance.
pub fn store(&self) -> &Store[src]
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 exports<'instance>(
&'instance self
) -> impl ExactSizeIterator<Item = Export<'instance>> + 'instance[src]
&'instance self
) -> impl ExactSizeIterator<Item = Export<'instance>> + 'instance
Returns the list of exported items from this Instance.
pub fn get_export(&self, name: &str) -> Option<Extern>[src]
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.
pub fn get_func(&self, name: &str) -> Option<Func>[src]
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.
pub fn get_table(&self, name: &str) -> Option<Table>[src]
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.
pub fn get_memory(&self, name: &str) -> Option<Memory>[src]
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 memory.
pub fn get_global(&self, name: &str) -> Option<Global>[src]
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.