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(crate) id: StoreId,
    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.

id: StoreId

A unique identifier for this store. This is used to verify that stored objects belong to the current Store.

user_data: T

dormitory: Dormitory

Implementations

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

pub fn module_instantiate( &mut self, validation_info: &ValidationInfo<'b>, extern_vals: Vec<StoredExternVal>, maybe_fuel: Option<u32>, ) -> Result<StoredInstantiationOutcome, RuntimeError>

This is a safe variant of Store::module_instantiate_unchecked.

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

This is a safe variant of Store::instance_export_unchecked.

pub fn func_type( &self, func_addr: Stored<FuncAddr>, ) -> Result<FuncType, RuntimeError>

This is a safe variant of Store::func_type_unchecked.

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

This is a safe variant of Store::invoke_unchecked.

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

This is a safe variant of Store::table_alloc_unchecked.

pub fn table_type( &self, table_addr: Stored<TableAddr>, ) -> Result<TableType, RuntimeError>

This is a safe variant of Store::table_type_unchecked.

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

This is a safe variant of Store::table_read_unchecked.

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

This is a safe variant of Store::table_write_unchecked.

pub fn table_size( &self, table_addr: Stored<TableAddr>, ) -> Result<u32, RuntimeError>

This is a safe variant of Store::table_size_unchecked.

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

This is a safe variant of Store::mem_alloc_unchecked.

pub fn mem_type( &self, mem_addr: Stored<MemAddr>, ) -> Result<MemType, RuntimeError>

This is a safe variant of Store::mem_type_unchecked.

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

This is a safe variant of Store::mem_read_unchecked.

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

This is a safe variant of Store::mem_write_unchecked.

pub fn mem_size(&self, mem_addr: Stored<MemAddr>) -> Result<u32, RuntimeError>

This is a safe variant of Store::mem_size_unchecked.

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

This is a safe variant of Store::mem_grow_unchecked.

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

This is a safe variant of Store::global_alloc_unchecked.

pub fn global_type( &self, global_addr: Stored<GlobalAddr>, ) -> Result<GlobalType, RuntimeError>

This is a safe variant of Store::global_type_unchecked.

pub fn global_read( &self, global_addr: Stored<GlobalAddr>, ) -> Result<StoredValue, RuntimeError>

This is a safe variant of Store::global_read_unchecked.

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

This is a safe variant of Store::global_write_unchecked.

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

This is a safe variant of Store::create_resumable_unchecked.

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

This is a safe variant of Store::resume_unchecked.

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

This is a safe variant of Store::access_fuel_mut_unchecked.

pub fn invoke_without_fuel( &mut self, func_addr: Stored<FuncAddr>, params: Vec<StoredValue>, ) -> Result<Vec<StoredValue>, RuntimeError>

This is a safe variant of Store::invoke_without_fuel_unchecked.

pub fn invoke_typed_without_fuel<Params: StoredInteropValueList, Returns: StoredInteropValueList>( &mut self, function: Stored<FuncAddr>, params: Params, ) -> Result<Returns, RuntimeError>

This is a safe variant of Store::invoke_typed_without_fuel_unchecked.

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 module_instantiate_unchecked( &mut self, validation_info: &ValidationInfo<'b>, extern_vals: Vec<ExternVal>, maybe_fuel: Option<u32>, ) -> 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 fn instance_export_unchecked( &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 fn func_alloc_unchecked( &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 fn func_type_unchecked(&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 fn invoke_unchecked( &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

Safety

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

pub fn table_alloc_unchecked( &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 fn table_type_unchecked(&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 fn table_read_unchecked( &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 fn table_write_unchecked( &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 fn table_size_unchecked(&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 fn table_grow_unchecked( &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_unchecked(&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

A Note About Safety

This method is always safe. However it returns a MemAddr, which can only be used with other unchecked methods. Consider using the safe and stored Store::mem_alloc variant instead, which returns a Stored<MemAddr>.

pub fn mem_type_unchecked(&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 fn mem_read_unchecked( &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 fn mem_write_unchecked( &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 fn mem_size_unchecked(&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 fn mem_grow_unchecked( &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 fn global_alloc_unchecked( &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 fn global_type_unchecked(&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 fn global_read_unchecked(&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 fn global_write_unchecked( &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.

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

Safety

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

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

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.

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 fn create_resumable_unchecked( &self, func_addr: FuncAddr, params: Vec<Value>, maybe_fuel: Option<u32>, ) -> Result<ResumableRef, 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 fn resume_unchecked( &mut self, resumable_ref: ResumableRef, ) -> Result<RunState, RuntimeError>

resumes the resumable associated to resumable_ref. Returns a RunState associated to this resumable if the resumable ran out of fuel or completely executed.

Safety

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

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

Calls its argument f with a mutable reference of the fuel of the respective ResumableRef.

Fuel is stored as an Option<u32>, where None means that fuel is disabled and Some(x) means that x units of fuel is left. A ubiquitious use of this method would be using f to read or mutate the current fuel amount of the respective ResumableRef.

Example

use wasm::{resumable::RunState, validate,  Store};
// a simple module with a single function looping forever
let wasm = [ 0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
            0x01, 0x04, 0x01, 0x60, 0x00, 0x00, 0x03, 0x02,
            0x01, 0x00, 0x07, 0x09, 0x01, 0x05, 0x6c, 0x6f,
            0x6f, 0x70, 0x73, 0x00, 0x00, 0x0a, 0x09, 0x01,
            0x07, 0x00, 0x03, 0x40, 0x0c, 0x00, 0x0b, 0x0b ];
let validation_info = validate(&wasm).unwrap();

let mut store = Store::new(());
let module = store.module_instantiate_unchecked(&validation_info, Vec::new(), None).unwrap().module_addr;
let func_addr = store.instance_export_unchecked(module, "loops").unwrap().as_func().unwrap();
let mut resumable_ref = store.create_resumable_unchecked(func_addr, Vec::new(), Some(0)).unwrap();
store.access_fuel_mut_unchecked(&mut resumable_ref, |x| { assert_eq!(*x, Some(0)); *x = None; }).unwrap();

Safety

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

pub fn func_alloc_typed_unchecked<Params: InteropValueList, Returns: InteropValueList>( &mut self, host_func: fn(&mut T, Vec<Value>) -> Result<Vec<Value>, HaltExecutionError>, ) -> FuncAddr

Allocates a new function with a statically known type signature with some host code.

This function is simply syntactic sugar for calling Store::func_alloc_unchecked with statically know types.

Panics & Unexpected Behavior

Same as Store::func_alloc_unchecked.

pub fn invoke_without_fuel_unchecked( &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_unchecked without any fuel and destructuring the resulting RunState.

Safety

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

pub fn invoke_typed_without_fuel_unchecked<Params: InteropValueList, Returns: InteropValueList>( &mut self, function: FuncAddr, params: Params, ) -> Result<Returns, RuntimeError>

Invokes a function with a statically known type signature without fuel.

This function is simply syntactic sugar for calling Store::invoke_unchecked without any fuel and destructuring the resulting RunState with statically known types.

Safety

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