Redesign StackLimits API for Engine's config (#1631)

* redesign StackLimits API for Engine's config

- Removed `StackLimits`
- Removed `Config::set_stack_limits` method
- Add `Config::set_{min_stack_height,max_stack_height,max_cached_stacks}`
- Add and use `StackConfig` internally

* fix broken doc links

* fix more broken doc links

* apply rustfmt

* add Error and Display impls to StackConfigError

* re-add deprecated types and APIs with deprecation note

* fix Wasmi fuzz configuration

Author: Robbepop

crates/fuzz/src/oracle/wasmi.rs

@@ -11,7 +11,6 @@ use wasmi::{
     Instance,
     Linker,
     Module,
-    StackLimits,
     Store,
     StoreLimits,
     StoreLimitsBuilder,
@@ -62,14 +61,9 @@ impl DifferentialOracleMeta for WasmiOracle {
         //
         // We increase the maximum stack space for Wasmi (register) to avoid
         // common stack overflows in certain generated fuzz test cases this way.
-        config.set_stack_limits(
-            StackLimits::new(
-                1024,             // 1 kiB
-                1024 * 1024 * 10, // 10 MiB
-                1024,
-            )
-            .unwrap(),
-        );
+        config.set_min_stack_height(1024); // 1 kiB
+        config.set_max_stack_height(1024 * 1024 * 10); // 10 MiB
+        config.set_max_recursion_depth(1024);
         config.wasm_custom_page_sizes(true);
         config.wasm_wide_arithmetic(true);
         let engine = Engine::new(&config);

crates/wasmi/benches/bench/mod.rs

@@ -1,5 +1,5 @@
 use std::{fs::File, io::Read as _};
-use wasmi::{Config, StackLimits};
+use wasmi::Config;
 
 /// Returns the Wasm binary at the given `file_name` as `Vec<u8>`.
 ///
@@ -24,7 +24,9 @@ pub fn load_wasm_from_file(file_name: &str) -> Vec<u8> {
 pub fn bench_config() -> Config {
     let mut config = Config::default();
     config.wasm_tail_call(true);
-    config.set_stack_limits(StackLimits::new(1024, 1024 * 1024, 64 * 1024).unwrap());
+    config.set_min_stack_height(1024);
+    config.set_max_stack_height(1024 * 1024);
+    config.set_max_recursion_depth(64 * 1024);
     config
 }
 

crates/wasmi/src/engine/config.rs

@@ -1,19 +1,16 @@
-use super::{EnforcedLimits, StackLimits};
+#[expect(deprecated)]
+use super::StackLimits;
+use super::{EnforcedLimits, StackConfig};
 use crate::core::FuelCostsProvider;
 use wasmparser::WasmFeatures;
 
-/// The default amount of stacks kept in the cache at most.
-const DEFAULT_CACHED_STACKS: usize = 2;
-
 /// Configuration for an [`Engine`].
 ///
 /// [`Engine`]: [`crate::Engine`]
 #[derive(Debug, Clone)]
 pub struct Config {
     /// The limits set on the value stack and call stack.
-    stack_limits: StackLimits,
-    /// The amount of Wasm stacks to keep in cache at most.
-    cached_stacks: usize,
+    pub(crate) stack: StackConfig,
     /// The Wasm features used when validating or translating functions.
     features: WasmFeatures,
     /// Is `true` if Wasmi executions shall consume fuel.
@@ -48,8 +45,7 @@ pub enum CompilationMode {
 impl Default for Config {
     fn default() -> Self {
         Self {
-            stack_limits: StackLimits::default(),
-            cached_stacks: DEFAULT_CACHED_STACKS,
+            stack: StackConfig::default(),
             features: Self::default_features(),
             consume_fuel: false,
             ignore_custom_sections: false,
@@ -84,29 +80,91 @@ impl Config {
     }
 
     /// Sets the [`StackLimits`] for the [`Config`].
-    pub fn set_stack_limits(&mut self, stack_limits: StackLimits) -> &mut Self {
-        self.stack_limits = stack_limits;
+    #[deprecated(
+        since = "0.51.0",
+        note = "\
+            use `Config::set_{min,max}_stack_height`, \
+            `Config::max_recursion_depth` instead"
+    )]
+    #[expect(deprecated)]
+    pub fn set_stack_limits(&mut self, limits: StackLimits) -> &mut Self {
+        self.set_min_stack_height(limits.initial_value_stack_height);
+        self.set_max_stack_height(limits.maximum_value_stack_height);
+        self.set_max_recursion_depth(limits.maximum_recursion_depth);
         self
     }
 
-    /// Returns the [`StackLimits`] of the [`Config`].
-    pub(super) fn stack_limits(&self) -> StackLimits {
-        self.stack_limits
-    }
-
     /// Sets the maximum amount of cached stacks for reuse for the [`Config`].
     ///
     /// # Note
     ///
     /// Defaults to 2.
+    #[deprecated(since = "0.51.0", note = "use `Config::set_max_cached_stacks` instead")]
     pub fn set_cached_stacks(&mut self, amount: usize) -> &mut Self {
-        self.cached_stacks = amount;
+        self.set_max_cached_stacks(amount);
+        self
+    }
+
+    /// Sets the maximum recursion depth of the [`Engine`]'s stack during execution.
+    ///
+    /// # Note
+    ///
+    /// An execution traps if it exceeds this limits.
+    ///
+    /// [`Engine`]: [`crate::Engine`]
+    pub fn set_max_recursion_depth(&mut self, value: usize) -> &mut Self {
+        self.stack.set_max_recursion_depth(value);
+        self
+    }
+
+    /// Sets the minimum (or initial) height of the [`Engine`]'s value stack in bytes.
+    ///
+    /// # Note
+    ///
+    /// - Lower initial heights may improve memory consumption.
+    /// - Higher initial heights may improve cold start times.
+    ///
+    /// # Panics
+    ///
+    /// If `value` is greater than the current maximum height of the value stack.
+    ///
+    /// [`Engine`]: [`crate::Engine`]
+    pub fn set_min_stack_height(&mut self, value: usize) -> &mut Self {
+        if self.stack.set_min_stack_height(value).is_err() {
+            let max = self.stack.max_stack_height();
+            panic!("minimum stack height exceeds maximum: min={value}, max={max}");
+        }
         self
     }
 
-    /// Returns the maximum amount of cached stacks for reuse of the [`Config`].
-    pub(super) fn cached_stacks(&self) -> usize {
-        self.cached_stacks
+    /// Sets the maximum height of the [`Engine`]'s value stack in bytes.
+    ///
+    /// # Note
+    ///
+    /// An execution traps if it exceeds this limits.
+    ///
+    /// # Panics
+    ///
+    /// If `value` is less than the current minimum height of the value stack.
+    ///
+    /// [`Engine`]: [`crate::Engine`]
+    pub fn set_max_stack_height(&mut self, value: usize) -> &mut Self {
+        if self.stack.set_max_stack_height(value).is_err() {
+            let max = self.stack.min_stack_height();
+            panic!("maximum stack height is lower than minimum: min={value}, max={max}");
+        }
+        self
+    }
+
+    /// Sets the maximum number of cached stacks for reuse for the [`Config`].
+    ///
+    /// # Note
+    ///
+    /// - A higher value may improve execution performance.
+    /// - A lower value may improve memory consumption.
+    pub fn set_max_cached_stacks(&mut self, value: usize) -> &mut Self {
+        self.stack.set_max_cached_stacks(value);
+        self
     }
 
     /// Enable or disable the [`mutable-global`] Wasm proposal for the [`Config`].

crates/wasmi/src/engine/executor/mod.rs

@@ -24,9 +24,6 @@ use crate::{
     StoreContextMut,
 };
 
-#[cfg(doc)]
-use crate::engine::StackLimits;
-
 use super::{code_map::CodeMap, ResumableError};
 
 mod cache;
@@ -226,7 +223,7 @@ pub struct EngineExecutor<'engine> {
 fn do_nothing<T>(_: &mut T) {}
 
 impl<'engine> EngineExecutor<'engine> {
-    /// Creates a new [`EngineExecutor`] with the given [`StackLimits`].
+    /// Creates a new [`EngineExecutor`] for the given [`Stack`].
     fn new(code_map: &'engine CodeMap, stack: &'engine mut Stack) -> Self {
         Self { code_map, stack }
     }

crates/wasmi/src/engine/executor/stack/mod.rs

@@ -11,7 +11,7 @@ pub use self::{
         ValueStack,
     },
 };
-use crate::{Instance, StackLimits, TrapCode};
+use crate::{engine::StackConfig, Instance, TrapCode};
 
 /// Returns a [`TrapCode`] signalling a stack overflow.
 #[cold]
@@ -32,12 +32,9 @@ impl Stack {
     /// Creates a new [`Stack`] given the [`Config`].
     ///
     /// [`Config`]: [`crate::Config`]
-    pub fn new(limits: StackLimits) -> Self {
-        let calls = CallStack::new(limits.maximum_recursion_depth);
-        let values = ValueStack::new(
-            limits.initial_value_stack_height,
-            limits.maximum_value_stack_height,
-        );
+    pub fn new(config: &StackConfig) -> Self {
+        let calls = CallStack::new(config.max_recursion_depth());
+        let values = ValueStack::new(config.min_stack_height(), config.max_stack_height());
         Self { calls, values }
     }
 

crates/wasmi/src/engine/limits/mod.rs

@@ -4,7 +4,9 @@ mod stack;
 #[cfg(test)]
 mod tests;
 
+#[expect(deprecated)]
+pub use self::stack::StackLimits;
 pub use self::{
     engine::{EnforcedLimits, EnforcedLimitsError},
-    stack::StackLimits,
+    stack::StackConfig,
 };