Struct InstanceHandle

pub struct InstanceHandle { /* private fields */ }

A handle holding an InstanceRef, which holds an Instance of a WebAssembly module.

This is more or less a public facade of the private Instance, providing useful higher-level API.

Implementations

impl InstanceHandle

pub unsafe fn new( artifact: Arc<dyn Artifact>, allocator: InstanceAllocator, finished_memories: BoxedSlice<LocalMemoryIndex, Arc<dyn Memory>>, finished_tables: BoxedSlice<LocalTableIndex, Arc<dyn Table>>, finished_globals: BoxedSlice<LocalGlobalIndex, Arc<Global>>, imports: Imports, passive_data: BTreeMap<DataIndex, Arc<[u8]>>, host_state: Box<dyn Any>, imported_function_envs: BoxedSlice<FunctionIndex, ImportFunctionEnv>, instance_config: InstanceConfig, ) -> Self

Create a new InstanceHandle pointing at a new [InstanceRef].

Safety

This method is not necessarily inherently unsafe to call, but in general the APIs of an Instance are quite unsafe and have not been really audited for safety that much. As a result the unsafety here on this method is a low-overhead way of saying “this is an extremely unsafe type to work with”.

Extreme care must be taken when working with InstanceHandle and it’s recommended to have relatively intimate knowledge of how it works internally if you’d like to do so. If possible it’s recommended to use the wasmer crate API rather than this type since that is vetted for safety.

However the following must be taken care of before calling this function:

• The memory at instance.tables_ptr() must be initialized with data for all the local tables.
• The memory at instance.memories_ptr() must be initialized with data for all the local memories.

pub unsafe fn finish_instantiation(&self) -> Result<(), Trap>

Finishes the instantiation process started by Instance::new.

Safety

Only safe to call immediately after instantiation.

pub unsafe fn invoke_function( &self, vmctx: VMFunctionEnvironment, trampoline: VMTrampoline, callee: *const VMFunctionBody, values_vec: *mut u8, ) -> Result<(), Trap>

See [traphandlers::wasmer_call_trampoline].

pub fn vmctx(&self) -> &VMContext

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

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

Return a raw pointer to the vmctx used by compiled wasm code.

pub fn vmoffsets(&self) -> &VMOffsets

Return a reference to the VMOffsets to get offsets in the Self::vmctx_ptr region. Be careful when doing pointer arithmetic!

pub fn function_by_index(&self, idx: FunctionIndex) -> Option<VMFunction>

Lookup an exported function with the specified function index.

pub fn global_by_index(&self, index: GlobalIndex) -> Option<VMGlobal>

Obtain a reference to a global entity by its index.

pub fn lookup(&self, field: &str) -> Option<VMExtern>

Lookup an exported function with the given name.

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

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

pub fn memory_index(&self, memory: &VMMemoryDefinition) -> LocalMemoryIndex

Return the memory index for the given VMMemoryDefinition in this instance.

pub fn memory_grow<IntoPages>( &self, memory_index: LocalMemoryIndex, delta: IntoPages, ) -> Result<Pages, MemoryError>

where IntoPages: Into<Pages>,

Grow memory in this instance by the specified amount of pages.

Returns None if memory can’t be grown by the specified amount of pages.

pub fn table_index(&self, table: &VMTableDefinition) -> LocalTableIndex

Return the table index for the given VMTableDefinition in this instance.

pub fn table_grow( &self, table_index: LocalTableIndex, delta: u32, init_value: TableElement, ) -> Option<u32>

Grow table in this instance by the specified amount of pages.

Returns None if memory can’t be grown by the specified amount of pages.

pub fn table_get( &self, table_index: LocalTableIndex, index: u32, ) -> Option<TableElement>

Get table element reference.

Returns None if index is out of bounds.

pub fn table_set( &self, table_index: LocalTableIndex, index: u32, val: TableElement, ) -> Result<(), Trap>

Set table element reference.

Returns an error if the index is out of bounds

pub fn get_local_table(&self, index: LocalTableIndex) -> &dyn Table

Get a table defined locally within this module.

Trait Implementations

impl Debug for InstanceHandle

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

Formats the value using the given formatter.

impl PartialEq for InstanceHandle

fn eq(&self, other: &InstanceHandle) -> 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 StructuralPartialEq for InstanceHandle