chore: improve ResourceLimiter

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

Author: explodingcamera

CHANGELOG.md

@@ -48,6 +48,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changed `TableType::element_type` and `Element::ty` from `WasmType` to `RefType`, and replaced module `table_types` with `TableDefinition { ty, init }`.
 - Removed the pluggable memory backend system (`LinearMemory`, `MemoryBackend`, `VecMemory`, `PagedMemory`, `LazyLinearMemory`, and `Config::with_memory_backend`). Linear memory is always `Vec`-backed. To limit initial memory allocation and growth, configure a `ResourceLimiter` with `Config::with_resource_limiter`.
 - Removed the local-memory allocation analysis (`LocalMemoryAllocation` and `ParserOptions::optimize_local_memory_allocation`). Local memories are always allocated eagerly.
+- Removed `Config::with_trap_on_oom`. A `ResourceLimiter` can return a trap when rejecting a memory allocation or growth request.
 
 ## [0.10.0] - 2026-07-24
 

README.md

@@ -61,7 +61,7 @@ TinyWasm modules can be compiled to the internal `twasm` bytecode format, which
 
 With default features disabled, `tinywasm` depends only on `core`, `alloc`, and `libm`[^libm], making it usable in `no_std + alloc` environments.
 
-Use `Engine` and `engine::Config` when you need non-default runtime settings such as fuel accounting, stack sizing, the GC collection threshold, or trap-on-OOM behavior. A `ResourceLimiter` attached to the engine's config bounds guest memory allocation and growth.
+Use `Engine` and `engine::Config` when you need non-default runtime settings such as fuel accounting, stack sizing, or the GC collection threshold. A `ResourceLimiter` attached to the engine's config bounds guest memory allocation and growth and can trap rejected requests.
 
 [^libm]: [rust-lang/rust#137578](https://github.com/rust-lang/rust/issues/137578) — tracking issue for floating-point math support in `no_std`.
 

crates/cli/src/engine_flags.rs

@@ -8,10 +8,6 @@ pub struct EngineFlags {
     #[arg(long, value_enum)]
     pub fuel_policy: Option<FuelPolicyArg>,
 
-    /// Trap immediately on memory or stack allocation failure
-    #[arg(long)]
-    pub trap_on_oom: bool,
-
     /// Fixed value stack size for all value lanes
     #[arg(long, conflicts_with = "value_stack_dynamic")]
     pub value_stack_size: Option<usize>,
@@ -88,10 +84,6 @@ impl EngineFlags {
             config = config.with_call_stack(call_stack_dynamic.into_stack_config());
         }
 
-        if self.trap_on_oom {
-            config = config.with_trap_on_oom(true);
-        }
-
         Ok(Engine::new(config))
     }
 }

crates/tinywasm/src/engine.rs

@@ -96,8 +96,7 @@ impl StackConfig {
 ///     .with_value_stack_32(StackConfig::dynamic(1024, 36 * 1024))
 ///     .with_value_stack_64(StackConfig::dynamic(1024, 32 * 1024))
 ///     .with_value_stack_128(StackConfig::dynamic(256, 4 * 1024))
-///     .with_call_stack(StackConfig::dynamic(64, 1024))
-///     .with_trap_on_oom(true);
+///     .with_call_stack(StackConfig::dynamic(64, 1024));
 ///
 /// assert!(matches!(config.fuel_policy(), FuelPolicy::Weighted));
 /// ```
@@ -117,9 +116,6 @@ pub struct Config {
     pub call_stack: StackConfig,
     /// Fuel accounting policy used by budgeted execution. Defaults to [`FuelPolicy::PerInstruction`].
     pub fuel_policy: FuelPolicy,
-    /// Whether memory and stack allocation failures should trap instead of degrading into normal operation failure modes.
-    /// Defaults to `false`.
-    pub trap_on_oom: bool,
     /// Resource limiter shared across all stores created from this engine. Defaults to `None`.
     pub resource_limiter: Option<Arc<dyn ResourceLimiter>>,
     /// Initial number of GC heap bytes that triggers collection.
@@ -171,12 +167,6 @@ impl Config {
         self
     }
 
-    /// Configure whether memory and stack allocation failures trap immediately.
-    pub fn with_trap_on_oom(mut self, trap_on_oom: bool) -> Self {
-        self.trap_on_oom = trap_on_oom;
-        self
-    }
-
     /// Set the resource limiter shared across all stores created from this engine.
     pub fn with_resource_limiter(mut self, limiter: Arc<dyn ResourceLimiter>) -> Self {
         self.resource_limiter = Some(limiter);
@@ -193,10 +183,6 @@ impl Config {
     pub fn fuel_policy(&self) -> FuelPolicy {
         self.fuel_policy
     }
-
-    pub(crate) const fn trap_on_oom(&self) -> bool {
-        self.trap_on_oom
-    }
 }
 
 impl Default for Config {
@@ -207,7 +193,6 @@ impl Default for Config {
             value_stack_128: StackConfig::fixed(DEFAULT_VALUE_STACK_128_SIZE),
             call_stack: StackConfig::fixed(DEFAULT_MAX_CALL_STACK_SIZE),
             fuel_policy: FuelPolicy::default(),
-            trap_on_oom: false,
             resource_limiter: None,
             gc_collection_threshold: 1024 * 1024,
         }
@@ -223,7 +208,6 @@ impl core::fmt::Debug for Config {
             .field("value_stack_128", &self.value_stack_128)
             .field("call_stack", &self.call_stack)
             .field("fuel_policy", &self.fuel_policy)
-            .field("trap_on_oom", &self.trap_on_oom)
             .field("resource_limiter", &self.resource_limiter.is_some())
             .field("gc_collection_threshold", &self.gc_collection_threshold)
             .finish()

crates/tinywasm/src/interpreter/executor.rs

@@ -1656,11 +1656,10 @@ impl<'store, const BUDGETED: bool> Executor<'store, BUDGETED> {
             true => <i64>::stack_pop(&mut self.store.value_stack),
             false => i64::from(<i32>::stack_pop(&mut self.store.value_stack)),
         };
-        let trap_on_oom = self.store.engine.config().trap_on_oom();
         let limiter = self.store.engine.config().resource_limiter.as_deref();
 
         let mem = self.store.state.get_mem_mut(mem_addr);
-        let size = mem.grow(pages_delta, trap_on_oom, limiter)?.unwrap_or(-1);
+        let size = mem.grow(pages_delta, limiter)?.unwrap_or(-1);
         match is_64bit {
             true => self.store.value_stack.push::<i64>(size)?,
             false => self.store.value_stack.push::<i32>(size as i32)?,

crates/tinywasm/src/lib.rs

@@ -54,9 +54,9 @@
 //! ```
 //!
 //! For non-default runtime behavior, construct a [`Store`] with a custom [`Engine`]
-//! and [`engine::Config`] to control stack sizing, fuel accounting, and trap-on-OOM
-//! behavior. A [`ResourceLimiter`] can be attached to the engine configuration to bound memory
-//! allocation and growth for stores created from that engine.
+//! and [`engine::Config`] to control stack sizing and fuel accounting. A [`ResourceLimiter`] can be
+//! attached to the engine configuration to bound memory allocation and growth for stores created
+//! from that engine and to trap rejected requests.
 //!
 //! For more examples, see the [`examples`](https://github.com/explodingcamera/tinywasm/tree/main/examples) directory.
 //!

crates/tinywasm/src/reference.rs

@@ -263,11 +263,14 @@ impl Memory {
         })
     }
 
-    /// Grow the memory by the given number of pages.
+    /// Grows the memory by the given number of pages.
+    ///
+    /// Returns the previous size, or `None` if growth fails or is rejected by the resource limiter.
+    /// A limiter-provided trap is returned as an error.
     pub fn grow(&self, store: &mut Store, delta_pages: i64) -> Result<Option<i64>> {
         let limiter = store.engine.config().resource_limiter.clone();
         let mem = self.instance_mut(store)?;
-        mem.grow(delta_pages, true, limiter.as_deref()).map_err(Into::into)
+        mem.grow(delta_pages, limiter.as_deref()).map_err(Into::into)
     }
 
     /// Get the current size of the memory in pages.

crates/tinywasm/src/store/memory/instance.rs

@@ -68,7 +68,7 @@ impl MemoryInstance {
 
         if initial_len != 0
             && let Some(limiter) = limiter
-            && !cold_err!(limiter.memory_growing(0, initial_len, Self::maximum_size(kind)))?
+            && !limiter.memory_growing(0, initial_len, Self::maximum_size(kind))?
         {
             return cold!(Err(Trap::OutOfMemory.into()));
         }
@@ -101,7 +101,6 @@ impl MemoryInstance {
     pub(crate) fn grow(
         &mut self,
         pages_delta: i64,
-        trap_on_oom: bool,
         limiter: Option<&dyn ResourceLimiter>,
     ) -> Result<Option<i64>, Trap> {
         let current_pages = self.page_count;
@@ -126,15 +125,12 @@ impl MemoryInstance {
         }
 
         if let Some(limiter) = limiter
-            && !cold_err!(limiter.memory_growing(self.inner.len(), new_size, Self::maximum_size(self.kind)))?
+            && !limiter.memory_growing(self.inner.len(), new_size, Self::maximum_size(self.kind))?
         {
             return cold!(Ok(None));
         }
 
-        if let Err(err) = cold_err!(self.inner.grow_to(new_size)) {
-            if trap_on_oom {
-                return Err(err);
-            }
+        if cold_err!(self.inner.grow_to(new_size)).is_err() {
             return Ok(None);
         }
         self.page_count = new_pages;

crates/tinywasm/src/store/mod.rs

@@ -31,32 +31,54 @@ pub(crate) use {data::*, element::*, exception::*, function::*, global::*, table
 // global store id counter
 static STORE_ID: AtomicU32 = AtomicU32::new(0);
 
-/// Limits resource consumption within a [`Store`].
+/// Controls resource usage by WebAssembly instances.
 ///
-/// The limiter is consulted before a memory is created or grown, so a host can bound how much a
-/// guest may consume. This mirrors the shape of Wasmtime's `ResourceLimiter`; additional resource
-/// types can be added as the need arises.
+/// Configure a limiter with
+/// [`Config::with_resource_limiter`](crate::engine::Config::with_resource_limiter). It currently
+/// controls guest linear-memory allocation and growth. It does not account for stacks, GC storage,
+/// runtime metadata, or other host allocations.
 ///
-/// A limiter is shared across the stores created from one [`Engine`], so implementations must be
-/// `Send + Sync` and use interior mutability to track state.
+/// # Example
+/// ```rust
+/// use std::sync::Arc;
+/// use tinywasm::engine::Config;
+/// use tinywasm::types::{MemoryArch, MemoryType};
+/// use tinywasm::{Engine, Memory, ResourceLimiter, Store};
+///
+/// struct MemoryLimit(usize);
+///
+/// impl ResourceLimiter for MemoryLimit {
+///     fn memory_growing(
+///         &self,
+///         _current: usize,
+///         desired: usize,
+///         _maximum: Option<usize>,
+///     ) -> Result<bool, tinywasm::Trap> {
+///         Ok(desired <= self.0)
+///     }
+/// }
+///
+/// let config = Config::new().with_resource_limiter(Arc::new(MemoryLimit(64 * 1024)));
+/// let mut store = Store::new(Engine::new(config));
+/// let memory = Memory::new(&mut store, MemoryType::new(MemoryArch::I32, 1, None, None))?;
+/// assert_eq!(memory.grow(&mut store, 1)?, None);
+/// # Ok::<(), tinywasm::Error>(())
+/// ```
 pub trait ResourceLimiter: Send + Sync {
-    /// Notifies the limiter that a linear memory is about to be allocated or grown.
-    ///
-    /// `current` and `desired` are byte sizes and are always multiples of the memory's page size.
-    /// `maximum` is the memory's declared maximum in bytes, or `None` when the memory is unbounded.
+    /// Returns whether a memory allocation or growth is allowed.
     ///
-    /// For initial allocation, `current` is zero. Return `Ok(true)` to allow the allocation or grow,
-    /// `Ok(false)` to reject it, or `Err` to return the supplied trap. A rejected initial allocation
-    /// returns [`Trap::OutOfMemory`], while a rejected `memory.grow` returns -1 to the guest.
-    fn memory_growing(&self, current: usize, desired: usize, maximum: Option<usize>) -> Result<bool, Trap>;
+    /// Sizes are in bytes. `current` is zero for initial allocation, and `maximum` is `None` for an
+    /// unbounded memory. `Ok(false)` rejects the request, while `Err` traps. Rejected initial
+    /// allocations return [`Trap::OutOfMemory`], since they have no normal failure result.
+    fn memory_growing(
+        &self,
+        current: usize,
+        desired: usize,
+        maximum: Option<usize>,
+    ) -> core::result::Result<bool, Trap>;
 }
 
-/// Global state that can be manipulated by WebAssembly programs
-///
-/// Managed WebAssembly GC objects are collected automatically. Other Store
-/// instances, such as modules, functions, memories, and tables, live until the
-/// Store is dropped. GC references exposed through the copyable host value API
-/// are retained for the Store's lifetime.
+/// Runtime state used by WebAssembly instances and host functions.
 ///
 /// ## Example
 /// ```rust

crates/tinywasm/tests/memory.rs

@@ -65,7 +65,7 @@ struct TrapGrowth;
 
 impl ResourceLimiter for TrapGrowth {
     fn memory_growing(&self, current: usize, _desired: usize, _maximum: Option<usize>) -> Result<bool, Trap> {
-        if current == 0 { Ok(true) } else { Err(Trap::Other("growth denied")) }
+        if current == 0 { Ok(true) } else { Err(Trap::Unreachable) }
     }
 }
 
@@ -80,16 +80,27 @@ fn resource_limiter_can_reject_growth() -> TestResult {
 }
 
 #[test]
-fn resource_limiter_can_trap_on_growth() -> TestResult {
-    let mut store = store_with_limiter(Arc::new(TrapGrowth));
-    let memory = Memory::new(&mut store, MemoryType::new(MemoryArch::I32, 1, None, None))?;
+fn resource_limiter_rejects_guest_memory_grow() -> TestResult {
+    let wasm = wat::parse_str(
+        r#"
+        (module
+          (memory 1)
+          (func (export "grow") (result i32)
+            i32.const 1
+            memory.grow))
+        "#,
+    )?;
+    let module = tinywasm::parse_bytes(&wasm)?;
+    let mut store = store_with_limiter(Arc::new(DenyGrowth));
+    let instance = ModuleInstance::instantiate(&mut store, &module, None)?;
 
-    assert!(matches!(memory.grow(&mut store, 1).unwrap_err(), tinywasm::Error::Trap(Trap::Other("growth denied"))));
+    let grow = instance.func::<(), i32>(&store, "grow")?;
+    assert_eq!(grow.call(&mut store, ())?, -1);
     Ok(())
 }
 
 #[test]
-fn resource_limiter_rejects_guest_memory_grow() -> TestResult {
+fn resource_limiter_can_trap_guest_memory_grow() -> TestResult {
     let wasm = wat::parse_str(
         r#"
         (module
@@ -100,11 +111,11 @@ fn resource_limiter_rejects_guest_memory_grow() -> TestResult {
         "#,
     )?;
     let module = tinywasm::parse_bytes(&wasm)?;
-    let mut store = store_with_limiter(Arc::new(DenyGrowth));
+    let mut store = store_with_limiter(Arc::new(TrapGrowth));
     let instance = ModuleInstance::instantiate(&mut store, &module, None)?;
 
     let grow = instance.func::<(), i32>(&store, "grow")?;
-    assert_eq!(grow.call(&mut store, ())?, -1);
+    assert!(matches!(grow.call(&mut store, ()), Err(tinywasm::Error::Trap(Trap::Unreachable))));
     Ok(())
 }