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 registry: Registry,
    pub user_data: T,
    pub(crate) dormitory: Dormitory,
}

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

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.

registry: Registry

user_data: T

dormitory: Dormitory

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 fn add_module( &mut self, name: &str, validation_info: &ValidationInfo<'b>, maybe_fuel: Option<u32>, ) -> Result<ModuleAddr, RuntimeError>

instantiates a validated module with validation_info as validation evidence with name name with the steps in https://webassembly.github.io/spec/core/exec/modules.html#instantiation this method roughly matches the suggested embedder functionmodule_instantiate https://webassembly.github.io/spec/core/appendix/embedding.html#modules except external values for module instantiation are retrieved from self. Returns the module addr of the new module instance

pub 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

pub 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

pub 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

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

See: WebAssembly Specification 2.0 - 7.1.7 - func_invoke

pub 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

pub 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

pub 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

pub 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

pub 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

pub 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

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

pub 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

pub 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

pub 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

pub 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

pub 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

pub 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

pub 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

pub 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

fn alloc_func( &mut self, func: (usize, (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

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

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

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

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

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

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

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

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

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

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

pub fn reregister_module( &mut self, module_addr: ModuleAddr, name: &str, ) -> Result<(), RuntimeError>

This function allows an already instantiated module to be reregistered under a different name. All previous registers of this module are not affected.

Note: This method exists as a temporary solution because our suboptimal registry design. Because Store::add_module automatically registers all modules directly after instantiation, we still need to provide some way for only registering a module.

pub fn create_resumable( &self, func_addr: FuncAddr, params: Vec<Value>, maybe_fuel: Option<u32>, ) -> Result<ResumableRef, RuntimeError>

pub fn resume( &mut self, resumable_ref: ResumableRef, ) -> Result<RunState, RuntimeError>

pub fn access_fuel_mut<R>( &mut self, resumable_ref: &mut ResumableRef, f: impl FnOnce(&mut Option<u32>) -> R, ) -> Result<R, RuntimeError>