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

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 module_instantiate( &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

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 create_resumable( &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.

pub fn resume( &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.

pub fn access_fuel_mut<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(&validation_info, Vec::new(), None).unwrap().module_addr;
let func_addr = store.instance_export(module, "loops").unwrap().as_func().unwrap();
let mut resumable_ref = store.create_resumable(func_addr, Vec::new(), Some(0)).unwrap();
store.access_fuel_mut(&mut resumable_ref, |x| { assert_eq!(*x, Some(0)); *x = None; }).unwrap();

pub fn func_alloc_typed<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.

Panics & Unexpected Behavior

Same as Store::func_alloc.

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

Invokes a function without fuel.

This is a wrapper around Store::invoke.

pub fn invoke_typed_without_fuel<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 is a wrapper around Store::invoke.