Struct wasmtime_runtime::Instance

#[repr(C)]
pub struct Instance { /* private fields */ }

A type that roughly corresponds to a WebAssembly instance, but is also used for host-defined objects.

This structure is is never allocated directly but is instead managed through an InstanceHandle. This structure ends with a VMContext which has a dynamic size corresponding to the module configured within. Memory management of this structure is always externalized.

Instances here can correspond to actual instantiated modules, but it’s also used ubiquitously for host-defined objects. For example creating a host-defined memory will have a module that looks like it exports a single memory (and similar for other constructs).

This Instance type is used as a ubiquitous representation for WebAssembly values, whether or not they were created on the host or through a module.

Implementations

impl Instance

pub unsafe fn from_vmctx<R>( vmctx: *mut VMContext, f: impl FnOnce(&mut Instance) -> R ) -> R

Converts the provided *mut VMContext to an Instance pointer and runs the provided closure with the instance.

This method will move the vmctx pointer backwards to point to the original Instance that precedes it. The closure is provided a temporary version of the Instance pointer with a constrained lifetime to the closure to ensure it doesn’t accidentally escape.

Unsafety

Callers must validate that the vmctx pointer is a valid allocation and that it’s valid to acquire &mut Instance at this time. For example this can’t be called twice on the same VMContext to get two active pointers to the same Instance.

pub fn engine_type_index( &self, module_index: ModuleInternedTypeIndex ) -> VMSharedTypeIndex

Translate a module-level interned type index into an engine-level interned type index.

pub fn defined_memories<'a>( &'a self ) -> impl ExactSizeIterator<Item = (DefinedMemoryIndex, &'a Memory)> + 'a

Return the memories defined within this instance (not imported).

pub fn all_globals<'a>( &'a mut self ) -> impl ExactSizeIterator<Item = (GlobalIndex, ExportGlobal)> + 'a

Get all globals within this instance.

Returns both import and defined globals.

Returns both exported and non-exported globals.

Gives access to the full globals space.

pub fn defined_globals<'a>( &'a mut self ) -> impl ExactSizeIterator<Item = (DefinedGlobalIndex, ExportGlobal)> + 'a

Get the globals defined in this instance (not imported).

pub fn runtime_limits(&mut self) -> *mut *const VMRuntimeLimits

Return a pointer to the interrupts structure

pub fn epoch_ptr(&mut self) -> *mut *const AtomicU64

Return a pointer to the global epoch counter used by this instance.

pub fn gc_heap_base(&mut self) -> *mut *mut u8

Return a pointer to the GC heap base pointer.

pub fn gc_heap_bound(&mut self) -> *mut usize

Return a pointer to the GC heap bound.

pub fn gc_heap_data(&mut self) -> *mut *mut u8

Return a pointer to the collector-specific heap data.

pub fn store(&self) -> *mut dyn Store

Gets a pointer to this instance’s Store which was originally configured on creation.

Panics

This will panic if the originally configured store was None. That can happen for host functions so host functions can’t be queried what their original Store was since it’s just retained as null (since host functions are shared amongst threads and don’t all share the same store).

pub fn vmctx(&self) -> *mut VMContext

Return a reference to the vmctx used by compiled wasm code.

pub fn exports(&self) -> Iter<'_, String, EntityIndex>

Return an iterator over the exports of this instance.

Specifically, it provides access to the key-value pairs, where the keys are export names, and the values are export declarations which can be resolved lookup_by_declaration.

pub fn host_state(&self) -> &dyn Any

Return a reference to the custom state attached to this instance.

pub unsafe fn table_index( &mut self, table: &VMTableDefinition ) -> DefinedTableIndex

Return the table index for the given VMTableDefinition.

pub fn get_defined_memory(&mut self, index: DefinedMemoryIndex) -> *mut Memory

Get a locally-defined memory.

pub fn get_defined_table_with_lazy_init( &mut self, idx: DefinedTableIndex, range: impl Iterator<Item = u32> ) -> *mut Table

Gets the raw runtime table data structure owned by this instance given the provided idx.

The range specified is eagerly initialized for funcref tables.