Struct wasmer_vm::InstanceHandle

pub struct InstanceHandle { /* fields omitted */ }

A handle holding an InstanceAllocator, 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 fn allocate_instance(module: &ModuleInfo) -> (NonNull<u8>, VMOffsets)

Allocates an instance for use with InstanceHandle::new.

Returns the instance pointer and the VMOffsets that describe the memory buffer pointed to by the instance pointer.

It should ideally return NonNull<Instance> rather than NonNull<u8>, however Instance is private, and we want to keep it private.

pub unsafe fn new(
    instance_ptr: NonNull<u8>,
    offsets: VMOffsets,
    module: Arc<ModuleInfo>,
    finished_functions: BoxedSlice<LocalFunctionIndex, FunctionBodyPtr>,
    finished_function_call_trampolines: BoxedSlice<SignatureIndex, VMTrampoline>,
    finished_memories: BoxedSlice<LocalMemoryIndex, Arc<dyn Memory>>,
    finished_tables: BoxedSlice<LocalTableIndex, Arc<dyn Table>>,
    finished_globals: BoxedSlice<LocalGlobalIndex, Arc<Global>>,
    imports: Imports,
    vmshared_signatures: BoxedSlice<SignatureIndex, VMSharedSignatureIndex>,
    host_state: Box<dyn Any>,
    import_initializers: Vec<(Option<ImportInitializerFuncPtr>, *mut c_void)>
) -> Result<Self, Trap>

Create a new InstanceHandle pointing at a new InstanceAllocator.

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:

• instance_ptr must point to valid memory sufficiently large for the Instance. instance_ptr will be owned by InstanceAllocator, see InstanceAllocator to learn more.
• 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 memory_definition_locations(
    instance_ptr: NonNull<u8>,
    offsets: &VMOffsets
) -> Vec<NonNull<VMMemoryDefinition>>

Get the locations of where the local VMMemoryDefinitions should be stored.

This function lets us create Memory objects on the host with backing memory in the VM.

Safety

• instance_ptr must point to enough memory that all of the offsets in offsets point to valid locations in memory, i.e. instance_ptr must have been allocated by InstanceHandle::allocate_instance.

pub unsafe fn table_definition_locations(
    instance_ptr: NonNull<u8>,
    offsets: &VMOffsets
) -> Vec<NonNull<VMTableDefinition>>

Get the locations of where the VMTableDefinitions should be stored.

This function lets us create Table objects on the host with backing memory in the VM.

Safety

• instance_ptr must point to enough memory that all of the offsets in offsets point to valid locations in memory, i.e. instance_ptr must have been allocated by InstanceHandle::allocate_instance.

pub unsafe fn finish_instantiation(
    &self,
    data_initializers: &[DataInitializer<'_>]
) -> Result<(), Trap>

Finishes the instantiation process started by Instance::new.

Safety

Only safe to call immediately after instantiation.

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 module(&self) -> &Arc<ModuleInfo>

Return a reference-counting pointer to a module.

pub fn module_ref(&self) -> &ModuleInfo

Return a reference to a module.

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

Lookup an export with the given name.

pub fn lookup_by_declaration(&self, export: &ExportIndex) -> VMExport

Lookup an export with the given export declaration.

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

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 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
) -> 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<VMCallerCheckedAnyfunc>

Get table element reference.

Returns None if index is out of bounds.

pub fn table_set(
    &self,
    table_index: LocalTableIndex,
    index: u32,
    val: VMCallerCheckedAnyfunc
) -> 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.

pub unsafe fn initialize_host_envs<Err: Sized>(
    &mut self,
    instance_ptr: *const c_void
) -> Result<(), Err>

Initializes the host environments.

Safety

• This function must be called with the correct Err type parameter: the error type is not visible to code in wasmer_vm, so it's the caller's responsibility to ensure these functions are called with the correct type.
• instance_ptr must point to a valid wasmer::Instance.

impl InstanceHandle

pub fn set_signal_handler<H>(&self, handler: H) where
    H: 'static + Fn(c_int, *const siginfo_t, *const c_void) -> bool, 

Set a custom signal handler

Trait Implementations

impl Debug for InstanceHandle

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

Formats the value using the given formatter.

impl PartialEq<InstanceHandle> for InstanceHandle

pub fn eq(&self, other: &InstanceHandle) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &InstanceHandle) -> bool

This method tests for !=.

impl StructuralPartialEq for InstanceHandle