Struct Store 

pub struct Store<'b, T: Config> {
    pub(crate) functions: AddrVec<FuncAddr, FuncInst<T>>,
    pub(crate) tables: AddrVec<TableAddr, TableInst>,
    pub(crate) memories: AddrVec<MemAddr, MemInst>,
    pub(crate) globals: AddrVec<GlobalAddr, GlobalInst>,
    pub(crate) elements: AddrVec<ElemAddr, ElemInst>,
    pub(crate) data: AddrVec<DataAddr, DataInst>,
    pub(crate) modules: AddrVec<ModuleAddr, ModuleInst<'b>>,
    pub user_data: T,
}

The store represents all global state that can be manipulated by WebAssembly programs. It consists of the runtime representation of all instances of functions, tables, memories, and globals, element segments, and data segments that have been allocated during the life time of the abstract machine. https://webassembly.github.io/spec/core/exec/runtime.html#store

Safety

All addresses contained in a store must be valid for their associated address vectors in the same store.

Fields

functions: AddrVec<FuncAddr, FuncInst<T>>

tables: AddrVec<TableAddr, TableInst>

memories: AddrVec<MemAddr, MemInst>

globals: AddrVec<GlobalAddr, GlobalInst>

elements: AddrVec<ElemAddr, ElemInst>

data: AddrVec<DataAddr, DataInst>

modules: AddrVec<ModuleAddr, ModuleInst<'b>>

An address space of modules instantiated within the context of this Store.

Although the WebAssembly Specification 2.0 does not specify module instances to be part of the Store, in reality they can be managed very similar to other instance types. Therefore, we extend the Store by a module address space along with a ModuleAddr index type.

user_data: T

Implementations

impl<'b, T: Config> Store<'b, T>

pub fn new(user_data: T) -> Self

Creates a new empty store with some user data

See: WebAssembly Specification 2.0 - 7.1.4 - store_init

pub unsafe fn module_instantiate( &mut self, validation_info: &ValidationInfo<'b>, extern_vals: Vec<ExternVal>, maybe_fuel: Option<u64>, ) -> Result<InstantiationOutcome, RuntimeError>

Instantiate a new module instance from a ValidationInfo in this Store.

Note that if this returns an Err(_), the store might be left in an ill-defined state. This might cause further operations to have unexpected results.

See: WebAssembly Specification 2.0 - 7.1.5 - module_instantiate

Safety

The caller has to guarantee that any address values contained in the ExternVals came from the current Store object.

pub unsafe fn instance_export( &self, module_addr: ModuleAddr, name: &str, ) -> Result<ExternVal, RuntimeError>

Gets an export of a specific module instance by its name

See: WebAssembly Specification 2.0 - 7.1.6 - instance_export

Safety

The caller has to guarantee that the ModuleAddr came from the current Store object.

pub unsafe fn func_alloc( &mut self, func_type: FuncType, host_func: fn(&mut T, Vec<Value>) -> Result<Vec<Value>, HaltExecutionError>, ) -> FuncAddr

Allocates a new function with some host code.

This type of function is also called a host function.

Panics & Unexpected Behavior

The specification states that:

This operation must make sure that the provided host function satisfies the pre- and post-conditions required for a function instance with type functype.

Therefore, all “invalid” host functions (e.g. those which return incorrect return values) can cause the interpreter to panic or behave unexpectedly.

See: https://webassembly.github.io/spec/core/exec/modules.html#host-functions See: WebAssembly Specification 2.0 - 7.1.7 - func_alloc

Safety

The caller has to guarantee that if the Values returned from the given host function are references, their addresses came either from the host function arguments or from the current Store object.

pub unsafe fn func_type(&self, func_addr: FuncAddr) -> FuncType

Gets the type of a function by its addr.

See: WebAssembly Specification 2.0 - 7.1.7 - func_type

Safety

The caller has to guarantee that the FuncAddr came from the current Store object.

pub unsafe fn invoke( &mut self, func_addr: FuncAddr, params: Vec<Value>, maybe_fuel: Option<u64>, ) -> Result<RunState<T>, RuntimeError>

See: WebAssembly Specification 2.0 - 7.1.7 - func_invoke

Safety

The caller has to guarantee that the given FuncAddr and any FuncAddr or ExternAddr values contained in the parameter values came from the current Store object.

pub unsafe fn table_alloc( &mut self, table_type: TableType, ref: Ref, ) -> Result<TableAddr, RuntimeError>

Allocates a new table with some table type and an initialization value ref and returns its table address.

See: WebAssembly Specification 2.0 - 7.1.8 - table_alloc

Safety

The caller has to guarantee that any FuncAddr or ExternAddr values contained in r#ref came from the current Store object.

pub unsafe fn table_type(&self, table_addr: TableAddr) -> TableType

Gets the type of some table by its addr.

See: WebAssembly Specification 2.0 - 7.1.8 - table_type

Safety

The caller has to guarantee that the given TableAddr came from the current Store object.

pub unsafe fn table_read( &self, table_addr: TableAddr, i: u32, ) -> Result<Ref, RuntimeError>

Reads a single reference from a table by its table address and an index into the table.

See: WebAssembly Specification 2.0 - 7.1.8 - table_read

Safety

The caller has to guarantee that the given TableAddr must come from the current Store object.

pub unsafe fn table_write( &mut self, table_addr: TableAddr, i: u32, ref: Ref, ) -> Result<(), RuntimeError>

Writes a single reference into a table by its table address and an index into the table.

See: WebAssembly Specification 2.0 - 7.1.8 - table_write

Safety

The caller has to guarantee that the given TableAddr and any FuncAddr or ExternAddr values contained in the Ref must come from the current Store object.

pub unsafe fn table_size(&self, table_addr: TableAddr) -> u32

Gets the current size of a table by its table address.

See: WebAssembly Specification 2.0 - 7.1.8 - table_size

Safety

The caller has to guarantee that the given TableAddr must come from the current Store object.

pub unsafe fn table_grow( &mut self, table_addr: TableAddr, n: u32, ref: Ref, ) -> Result<(), RuntimeError>

Grows a table referenced by its table address by n elements.

See: WebAssembly Specification 2.0 - 7.1.8 - table_grow

Safety

The caller has to guarantee that the given TableAddr and any FuncAddr or ExternAddr values contained in the Ref must come from the current Store object.

pub fn mem_alloc(&mut self, mem_type: MemType) -> MemAddr

Allocates a new linear memory and returns its memory address.

See: WebAssembly Specification 2.0 - 7.1.9 - mem_alloc

pub unsafe fn mem_type(&self, mem_addr: MemAddr) -> MemType

Gets the memory type of some memory by its memory address

See: WebAssemblySpecification 2.0 - 7.1.9 - mem_type

Safety

The caller has to guarantee that the given MemAddr came from the current Store object.

pub unsafe fn mem_read( &self, mem_addr: MemAddr, i: u32, ) -> Result<u8, RuntimeError>

Reads a byte from some memory by its memory address and an index into the memory

See: WebAssemblySpecification 2.0 - 7.1.9 - mem_read

Safety

The caller has to guarantee that the given MemAddr came from the current Store object.

pub unsafe fn mem_write( &self, mem_addr: MemAddr, i: u32, byte: u8, ) -> Result<(), RuntimeError>

Writes a byte into some memory by its memory address and an index into the memory

See: WebAssemblySpecification 2.0 - 7.1.9 - mem_write

Safety

The caller has to guarantee that the given MemAddr came from the current Store object.

pub unsafe fn mem_size(&self, mem_addr: MemAddr) -> u32

Gets the size of some memory by its memory address in pages.

See: WebAssemblySpecification 2.0 - 7.1.9 - mem_size

Safety

The caller has to guarantee that the given MemAddr came from the current Store object.

pub unsafe fn mem_grow( &mut self, mem_addr: MemAddr, n: u32, ) -> Result<(), RuntimeError>

Grows some memory by its memory address by n pages.

See: WebAssemblySpecification 2.0 - 7.1.9 - mem_grow

Safety

The caller has to guarantee that the given MemAddr came from the current Store object.

pub unsafe fn global_alloc( &mut self, global_type: GlobalType, val: Value, ) -> Result<GlobalAddr, RuntimeError>

Allocates a new global and returns its global address.

See: WebAssemblySpecification 2.0 - 7.1.10 - global_alloc

Safety

The caller has to guarantee that any FuncAddr or ExternAddr values contained in the Value came from the current Store object.

pub unsafe fn global_type(&self, global_addr: GlobalAddr) -> GlobalType

Returns the global type of some global instance by its addr.

See: WebAssembly Specification 2.0 - 7.1.10 - global_type

Safety

The caller has to guarantee that the given GlobalAddr came from the current Store object.

pub unsafe fn global_read(&self, global_addr: GlobalAddr) -> Value

Returns the current value of some global instance by its addr.

See: WebAssembly Specification 2.0 - 7.1.10 - global_read

Safety

The caller has to guarantee that the given GlobalAddr came from the current Store object.

pub unsafe fn global_write( &mut self, global_addr: GlobalAddr, val: Value, ) -> Result<(), RuntimeError>

Sets a new value of some global instance by its addr.

Errors

• RuntimeError::WriteOnImmutableGlobal
• RuntimeError::GlobalTypeMismatch

See: WebAssembly Specification 2.0 - 7.1.10 - global_write

Safety

The caller has to guarantee that the given GlobalAddr and any FuncAddr or ExternAddr values contained in the Value came from the current Store object.

unsafe fn alloc_func( &mut self, func: (TypeIdx, (Span, usize)), module_addr: ModuleAddr, ) -> FuncAddr

roughly matches https://webassembly.github.io/spec/core/exec/modules.html#functions with the addition of sidetable pointer to the input signature

Safety

The caller has to guarantee that

• the given ModuleAddr came from the current Store object.
• the given TypeIdx is valid in the module for the given ModuleAddr.

unsafe fn alloc_table(&mut self, table_type: TableType, reff: Ref) -> TableAddr

https://webassembly.github.io/spec/core/exec/modules.html#tables

Safety

The caller has to guarantee that any FuncAddr or ExternAddr values contained in the Ref came from the current Store object.

fn alloc_mem(&mut self, mem_type: MemType) -> MemAddr

https://webassembly.github.io/spec/core/exec/modules.html#memories

unsafe fn alloc_global( &mut self, global_type: GlobalType, val: Value, ) -> GlobalAddr

https://webassembly.github.io/spec/core/exec/modules.html#globals

Safety

The caller has to guarantee that any FuncAddr or ExternAddr values contained in the Value came from the current Store object.

unsafe fn alloc_elem(&mut self, ref_type: RefType, refs: Vec<Ref>) -> ElemAddr

https://webassembly.github.io/spec/core/exec/modules.html#element-segments

Safety

The caller has to guarantee that any FuncAddr or ExternAddr values contained in the Refs came from the current Store object.

fn alloc_data(&mut self, bytes: &[u8]) -> DataAddr

https://webassembly.github.io/spec/core/exec/modules.html#data-segments

pub unsafe fn create_resumable( &self, func_addr: FuncAddr, params: Vec<Value>, maybe_fuel: Option<u64>, ) -> Result<Resumable<T>, RuntimeError>

Creates a new resumable, which when resumed for the first time invokes the function function_ref is associated to, with the arguments params. The newly created resumable initially stores fuel units of fuel. Returns a [ResumableRef] associated to the newly created resumable on success.

Safety

The caller has to guarantee that the FuncAddr and any FuncAddr or ExternAddr values contained in the parameter values came from the current Store object.

pub unsafe fn resume( &mut self, resumable: Resumable<T>, ) -> Result<RunState<T>, RuntimeError>

Resumes the given Resumable. Returns a RunState that may contain a new Resumable depending on whether execution ran out of fuel or finished normally.

Safety

The caller has to guarantee that the Resumable came from the current Store object.

pub unsafe fn invoke_without_fuel( &mut self, function: FuncAddr, params: Vec<Value>, ) -> Result<Vec<Value>, RuntimeError>

Invokes a function without fuel.

This function is simply syntactic sugar for calling Store::invoke without any fuel and destructuring the resulting RunState.

Safety

The caller has to guarantee that the given FuncAddr and any FuncAddr or ExternAddr values contained in the parameter values came from the current Store object.

pub unsafe fn mem_access_mut_slice<R>( &self, memory: MemAddr, accessor: impl FnOnce(&mut [u8]) -> R, ) -> R

Allows a given closure to temporarily access the entire memory as a &mut [u8].

Safety

The caller has to guarantee that the given MemAddr came from the current Store object.

pub unsafe fn instance_exports( &self, module_addr: ModuleAddr, ) -> Vec<(String, ExternVal)>

Returns all exports of a module instance by its module address.

To get a single import by its known name, use Store::instance_export.

Safety

The caller has to guarantee that the given ModuleAddr came from the current Store object.