feat: rework public api, add missing export apis

Signed-off-by: Henry <mail@henrygressmann.de>

Author: explodingcamera

CHANGELOG.md

@@ -9,23 +9,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Support for the custom memory page sizes proposal ([#22](https://github.com/explodingcamera/tinywasm/pull/22) by [@danielstuart14](https://github.com/danielstuart14))
+- Support for the `custom_page_sizes` proposal ([#22](https://github.com/explodingcamera/tinywasm/pull/22) by [@danielstuart14](https://github.com/danielstuart14))
 - Support for the `tail_call` proposal
 - Support for the `memory64` proposal
-- Support for the fixed-width `simd` proposal
+- Support for the `simd` proposal
 - Support for the `relaxed_simd` proposal
 - Support for the `wide_arithmetic` proposal
 - New `Engine` API (`tinywasm::Engine` and `engine::Config`) for runtime configuration
 - Resumable function execution with fuel/time-budget APIs (`call_resumable`, `resume_with_fuel`, `resume_with_time_budget`, `ExecProgress`)
 - Host-function fuel APIs: `FuncContext::charge_fuel` and `FuncContext::remaining_fuel`
 - `engine::FuelPolicy` and `engine::Config::fuel_policy` for fuel accounting behavior
 - New `canonicalize_nans` feature flag to enable canonicalizing NaN values in the `f32`, `f64`, and `v128` types
+- Public API rework for runtime object access:
+  - export lookups: `func`, `func_typed`, `memory`, `memory_mut`
+  - table/global access: `table`, `table_mut`, `global`, `global_mut`, `global_get`, `global_set`
+  - generic export access: `extern_item`, `extern_item_mut`
+  - export iteration: `ModuleInstance::exports`
+  - module descriptors: `Module::imports`, `Module::exports`
+  - raw memory data access: `MemoryRef::data`/`data_size`, `MemoryRefMut::data`/`data_mut`/`data_size`
 
 ### Changed
 
 - Locals are now stored in the typed value stacks instead of a separate locals structure
 - Structured control flow is fully lowered to jump-oriented internal instructions during parsing
-- Stack and call-stack limits are configured via `engine::Config`
+- Stack and call-stack limits can now be configured via `engine::Config`
+- Module-internal by-index inspection APIs are now gated behind the `guest_debug` feature
 
 ### Breaking Changes
 
@@ -41,12 +49,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cargo feature `logging` was renamed to `log`
 - Increased MSRV to 1.90
 - `Error::ParseError` was renamed to `Error::Parser`, and `Error::Twasm` was added
+- `ModuleInstance` export lookup APIs were renamed:
+  - `exported_func_untyped` -> `func`
+  - `exported_func` -> `func_typed`
+  - `exported_memory` -> `memory`
+  - `exported_memory_mut` -> `memory_mut`
+- `Imports::link_module` now takes a `ModuleInstance` instead of a raw module instance id
+- `func_typed` now validates the exact wasm signature at lookup time and fails immediately on mismatches
 
 ### Fixed
 
 - Fixed archive **no_std** support which was broken in the previous release, and added more tests to ensure it stays working
 - `ModuleInstance::exported_memory` and `FuncContext::exported_memory` are now actually immutable ([#41](https://github.com/explodingcamera/tinywasm/pull/41))
 - Check returns in untyped host functions ([#27](https://github.com/explodingcamera/tinywasm/pull/27)) (thanks [@WhaleKit](https://github.com/WhaleKit))
+- `MemoryRefMut::copy_within(src, dst, len)` now follows its documented argument order
+- Imported tables created with `Extern::table(ty, init)` now honor the provided init value
 
 ## [0.8.0] - 2024-08-29
 

crates/cli/src/bin.rs

@@ -109,7 +109,7 @@ fn run(module: Module, func: Option<String>, args: &[WasmValue]) -> Result<()> {
     let instance = module.instantiate(&mut store, None)?;
 
     if let Some(func) = func {
-        let func = instance.exported_func_untyped(&store, &func)?;
+        let func = instance.func(&store, &func)?;
         let res = func.call(&mut store, args)?;
         info!("{res:?}");
     }

crates/parser/src/visit.rs

@@ -200,7 +200,7 @@ impl<'a, R: WasmModuleResources> wasmparser::VisitOperator<'a> for FunctionBuild
         visit_ref_func(RefFunc, u32), visit_table_fill(TableFill, u32), visit_table_get(TableGet, u32), visit_table_set(TableSet, u32), visit_table_grow(TableGrow, u32), visit_table_size(TableSize, u32),
 
         // Bulk Memory
-        visit_memory_init(MemoryInit, u32, u32), visit_memory_fill(MemoryFill, u32), visit_memory_copy(MemoryCopy, u32, u32), visit_table_init(TableInit, u32, u32), visit_data_drop(DataDrop, u32), visit_elem_drop(ElemDrop, u32),
+        visit_memory_init(MemoryInit, u32, u32), visit_memory_fill(MemoryFill, u32), visit_table_init(TableInit, u32, u32), visit_data_drop(DataDrop, u32), visit_elem_drop(ElemDrop, u32),
 
         // Wide Arithmetic
         visit_i64_add128(I64Add128), visit_i64_sub128(I64Sub128), visit_i64_mul_wide_s(I64MulWideS), visit_i64_mul_wide_u(I64MulWideU)
@@ -440,7 +440,11 @@ impl<'a, R: WasmModuleResources> wasmparser::VisitOperator<'a> for FunctionBuild
     }
 
     fn visit_table_copy(&mut self, dst_table: u32, src_table: u32) -> Self::Output {
-        self.instructions.push(Instruction::TableCopy { from: src_table, to: dst_table });
+        self.instructions.push(Instruction::TableCopy { dst_table, src_table });
+    }
+
+    fn visit_memory_copy(&mut self, dst_mem: u32, src_mem: u32) -> Self::Output {
+        self.instructions.push(Instruction::MemoryCopy { dst_mem, src_mem });
     }
 
     // Reference Types

crates/tinywasm/Cargo.toml

@@ -15,6 +15,10 @@ readme="../../README.md"
 name="tinywasm"
 path="src/lib.rs"
 
+[package.metadata.docs.rs]
+features=["std", "parser", "archive", "log", "canonicalize_nans", "debug", "guest_debug"]
+rustdoc-args=["--cfg", "docsrs"]
+
 [dependencies]
 log={workspace=true, optional=true}
 tinywasm-parser={version="0.9.0-alpha.0", path="../parser", default-features=false, optional=true}
@@ -51,6 +55,9 @@ canonicalize_nans=[]
 # derive Debug for runtime/types structs
 debug=["tinywasm-types/debug"]
 
+# expose module-internal by-index inspection APIs
+guest_debug=[]
+
 # enable x86-specific SIMD intrinsics in Value128 (uses unsafe code)
 # note: for x86 backend selection, compile with x86-64-v3 target features
 # (for example: `RUSTFLAGS="-C target-cpu=x86-64-v3"`)

crates/tinywasm/benches/argon2id.rs

@@ -24,19 +24,22 @@ fn argon2id_from_twasm(twasm: &[u8]) -> Result<TinyWasmModule> {
 fn argon2id_run(module: TinyWasmModule) -> Result<()> {
     let mut store = Store::default();
     let instance = ModuleInstance::instantiate(&mut store, module.into(), None)?;
-    let argon2 = instance.exported_func::<(i32, i32, i32), i32>(&store, "argon2id")?;
+    let argon2 = instance.func_typed::<(i32, i32, i32), i32>(&store, "argon2id")?;
     argon2.call(&mut store, (1000, 2, 1))?;
     Ok(())
 }
 
 fn criterion_benchmark(c: &mut Criterion) {
     let module = argon2id_parse().expect("argon2id_parse");
     let twasm = argon2id_to_twasm(&module).expect("argon2id_to_twasm");
-
-    c.bench_function("argon2id_parse", |b| b.iter(argon2id_parse));
-    c.bench_function("argon2id_to_twasm", |b| b.iter(|| argon2id_to_twasm(&module)));
-    c.bench_function("argon2id_from_twasm", |b| b.iter(|| argon2id_from_twasm(&twasm)));
-    c.bench_function("argon2id", |b| b.iter(|| argon2id_run(module.clone())));
+    let mut group = c.benchmark_group("argon2id");
+
+    group.measurement_time(std::time::Duration::from_secs(2));
+    group.bench_function("argon2id_parse", |b| b.iter(argon2id_parse));
+    group.bench_function("argon2id_to_twasm", |b| b.iter(|| argon2id_to_twasm(&module)));
+    group.bench_function("argon2id_from_twasm", |b| b.iter(|| argon2id_from_twasm(&twasm)));
+    group.measurement_time(std::time::Duration::from_secs(10));
+    group.bench_function("argon2id", |b| b.iter(|| argon2id_run(module.clone())));
 }
 
 criterion_group!(benches, criterion_benchmark);

crates/tinywasm/benches/fibonacci.rs

@@ -23,7 +23,7 @@ fn fibonacci_from_twasm(twasm: &[u8]) -> Result<TinyWasmModule> {
 fn fibonacci_run(module: TinyWasmModule, recursive: bool, n: i32) -> Result<()> {
     let mut store = Store::default();
     let instance = ModuleInstance::instantiate(&mut store, module.into(), None)?;
-    let argon2 = instance.exported_func::<i32, i32>(
+    let argon2 = instance.func_typed::<i32, i32>(
         &store,
         match recursive {
             true => "fibonacci_recursive",
@@ -37,12 +37,15 @@ fn fibonacci_run(module: TinyWasmModule, recursive: bool, n: i32) -> Result<()>
 fn criterion_benchmark(c: &mut Criterion) {
     let module = fibonacci_parse().expect("fibonacci_parse");
     let twasm = fibonacci_to_twasm(&module).expect("fibonacci_to_twasm");
-
-    c.bench_function("fibonacci_parse", |b| b.iter(fibonacci_parse));
-    c.bench_function("fibonacci_to_twasm", |b| b.iter(|| fibonacci_to_twasm(&module)));
-    c.bench_function("fibonacci_from_twasm", |b| b.iter(|| fibonacci_from_twasm(&twasm)));
-    c.bench_function("fibonacci_iterative_60", |b| b.iter(|| fibonacci_run(module.clone(), false, 60)));
-    c.bench_function("fibonacci_recursive_26", |b| b.iter(|| fibonacci_run(module.clone(), true, 26)));
+    let mut group = c.benchmark_group("fibonacci");
+
+    group.measurement_time(std::time::Duration::from_secs(2));
+    group.bench_function("fibonacci_parse", |b| b.iter(fibonacci_parse));
+    group.bench_function("fibonacci_to_twasm", |b| b.iter(|| fibonacci_to_twasm(&module)));
+    group.bench_function("fibonacci_from_twasm", |b| b.iter(|| fibonacci_from_twasm(&twasm)));
+    group.measurement_time(std::time::Duration::from_secs(10));
+    group.bench_function("fibonacci_iterative_60", |b| b.iter(|| fibonacci_run(module.clone(), false, 60)));
+    group.bench_function("fibonacci_recursive_26", |b| b.iter(|| fibonacci_run(module.clone(), true, 26)));
 }
 
 criterion_group!(benches, criterion_benchmark);

crates/tinywasm/benches/tinywasm.rs

@@ -26,7 +26,7 @@ fn tinywasm_run(module: TinyWasmModule) -> Result<()> {
     let mut imports = Imports::default();
     imports.define("env", "printi32", Extern::typed_func(|_: FuncContext<'_>, _: i32| Ok(()))).expect("define");
     let instance = ModuleInstance::instantiate(&mut store, module.into(), Some(imports)).expect("instantiate");
-    let hello = instance.exported_func::<(), ()>(&store, "hello").expect("exported_func");
+    let hello = instance.func_typed::<(), ()>(&store, "hello").expect("func_typed");
     hello.call(&mut store, ()).expect("call");
     Ok(())
 }
@@ -35,11 +35,12 @@ fn criterion_benchmark(c: &mut Criterion) {
     let module = tinywasm_parse().expect("tinywasm_parse");
     let twasm = tinywasm_to_twasm(&module).expect("tinywasm_to_twasm");
     let mut group = c.benchmark_group("tinywasm");
-    group.measurement_time(std::time::Duration::from_secs(10));
 
+    group.measurement_time(std::time::Duration::from_secs(2));
     group.bench_function("tinywasm_parse", |b| b.iter(tinywasm_parse));
     group.bench_function("tinywasm_to_twasm", |b| b.iter(|| tinywasm_to_twasm(&module)));
     group.bench_function("tinywasm_from_twasm", |b| b.iter(|| tinywasm_from_twasm(&twasm)));
+    group.measurement_time(std::time::Duration::from_secs(10));
     group.bench_function("tinywasm", |b| b.iter(|| tinywasm_run(module.clone())));
 }
 

crates/tinywasm/benches/tinywasm_modes.rs

@@ -24,7 +24,7 @@ fn setup_typed_func(module: TinyWasmModule, engine: Option<Engine>) -> Result<(S
     imports.define("env", "printi32", Extern::typed_func(|_: FuncContext<'_>, _: i32| Ok(())))?;
 
     let instance = ModuleInstance::instantiate(&mut store, module.into(), Some(imports))?;
-    let func = instance.exported_func::<(), ()>(&store, "hello")?;
+    let func = instance.func_typed::<(), ()>(&store, "hello")?;
     Ok((store, func))
 }
 

crates/tinywasm/src/func.rs

@@ -22,6 +22,7 @@ pub(crate) struct ExecutionState {
 /// A function handle
 #[cfg_attr(feature = "debug", derive(Debug))]
 pub struct FuncHandle {
+    pub(crate) store_id: usize,
     pub(crate) module_addr: ModuleInstanceAddr,
     pub(crate) addr: u32,
     pub(crate) ty: FuncType,
@@ -53,6 +54,10 @@ impl FuncHandle {
     /// See <https://webassembly.github.io/spec/core/exec/modules.html#invocation>
     #[inline]
     pub fn call(&self, store: &mut Store, params: &[WasmValue]) -> Result<Vec<WasmValue>> {
+        if self.store_id != store.id() {
+            return Err(Error::InvalidStore);
+        }
+
         validate_call_params(&self.ty, params)?;
 
         let func_inst = store.state.get_func(self.addr);
@@ -86,6 +91,10 @@ impl FuncHandle {
         store: &'store mut Store,
         params: &[WasmValue],
     ) -> Result<FuncExecution<'store>> {
+        if self.store_id != store.id() {
+            return Err(Error::InvalidStore);
+        }
+
         validate_call_params(&self.ty, params)?;
 
         let func_inst = store.state.get_func(self.addr);

crates/tinywasm/src/imports.rs

@@ -6,7 +6,8 @@ use alloc::vec::Vec;
 use core::fmt::Debug;
 
 use crate::func::{FromWasmValueTuple, IntoWasmValueTuple, ValTypesFromTuple};
-use crate::{LinkingError, MemoryRef, MemoryRefMut, Result, log};
+use crate::instance::{ExternItemRef, ExternItemRefMut};
+use crate::{GlobalRef, GlobalRefMut, LinkingError, MemoryRef, MemoryRefMut, Result, TableRef, TableRefMut, log};
 use tinywasm_types::*;
 
 /// The internal representation of a function
@@ -74,14 +75,54 @@ impl FuncContext<'_> {
         })
     }
 
-    /// Get a reference to an exported memory
-    pub fn exported_memory(&self, name: &str) -> Result<MemoryRef<'_>> {
-        self.module().exported_memory(self.store, name)
+    /// Get a reference to a memory export.
+    pub fn memory(&self, name: &str) -> Result<MemoryRef<'_>> {
+        self.module().memory(self.store, name)
     }
 
-    /// Get a mutable reference to an exported memory
-    pub fn exported_memory_mut(&mut self, name: &str) -> Result<MemoryRefMut<'_>> {
-        self.module().exported_memory_mut(self.store, name)
+    /// Get a mutable reference to a memory export.
+    pub fn memory_mut(&mut self, name: &str) -> Result<MemoryRefMut<'_>> {
+        self.module().memory_mut(self.store, name)
+    }
+
+    /// Get any exported extern value by name.
+    pub fn extern_item(&self, name: &str) -> Result<ExternItemRef<'_>> {
+        self.module().extern_item(self.store, name)
+    }
+
+    /// Get any exported extern value by name with mutable access when applicable.
+    pub fn extern_item_mut(&mut self, name: &str) -> Result<ExternItemRefMut<'_>> {
+        self.module().extern_item_mut(self.store, name)
+    }
+
+    /// Get a reference to a table export.
+    pub fn table(&self, name: &str) -> Result<TableRef<'_>> {
+        self.module().table(self.store, name)
+    }
+
+    /// Get a mutable reference to a table export.
+    pub fn table_mut(&mut self, name: &str) -> Result<TableRefMut<'_>> {
+        self.module().table_mut(self.store, name)
+    }
+
+    /// Get the value of a global export.
+    pub fn global_get(&self, name: &str) -> Result<WasmValue> {
+        self.module().global_get(self.store, name)
+    }
+
+    /// Get a reference to a global export.
+    pub fn global(&self, name: &str) -> Result<GlobalRef<'_>> {
+        self.module().global(self.store, name)
+    }
+
+    /// Get a mutable reference to a global export.
+    pub fn global_mut(&mut self, name: &str) -> Result<GlobalRefMut<'_>> {
+        self.module().global_mut(self.store, name)
+    }
+
+    /// Set the value of a mutable global export.
+    pub fn global_set(&mut self, name: &str, value: WasmValue) -> Result<()> {
+        self.module().global_set(self.store, name, value)
     }
 
     /// Charge additional fuel from the currently running resumable invocation.
@@ -230,8 +271,12 @@ impl From<&Import> for ExternName {
 /// ```rust
 /// # use log;
 /// # fn main() -> tinywasm::Result<()> {
-/// use tinywasm::{Imports, Extern};
+/// use tinywasm::{Extern, Imports, Module, Store};
 /// use tinywasm::types::{ValType, TableType, MemoryType, MemoryArch, WasmValue};
+/// # let wasm = wat::parse_str("(module)").expect("valid wat");
+/// # let module = Module::parse_bytes(&wasm)?;
+/// # let mut store = Store::default();
+/// # let my_other_instance = module.instantiate(&mut store, None)?;
 /// let mut imports = Imports::new();
 ///
 /// // function args can be either a single
@@ -249,18 +294,16 @@ impl From<&Import> for ExternName {
 ///     .define("my_module", "table", Extern::table(table_type, table_init))?
 ///     .define("my_module", "memory", Extern::memory(MemoryType::new(MemoryArch::I32, 1, Some(2), None)))?
 ///     .define("my_module", "global_i32", Extern::global(WasmValue::I32(666), false))?
-///     .link_module("my_other_module", 0)?;
+///     .link_module("my_other_module", my_other_instance)?;
 /// # Ok(())
 /// # }
 /// ```
-///
-/// Note that module instance addresses for [`Imports::link_module`] can be obtained from [`crate::ModuleInstance::id`].
 /// Now, the imports object can be passed to [`crate::ModuleInstance::instantiate`].
 #[derive(Default, Clone)]
 #[cfg_attr(feature = "debug", derive(Debug))]
 pub struct Imports {
     values: BTreeMap<ExternName, Extern>,
-    modules: BTreeMap<String, ModuleInstanceAddr>,
+    modules: BTreeMap<String, crate::ModuleInstance>,
 }
 
 pub(crate) enum ResolvedExtern<S, V> {
@@ -297,8 +340,8 @@ impl Imports {
     /// Link a module
     ///
     /// This will automatically link all imported values on instantiation
-    pub fn link_module(&mut self, name: &str, addr: ModuleInstanceAddr) -> Result<&mut Self> {
-        self.modules.insert(name.to_string(), addr);
+    pub fn link_module(&mut self, name: &str, instance: crate::ModuleInstance) -> Result<&mut Self> {
+        self.modules.insert(name.to_string(), instance);
         Ok(self)
     }
 
@@ -312,17 +355,20 @@ impl Imports {
         &mut self,
         store: &mut crate::Store,
         import: &Import,
-    ) -> Option<ResolvedExtern<ExternVal, Extern>> {
+    ) -> Result<Option<ResolvedExtern<ExternVal, Extern>>> {
         let name = ExternName::from(import);
         if let Some(v) = self.values.get(&name) {
-            return Some(ResolvedExtern::Extern(v.clone()));
+            return Ok(Some(ResolvedExtern::Extern(v.clone())));
         }
-        if let Some(addr) = self.modules.get(&name.module) {
-            let instance = store.get_module_instance(*addr)?;
-            return Some(ResolvedExtern::Store(instance.export_addr(&import.name)?));
+        if let Some(instance) = self.modules.get(&name.module) {
+            if instance.0.store_id != store.id() {
+                return Err(crate::Error::InvalidStore);
+            }
+
+            return Ok(instance.export_addr(&import.name).map(ResolvedExtern::Store));
         }
 
-        None
+        Ok(None)
     }
 
     #[cfg(not(feature = "debug"))]
@@ -392,16 +438,17 @@ impl Imports {
         let mut imports = ResolvedImports::new();
 
         for import in &*module.0.imports {
-            match self.take(store, import).ok_or_else(|| LinkingError::unknown_import(import))? {
+            match self.take(store, import)?.ok_or_else(|| LinkingError::unknown_import(import))? {
                 // A link to something that needs to be added to the store
                 ResolvedExtern::Extern(ex) => match (ex, &import.kind) {
                     (Extern::Global { ty, val }, ImportKind::Global(import_ty)) => {
                         Self::compare_types(import, &ty, import_ty)?;
                         imports.globals.push(store.add_global(ty, val.into(), idx)?);
                     }
-                    (Extern::Table { ty, .. }, ImportKind::Table(import_ty)) => {
+                    (Extern::Table { ty, init }, ImportKind::Table(import_ty)) => {
                         Self::compare_table_types(import, &ty, import_ty)?;
-                        imports.tables.push(store.add_table(ty, idx)?);
+                        Self::compare_types(import, &ty.element_type, &init.val_type())?;
+                        imports.tables.push(store.add_table(ty, init, idx)?);
                     }
                     (Extern::Memory { ty }, ImportKind::Memory(import_ty)) => {
                         Self::compare_memory_types(import, &ty, import_ty, None)?;