Struct wasmtime_runtime::InstanceHandle

source · [−]

pub struct InstanceHandle { /* private fields */ }

Expand description

A handle holding an Instance of a WebAssembly module.

Implementations

source

impl InstanceHandle

source

pub unsafe fn new(
 module: Arc<Module>,
 finished_functions: &PrimaryMap<DefinedFuncIndex, mut [VMFunctionBody ]>,
 imports: Imports<'_>,
 mem_creator: Option<&dyn RuntimeMemoryCreator>,
 lookup_shared_signature: &dyn Fn(SignatureIndex) -> VMSharedSignatureIndex,
 host_state: Box<dyn Any>,
 interrupts: const VMInterrupts,
 externref_activations_table: mut VMExternRefActivationsTable,
 stack_map_registry: mut StackMapRegistry
) -> Result<Self, InstantiationError>

Create a new InstanceHandle pointing at a new Instance.

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 wasmtime crate API rather than this type since that is vetted for safety.

It is your responsibility to ensure that the given raw externref_activations_table and stack_map_registry outlive this instance.

source

pub unsafe fn initialize(
 &self,
 is_bulk_memory: bool,
 data_initializers: &[DataInitializer<'_>]
) -> Result<(), InstantiationError>

Finishes the instantiation process started by Instance::new.

Only safe to call immediately after instantiation.

source

pub unsafe fn from_vmctx(vmctx: *mut VMContext) -> Self

Create a new InstanceHandle pointing at the instance pointed to by the given VMContext pointer.

Safety

This is unsafe because it doesn’t work on just any VMContext, it must be a VMContext allocated as part of an Instance.

source

pub fn vmctx(&self) -> &VMContext

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

source

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

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

source

pub fn module(&self) -> &Module

Return a reference to a module.

source

pub fn lookup(&self, field: &str) -> Option<Export<'_>>

Lookup an export with the given name.

source

pub fn lookup_by_declaration(&self, export: &EntityIndex) -> Export<'_>

Lookup an export with the given export declaration.

source

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.

source

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

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

source

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

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

source

pub fn memory_grow(
 &self,
 memory_index: DefinedMemoryIndex,
 delta: u32
) -> Option<u32>

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.

source

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

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

source

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

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

When the table is successfully grown, returns the original size of the table.

Returns None if memory can’t be grown by the specified amount of pages or if the init_value is the incorrect table element type.

source

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

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

When the table is successfully grown, returns the original size of the table.

Returns None if memory can’t be grown by the specified amount of pages or if the init_value is the incorrect table element type.

source

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

Get table element reference.

Returns None if index is out of bounds.

source

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

Set table element reference.

Returns an error if the index is out of bounds

source

pub fn defined_table_fill(
 &self,
 table_index: DefinedTableIndex,
 dst: u32,
 val: TableElement,
 len: u32
) -> Result<(), Trap>

Fill a region of the table.

Returns an error if the region is out of bounds or val is not of the correct type.

source

pub fn get_defined_table(&self, index: DefinedTableIndex) -> &Table

Get a table defined locally within this module.

source

pub unsafe fn clone(&self) -> InstanceHandle

Returns a clone of this instance.

This is unsafe because the returned handle here is just a cheap clone of the internals, there’s no lifetime tracking around its validity. You’ll need to ensure that the returned handles all go out of scope at the same time.

source

pub unsafe fn dealloc(&self)

Deallocates memory associated with this instance.

Note that this is unsafe because there might be other handles to this InstanceHandle elsewhere, and there’s nothing preventing usage of this handle after this function is called.