refactor: separate interpreter code and execution state

- borrow function code separately from mutable runtime state
- forward the 32-bit lane height through tail handlers
- add an optional preserve-none ABI.
- add parser checkpoints and remove time-budgeted execution

Adapts some of the ideas from #74 and #79

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

Author: explodingcamera

CHANGELOG.md

@@ -13,6 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added new `Memory::data` and `Memory::data_mut` methods for direct access to linear memory.
 - Added several internal methods to support a future c-api crate
 
+### Removed
+
+- Removed `resume_with_time_budget`. Use `resume_with_fuel` and check application deadlines between resumes.
+
 ### Fixed
 
 - Restore store state after a panic in a function call, allowing subsequent calls and preventing invalid resumption.

README.md

@@ -59,6 +59,7 @@ See the [examples](./examples) directory and [documentation](https://docs.rs/tin
 - **`debug`:** Derives `Debug` for runtime types. Enabled by default.
 - **`guest-debug`:** Exposes module-internal by-index inspection APIs (`*_by_index`).
 - **`nightly-tail-calls`:** Uses Rust's unstable explicit tail calls for interpreter dispatch. Requires nightly Rust (recommended for maximum performance).
+- **`nightly-rust-preserve-none`:** Uses Rust's experimental preserve-none ABI for x86_64 and 64-bit AArch64 tail-call handlers. Requires nightly Rust (recommended for maximum performance).
 - **`simd-x86`:** Enables x86-specific SIMD intrinsics and uses `unsafe` internally.
 
 With default features disabled, `tinywasm` supports `no_std + alloc` and depends only on `libm`.
@@ -75,7 +76,9 @@ Applications that only load `.twasm` can remove the parser and validator from th
 
 WebAssembly [validation](https://webassembly.github.io/spec/core/valid/index.html) is enabled by default through the `validate` feature. Keep this feature enabled and leave `ParserOptions::validation` enabled for modules from untrusted sources. Without validation, parsing can produce modules that violate runtime assumptions and may panic during instantiation or execution.
 
-Validation does not limit parsing or execution resources. Hosts that run untrusted code should also configure `parser::ParseLimits`, stack and `ResourceLimiter` limits, and fuel- or time-budgeted execution as needed.
+Validation does not limit parsing or execution resources. Hosts that run untrusted code should also configure `parser::ParseLimits`, stack and `ResourceLimiter` limits, and fuel-budgeted execution as needed. The default fuel policy counts interpreter steps. Applications can check their own deadlines between calls to `resume_with_fuel`.
+
+Use `parser::ParserOptions::new().with_checkpoint_interval(4096)` to tune straight-line budget-check spacing before parsing. The default is 1,024 emitted interpreter instructions, with up to three extra for pending fusion. Larger intervals trade responsiveness for lower checkpoint overhead. Taken loop backedges are checked independently, and synthetic checkpoints consume no fuel.
 
 Loading `.twasm` checks the archive header and encoding but does not run WebAssembly validation or verify TinyWasm's runtime invariants. Load archives only from trusted sources. For untrusted input, parse a WebAssembly binary with validation enabled.
 

crates/cli/src/wast_runner.rs

@@ -3,7 +3,6 @@ use std::fmt::{Display, Formatter};
 use std::fs::canonicalize;
 use std::panic::{self, AssertUnwindSafe};
 use std::path::PathBuf;
-use std::time::Duration;
 
 use anyhow::{Context, Result, anyhow, bail};
 use log::{debug, error};
@@ -14,7 +13,7 @@ use tinywasm::{
 use wast::QuoteWat;
 use wast::core::{AbstractHeapType, NanPattern};
 
-const TEST_TIME_SLICE: Duration = Duration::from_millis(20);
+const TEST_FUEL_SLICE: u32 = 64 * 1024;
 const TEST_MAX_SUSPENSIONS: u32 = 1000;
 // Older suites classify encodings that wasmparser accepts with the latest feature set as malformed.
 const ACCEPTED_MALFORMED_MESSAGES: &[&str] =
@@ -733,13 +732,13 @@ fn exec_with_budget(
 ) -> Result<(), tinywasm::Error> {
     let mut exec = func.call_resumable(store, args, results)?;
     for _ in 0..TEST_MAX_SUSPENSIONS {
-        if let ExecProgress::Completed(()) = exec.resume_with_time_budget(TEST_TIME_SLICE)? {
+        if let ExecProgress::Completed(()) = exec.resume_with_fuel(TEST_FUEL_SLICE)? {
             return Ok(());
         }
     }
     Err(tinywasm::Error::Other(format!(
-        "testsuite execution timed out after {} time slices of {:?}",
-        TEST_MAX_SUSPENSIONS, TEST_TIME_SLICE
+        "testsuite execution exhausted {} fuel slices of {} units",
+        TEST_MAX_SUSPENSIONS, TEST_FUEL_SLICE
     )))
 }
 

crates/parser/src/emitter.rs

@@ -57,6 +57,8 @@ enum PatchSite {
 pub(crate) struct Emitter {
     instructions: Vec<Instruction>,
     committed: usize,
+    checkpoint_start: usize,
+    checkpoint_interval: usize,
     select: bool,
     self_func_addr: u32,
     return_instruction: Instruction,
@@ -79,6 +81,8 @@ impl Emitter {
         Self {
             instructions: Vec::with_capacity(body_size.min(1024)),
             committed: 0,
+            checkpoint_start: 0,
+            checkpoint_interval: options.checkpoint_interval(),
             select: options.optimize(),
             self_func_addr: context.self_func_addr,
             return_instruction,
@@ -146,9 +150,19 @@ impl Emitter {
 
     fn push(&mut self, instruction: Instruction) -> Result<()> {
         self.seal_jump();
-        if self.instructions.len() >= u32::MAX as usize {
+        let checkpoint = self.committed - self.checkpoint_start >= self.checkpoint_interval;
+        let added = 1 + usize::from(checkpoint);
+        if self.instructions.len().checked_add(added).is_none_or(|len| len > u32::MAX as usize) {
             return Err(ParseError::Other("function body is too large".into()));
         }
+        if checkpoint {
+            // Seal the pending fusion window instead of inserting into the committed prefix.
+            // This permits at most LOOKBEHIND extra guest instructions per interval. Labels bound
+            // at this boundary target the checkpoint, and exclusive exception ends exclude it.
+            self.instructions.push(Instruction::Checkpoint);
+            self.commit(self.instructions.len());
+            self.checkpoint_start = self.instructions.len();
+        }
         self.instructions.push(instruction);
         Ok(())
     }

crates/parser/src/lib.rs

@@ -71,6 +71,13 @@ pub struct ParserOptions {
     /// Whether to deduplicate immutable function operands while parsing.
     pub deduplicate_operands: bool,
 
+    /// Target number of emitted guest instructions between synthetic execution checkpoints.
+    ///
+    /// Defaults to 1,024. The pending fusion window can add up to three instructions per interval.
+    /// Larger intervals reduce checkpoint overhead but allow longer straight-line execution before
+    /// a resumable invocation checks its budget. Taken control-flow boundaries are checked separately.
+    pub checkpoint_interval: core::num::NonZeroUsize,
+
     /// Optional limits for parsing untrusted modules. Unlimited by default.
     pub limits: ParseLimits,
 
@@ -91,6 +98,7 @@ impl Default for ParserOptions {
             validation: cfg!(feature = "validate"),
             optimize: true,
             deduplicate_operands: true,
+            checkpoint_interval: core::num::NonZeroUsize::new(1024).unwrap(),
             limits: ParseLimits::default(),
             #[cfg(parallel_parser)]
             threads: None,
@@ -143,6 +151,23 @@ impl ParserOptions {
         self.deduplicate_operands
     }
 
+    /// Sets the target number of emitted guest instructions between execution checkpoints.
+    ///
+    /// This also applies when optimizations are disabled. Synthetic checkpoints consume no guest
+    /// fuel. This bounds interpreter work, not time spent in bulk operations or host callbacks.
+    ///
+    /// # Panics
+    /// Panics if `interval` is zero.
+    pub const fn with_checkpoint_interval(mut self, interval: usize) -> Self {
+        self.checkpoint_interval = core::num::NonZeroUsize::new(interval).expect("checkpoint interval must be nonzero");
+        self
+    }
+
+    /// Returns the target execution checkpoint interval in emitted guest instructions.
+    pub const fn checkpoint_interval(&self) -> usize {
+        self.checkpoint_interval.get()
+    }
+
     /// Set parse-time limits.
     pub const fn with_limits(mut self, limits: ParseLimits) -> Self {
         self.limits = limits;

crates/tinywasm/Cargo.toml

@@ -132,6 +132,9 @@ guest-debug = []
 # use explicit tail calls for interpreter dispatch (requires nightly Rust)
 nightly-tail-calls = []
 
+# use the experimental preserve-none ABI for x86_64 and 64-bit AArch64 tail-call handlers
+nightly-rust-preserve-none = ["nightly-tail-calls"]
+
 # 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/build.rs

@@ -0,0 +1,36 @@
+use std::env;
+
+fn main() {
+    println!("cargo::rerun-if-changed=build.rs");
+    println!(
+        "cargo::rustc-check-cfg=cfg(tail_abi, values(\"Rust\", \"C-unwind\", \"sysv64-unwind\", \"rust-preserve-none\"))"
+    );
+    println!("cargo::rustc-check-cfg=cfg(simd_backend, values(\"generic\", \"wasm\", \"x86\"))");
+
+    let arch = env::var("CARGO_CFG_TARGET_ARCH").expect("Cargo target architecture");
+    let features = env::var("CARGO_CFG_TARGET_FEATURE").unwrap_or_default();
+    let x86_v3 = ["sse4.2", "avx", "avx2", "bmi1", "bmi2", "fma", "lzcnt", "movbe", "popcnt"]
+        .iter()
+        .all(|required| features.split(',').any(|enabled| enabled == *required));
+    let simd = match arch.as_str() {
+        "wasm32" | "wasm64" => "wasm",
+        "x86_64" if env::var_os("CARGO_FEATURE_SIMD_X86").is_some() && x86_v3 => "x86",
+        _ => "generic",
+    };
+    println!("cargo::rustc-cfg=simd_backend={simd:?}");
+
+    if env::var_os("CARGO_FEATURE_NIGHTLY_TAIL_CALLS").is_none() {
+        return;
+    }
+
+    let width = env::var("CARGO_CFG_TARGET_POINTER_WIDTH").expect("Cargo target pointer width");
+    let os = env::var("CARGO_CFG_TARGET_OS").expect("Cargo target OS");
+    let preserve_none = env::var_os("CARGO_FEATURE_NIGHTLY_RUST_PRESERVE_NONE").is_some();
+    let abi = match (arch.as_str(), width.as_str(), os.as_str(), preserve_none) {
+        ("aarch64", "32", _, _) => "C-unwind",
+        ("x86_64", _, _, true) | ("aarch64", "64", _, true) => "rust-preserve-none",
+        ("x86_64", _, "windows", _) => "sysv64-unwind",
+        _ => "Rust",
+    };
+    println!("cargo::rustc-cfg=tail_abi={abi:?}");
+}

crates/tinywasm/src/store/gc/arena.rs crates/tinywasm/src/collections/arena.rscrates/tinywasm/src/store/gc/arena.rs renamed to crates/tinywasm/src/collections/arena.rs

@@ -1,4 +1,4 @@
-//! Mark-and-sweep storage with stable handles for WebAssembly GC objects.
+//! Mark-and-sweep storage with stable generational handles.
 
 use alloc::vec::Vec;
 use core::cell::Cell;
@@ -63,7 +63,8 @@ pub(crate) struct Arena<T> {
     free_head: Option<u32>,
     worklist: Vec<u32>,
     len: usize,
-    pub(super) allocated_bytes: usize,
+    /// Bytes retained by live objects, including their slot storage.
+    pub(crate) allocated_bytes: usize,
     collection_threshold: usize,
     next_collection: usize,
 }
@@ -161,7 +162,8 @@ impl<T> Arena<T> {
             .is_none_or(|bytes| bytes >= self.next_collection)
     }
 
-    pub(super) fn allocation_size(out_of_line_bytes: usize) -> Option<usize> {
+    /// Returns the retained bytes for one slot and its separately allocated storage.
+    pub(crate) fn allocation_size(out_of_line_bytes: usize) -> Option<usize> {
         size_of::<Slot<T>>().checked_add(out_of_line_bytes)
     }
 }

crates/tinywasm/src/collections/mod.rs

@@ -0,0 +1,7 @@
+//! Internal storage collections used by stacks and the managed heap.
+
+mod arena;
+mod stack;
+
+pub(crate) use arena::{AllocError, Arena, Handle, Trace};
+pub(crate) use stack::StackLane;