Struct wiggle::wasmtime_crate::Instance
source · [−]#[repr(transparent)]pub struct Instance(_);
Expand description
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. When interacting with any wasm code you’ll want to make an
Instance
to call any code or execute anything.
Instances are owned by a Store
which is passed in at
creation time. It’s recommended to create instances with
Linker::instantiate
or similar
Linker
methods, but a more low-level constructor is also
available as Instance::new
.
Implementations
sourceimpl Instance
impl Instance
sourcepub fn new(
store: impl AsContextMut,
module: &Module,
imports: &[Extern]
) -> Result<Instance, Error>
pub fn new(
store: impl AsContextMut,
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 specified in the module
) 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 performs 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 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. For an
easier time passing imports by doing name-based resolution it’s
recommended to instead use the Linker
type.
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 themodule
’sModule::imports
method. - The type of any
Extern
doesn’t match the correspondingExternType
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>()
.
Panics
This function will panic if called with a store associated with a
asynchronous config
. This function
will also panic if any Extern
supplied is not owned by store
.
sourcepub async fn new_async<T>(
store: impl AsContextMut<Data = T>,
module: &'_ Module,
imports: &'_ [Extern]
) -> Result<Instance, Error> where
T: Send,
pub async fn new_async<T>(
store: impl AsContextMut<Data = T>,
module: &'_ Module,
imports: &'_ [Extern]
) -> Result<Instance, Error> where
T: Send,
Same as Instance::new
, except for usage in [asynchronous stores].
For more details about this function see the documentation on
Instance::new
. The only difference between these two methods is that
this one will asynchronously invoke the wasm start function in case it
calls any imported function which is an asynchronous host function (e.g.
created with Func::new_async
.
Panics
This function will panic if called with a store associated with a
synchronous config
. This is only compatible with
stores associated with an asynchronous config
.
This function will also panic, like Instance::new
, if any Extern
specified does not belong to store
.
sourcepub fn exports<'a, T>(
&'a self,
store: impl Into<StoreContextMut<'a, T>>
) -> impl ExactSizeIterator + 'a where
T: 'a,
pub fn exports<'a, T>(
&'a self,
store: impl Into<StoreContextMut<'a, T>>
) -> impl ExactSizeIterator + 'a where
T: 'a,
sourcepub fn get_export(&self, store: impl AsContextMut, name: &str) -> Option<Extern>
pub fn get_export(&self, store: impl AsContextMut, 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
.
Panics
Panics if store
does not own this instance.
Why does get_export
take a mutable context?
This method requires a mutable context because an instance’s exports are lazily populated, and we cache them as they are accessed. This makes instantiating a module faster, but also means this method requires a mutable context.
sourcepub fn get_typed_func<Params, Results, S>(
&self,
store: S,
name: &str
) -> Result<TypedFunc<Params, Results>, Error> where
Params: WasmParams,
Results: WasmResults,
S: AsContextMut,
pub fn get_typed_func<Params, Results, S>(
&self,
store: S,
name: &str
) -> Result<TypedFunc<Params, Results>, Error> where
Params: WasmParams,
Results: WasmResults,
S: AsContextMut,
Looks up an exported Func
value by name and with its type.
This function is a convenience wrapper over Instance::get_func
and
Func::typed
. For more information see the linked documentation.
Returns an error if name
isn’t a function export or if the export’s
type did not match Params
or Results
Panics
Panics if store
does not own this instance.
sourcepub fn get_memory(&self, store: impl AsContextMut, name: &str) -> Option<Memory>
pub fn get_memory(&self, store: impl AsContextMut, name: &str) -> Option<Memory>
Looks up an exported SharedMemory
value by name.
Returns None
if there was no export named name
, or if there was but
it wasn’t a shared memory.
Panics
Panics if store
does not own this instance.
sourcepub fn get_global(&self, store: impl AsContextMut, name: &str) -> Option<Global>
pub fn get_global(&self, store: impl AsContextMut, name: &str) -> Option<Global>
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Instance
impl Send for Instance
impl Sync for Instance
impl Unpin for Instance
impl UnwindSafe for Instance
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> Pointable for T
impl<T> Pointable for T
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more