chore: refactor executor and improve documentation

Signed-off-by: Henry Gressmann <[email protected]>

Author: explodingcamera

.github/workflows/test.yaml

@@ -38,7 +38,7 @@ jobs:
           submodules: true
 
       - name: Install nightly Rust toolchain
-        run: rustup update stable nightly
+        run: rustup update nightly
 
       - name: Build (nightly, no default features)
         run: cargo +nightly build --workspace --exclude wasm-testsuite --no-default-features

crates/parser/src/error.rs

@@ -4,6 +4,7 @@ use alloc::string::{String, ToString};
 use wasmparser::Encoding;
 
 #[derive(Debug)]
+/// Errors that can occur when parsing a WebAssembly module
 pub enum ParseError {
     InvalidType,
     UnsupportedSection(String),

crates/tinywasm/src/error.rs

@@ -3,31 +3,31 @@ use core::fmt::Display;
 use tinywasm_types::FuncType;
 
 #[cfg(feature = "parser")]
-use tinywasm_parser::ParseError;
+pub use tinywasm_parser::ParseError;
 
-/// A tinywasm error
+/// Errors that can occur for TinyWasm operations
 #[derive(Debug)]
 pub enum Error {
-    #[cfg(feature = "parser")]
-    /// A parsing error occurred
-    ParseError(ParseError),
-
     #[cfg(feature = "std")]
     /// An I/O error occurred
     Io(crate::std::io::Error),
 
-    /// A WebAssembly feature is not supported
-    UnsupportedFeature(String),
-
-    /// An unknown error occurred
-    Other(String),
+    #[cfg(feature = "parser")]
+    /// A parsing error occurred
+    ParseError(ParseError),
 
     /// A WebAssembly trap occurred
     Trap(Trap),
 
     /// A linking error occurred
     Linker(LinkingError),
 
+    /// A WebAssembly feature is not supported
+    UnsupportedFeature(String),
+
+    /// An unknown error occurred
+    Other(String),
+
     /// A function did not return a value
     FuncDidNotReturn,
 
@@ -48,7 +48,7 @@ pub enum Error {
 }
 
 #[derive(Debug)]
-/// A linking error
+/// Errors that can occur when linking a WebAssembly module
 pub enum LinkingError {
     /// An unknown import was encountered
     UnknownImport {
@@ -210,5 +210,5 @@ impl From<tinywasm_parser::ParseError> for Error {
     }
 }
 
-/// A specialized [`Result`] type for tinywasm operations
+/// A wrapper around [`core::result::Result`] for tinywasm operations
 pub type Result<T, E = Error> = crate::std::result::Result<T, E>;

crates/tinywasm/src/func.rs

@@ -89,7 +89,7 @@ impl FuncHandle {
 
 #[derive(Debug)]
 /// A typed function handle
-pub struct TypedFuncHandle<P, R> {
+pub struct FuncHandleTyped<P, R> {
     /// The underlying function handle
     pub func: FuncHandle,
     pub(crate) marker: core::marker::PhantomData<(P, R)>,
@@ -105,7 +105,7 @@ pub trait FromWasmValueTuple {
         Self: Sized;
 }
 
-impl<P: IntoWasmValueTuple, R: FromWasmValueTuple> TypedFuncHandle<P, R> {
+impl<P: IntoWasmValueTuple, R: FromWasmValueTuple> FuncHandleTyped<P, R> {
     /// Call a typed function
     pub fn call(&self, store: &mut Store, params: P) -> Result<R> {
         // Convert params into Vec<WasmValue>

crates/tinywasm/src/imports.rs

@@ -90,56 +90,45 @@ impl Debug for HostFunction {
 /// An external value
 pub enum Extern {
     /// A global value
-    Global(ExternGlobal),
+    Global {
+        /// The type of the global value.
+        ty: GlobalType,
+        /// The actual value of the global, encapsulated in `WasmValue`.
+        val: WasmValue,
+    },
 
     /// A table
-    Table(ExternTable),
+    Table {
+        /// Defines the type of the table, including its element type and limits.
+        ty: TableType,
+        /// The initial value of the table.
+        init: WasmValue,
+    },
 
     /// A memory
-    Memory(ExternMemory),
+    Memory {
+        /// Defines the type of the memory, including its limits and the type of its pages.
+        ty: MemoryType,
+    },
 
     /// A function
     Function(Function),
 }
 
-/// A function
-#[derive(Debug, Clone)]
-pub struct ExternFunc(pub(crate) HostFunction);
-
-/// A global value
-#[derive(Debug, Clone)]
-pub struct ExternGlobal {
-    pub(crate) ty: GlobalType,
-    pub(crate) val: WasmValue,
-}
-
-/// A table
-#[derive(Debug, Clone)]
-pub struct ExternTable {
-    pub(crate) ty: TableType,
-    pub(crate) val: WasmValue,
-}
-
-/// A memory
-#[derive(Debug, Clone)]
-pub struct ExternMemory {
-    pub(crate) ty: MemoryType,
-}
-
 impl Extern {
     /// Create a new global import
     pub fn global(val: WasmValue, mutable: bool) -> Self {
-        Self::Global(ExternGlobal { ty: GlobalType { ty: val.val_type(), mutable }, val })
+        Self::Global { ty: GlobalType { ty: val.val_type(), mutable }, val }
     }
 
     /// Create a new table import
-    pub fn table(ty: TableType, val: WasmValue) -> Self {
-        Self::Table(ExternTable { ty, val })
+    pub fn table(ty: TableType, init: WasmValue) -> Self {
+        Self::Table { ty, init }
     }
 
     /// Create a new memory import
     pub fn memory(ty: MemoryType) -> Self {
-        Self::Memory(ExternMemory { ty })
+        Self::Memory { ty }
     }
 
     /// Create a new function import
@@ -174,10 +163,10 @@ impl Extern {
 
     pub(crate) fn kind(&self) -> ExternalKind {
         match self {
-            Self::Global(_) => ExternalKind::Global,
-            Self::Table(_) => ExternalKind::Table,
-            Self::Memory(_) => ExternalKind::Memory,
-            Self::Function(_) => ExternalKind::Func,
+            Self::Global { .. } => ExternalKind::Global,
+            Self::Table { .. } => ExternalKind::Table,
+            Self::Memory { .. } => ExternalKind::Memory,
+            Self::Function { .. } => ExternalKind::Func,
         }
     }
 }
@@ -197,6 +186,38 @@ impl From<&Import> for ExternName {
 
 #[derive(Debug, Default)]
 /// Imports for a module instance
+///
+/// This is used to link a module instance to its imports
+///
+/// ## Example
+/// ```rust
+/// # fn main() -> tinywasm::Result<()> {
+/// use tinywasm::{Imports, Extern};
+/// use tinywasm::types::{ValType, TableType, MemoryType, WasmValue};
+/// let mut imports = Imports::new();
+///
+/// // function args can be either a single
+/// // value that implements `TryFrom<WasmValue>` or a tuple of them
+/// let print_i32 = Extern::typed_func(|_ctx: tinywasm::FuncContext<'_>, arg: i32| {
+///     log::debug!("print_i32: {}", arg);
+///     Ok(())
+/// });
+///
+/// let table_type = TableType::new(ValType::RefFunc, 10, Some(20));
+/// let table_init = WasmValue::default_for(ValType::RefFunc);
+///
+/// imports
+///     .define("my_module", "print_i32", print_i32)?
+///     .define("my_module", "table", Extern::table(table_type, table_init))?
+///     .define("my_module", "memory", Extern::memory(MemoryType::new_32(1, Some(2))))?
+///     .define("my_module", "global_i32", Extern::global(WasmValue::I32(666), false))?
+///     .link_module("my_other_module", 0)?;
+/// # 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`].
 pub struct Imports {
     values: BTreeMap<ExternName, Extern>,
     modules: BTreeMap<String, ModuleInstanceAddr>,
@@ -334,17 +355,17 @@ impl Imports {
             match val {
                 // A link to something that needs to be added to the store
                 ResolvedExtern::Extern(ex) => match (ex, &import.kind) {
-                    (Extern::Global(extern_global), ImportKind::Global(ty)) => {
-                        Self::compare_types(import, &extern_global.ty, ty)?;
-                        imports.globals.push(store.add_global(extern_global.ty, extern_global.val.into(), idx)?);
+                    (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(extern_table), ImportKind::Table(ty)) => {
-                        Self::compare_table_types(import, &extern_table.ty, ty)?;
-                        imports.tables.push(store.add_table(extern_table.ty, idx)?);
+                    (Extern::Table { ty, .. }, ImportKind::Table(import_ty)) => {
+                        Self::compare_table_types(import, &ty, import_ty)?;
+                        imports.tables.push(store.add_table(ty, idx)?);
                     }
-                    (Extern::Memory(extern_memory), ImportKind::Memory(ty)) => {
-                        Self::compare_memory_types(import, &extern_memory.ty, ty, None)?;
-                        imports.memories.push(store.add_mem(extern_memory.ty, idx)?);
+                    (Extern::Memory { ty }, ImportKind::Memory(import_ty)) => {
+                        Self::compare_memory_types(import, &ty, import_ty, None)?;
+                        imports.memories.push(store.add_mem(ty, idx)?);
                     }
                     (Extern::Function(extern_func), ImportKind::Function(ty)) => {
                         let import_func_type = module

crates/tinywasm/src/instance.rs

@@ -6,10 +6,10 @@ use tinywasm_types::{
 
 use crate::{
     func::{FromWasmValueTuple, IntoWasmValueTuple},
-    Error, FuncHandle, Imports, Module, Result, Store, TypedFuncHandle,
+    Error, FuncHandle, FuncHandleTyped, Imports, Module, Result, Store,
 };
 
-/// A WebAssembly Module Instance
+/// An instanciated WebAssembly module
 ///
 /// Backed by an Arc, so cloning is cheap
 ///
@@ -178,13 +178,13 @@ impl ModuleInstance {
     }
 
     /// Get a typed exported function by name
-    pub fn typed_func<P, R>(&self, store: &Store, name: &str) -> Result<TypedFuncHandle<P, R>>
+    pub fn typed_func<P, R>(&self, store: &Store, name: &str) -> Result<FuncHandleTyped<P, R>>
     where
         P: IntoWasmValueTuple,
         R: FromWasmValueTuple,
     {
         let func = self.exported_func_by_name(store, name)?;
-        Ok(TypedFuncHandle { func, marker: core::marker::PhantomData })
+        Ok(FuncHandleTyped { func, marker: core::marker::PhantomData })
     }
 
     /// Get the start function of the module

crates/tinywasm/src/lib.rs

@@ -14,12 +14,23 @@
 //! to be useful for embedded systems and other environments where a full-featured
 //! runtime is not required.
 //!
-//! ## Getting Started
+//! ## Features
+//! - `std` (default): Enables the use of `std` and `std::io` for parsing from files and streams.
+//! - `logging` (default): Enables logging via the `log` crate.
+//! - `parser` (default): Enables the `tinywasm_parser` crate for parsing WebAssembly modules.
+//!
+//! ## No-std support
+//! TinyWasm supports `no_std` environments by disabling the `std` feature and registering
+//! a custom allocator. This removes support for parsing from files and streams,
+//! but otherwise the API is the same.
+//! Additionally, to have proper error types, you currently need a `nightly` compiler to have the error trait in core.
 //!
+//! ## Getting Started
 //! The easiest way to get started is to use the [`Module::parse_bytes`] function to load a
 //! WebAssembly module from bytes. This will parse the module and validate it, returning
 //! a [`Module`] that can be used to instantiate the module.
 //!
+//!
 //! ```rust
 //! use tinywasm::{Store, Module};
 //!
@@ -39,25 +50,21 @@
 //!
 //! // Get a typed handle to the exported "add" function
 //! // Alternatively, you can use `instance.get_func` to get an untyped handle
-//! // that takes and returns WasmValue types
-//! let func = instance.typed_func::<(i32, i32), (i32,)>(&mut store, "add")?;
+//! // that takes and returns [`WasmValue`]s
+//! let func = instance.typed_func::<(i32, i32), i32>(&mut store, "add")?;
 //! let res = func.call(&mut store, (1, 2))?;
 //!
-//! assert_eq!(res, (3,));
+//! assert_eq!(res, 3);
 //! # Ok::<(), tinywasm::Error>(())
 //! ```
 //!
-//! ## Features
-//! - `std` (default): Enables the use of `std` and `std::io` for parsing from files and streams.
-//! - `logging` (default): Enables logging via the `log` crate.
-//! - `parser` (default): Enables the `tinywasm_parser` crate for parsing WebAssembly modules.
+//! ## Custom Imports
 //!
-//! ## No-std support
-//! TinyWasm supports `no_std` environments by disabling the `std` feature and registering
-//! a custom allocator. This removes support for parsing from files and streams,
-//! but otherwise the API is the same.
+//! To provide custom imports to a module, you can use the [`Imports`] struct.
+//! This struct allows you to register custom functions, globals, memories, tables,
+//! and other modules to be linked into the module when it is instantiated.
 //!
-//! Additionally, if you want proper error types, you must use a `nightly` compiler to have the error trait in core.
+//! See the [`Imports`] documentation for more information.
 
 mod std;
 extern crate alloc;
@@ -87,13 +94,14 @@ mod instance;
 pub use instance::ModuleInstance;
 
 mod func;
-pub use func::{FuncHandle, TypedFuncHandle};
+pub use func::{FuncHandle, FuncHandleTyped};
 
 mod imports;
 pub use imports::*;
 
-mod runtime;
-pub use runtime::*;
+/// Runtime for executing WebAssembly modules.
+pub mod runtime;
+pub use runtime::InterpreterRuntime;
 
 #[cfg(feature = "parser")]
 /// Re-export of [`tinywasm_parser`]. Requires `parser` feature.