Allow function resumption after running out of fuel (#1498)

* rename resumable call types

* apply missing renaming

* move common state into the new ResumableCallCommon type

* deduplicate more potentially shared logic

* update resumable call integration tests

* add ResumableCall::OutOfFuel variant

* re-export [Typed]ResumableCallOutOfFuel variants

* move ResumableHostTrapError into resumable module

* add ResumableOutOfFuelError type

* add ResumableOutOfFuelError to Error

* add ResumableOutOfFuelError::into_error method

* extend FuelError with required_fuel info

* fix broken doc links

* integrate new OufOfFuel resumption into the engine

* reformat code a bit

* clean-up and refactor wast runner invoke

* move prepare_results lower in file

* merge impl blocks

* add ResumableCallHostTrap::into_host_error method

* extend Error::into_resumable method

* make Wasmi Wast runner use resumable calls if fuel metering is enabled

* apply rustfmt

* remove unused parameter

* apply rustfmt

* update instruction pointer upon failure

* no longer refuel with 6000 additional fuel on top

* only update ip if there is at least one call frame left

* preserve fuel when instantiating a module in Wast runner

* only update ip if the error is out-of-fuel

* apply clippy suggestion

Author: Robbepop

crates/core/src/fuel.rs

@@ -179,7 +179,7 @@ pub enum FuelError {
     /// Returned by some [`Fuel`] methods when fuel metering is disabled.
     FuelMeteringDisabled,
     /// Raised when trying to consume more fuel than is available.
-    OutOfFuel,
+    OutOfFuel { required_fuel: u64 },
 }
 
 impl Error for FuelError {}
@@ -188,7 +188,7 @@ impl fmt::Display for FuelError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Self::FuelMeteringDisabled => write!(f, "fuel metering is disabled"),
-            Self::OutOfFuel => write!(f, "all fuel consumed"),
+            Self::OutOfFuel { required_fuel } => write!(f, "ouf of fuel. required={required_fuel}"),
         }
     }
 }
@@ -210,8 +210,8 @@ impl FuelError {
     ///
     /// This method exists to indicate that this execution path is cold.
     #[cold]
-    pub fn out_of_fuel() -> Self {
-        Self::OutOfFuel
+    pub fn out_of_fuel(required_fuel: u64) -> Self {
+        Self::OutOfFuel { required_fuel }
     }
 }
 
@@ -295,7 +295,7 @@ impl Fuel {
         self.remaining = self
             .remaining
             .checked_sub(delta)
-            .ok_or(FuelError::OutOfFuel)?;
+            .ok_or(FuelError::out_of_fuel(delta))?;
         Ok(self.remaining)
     }
 

crates/core/src/limiter.rs

@@ -15,7 +15,7 @@ pub enum LimiterError {
     /// Returned if a [`ResourceLimiter`] denies allocation or growth.
     ResourceLimiterDeniedAllocation,
     /// Encountered when an operation ran out of fuel.
-    OutOfFuel,
+    OutOfFuel { required_fuel: u64 },
 }
 
 impl Error for LimiterError {}
@@ -26,7 +26,9 @@ impl Display for LimiterError {
             LimiterError::OutOfSystemMemory => "out of system memory",
             LimiterError::OutOfBoundsGrowth => "out of bounds growth",
             LimiterError::ResourceLimiterDeniedAllocation => "resource limiter denied allocation",
-            LimiterError::OutOfFuel => "out of fuel",
+            LimiterError::OutOfFuel { required_fuel } => {
+                return write!(f, "not enough fuel. required={required_fuel}")
+            }
         };
         write!(f, "{message}")
     }
@@ -38,7 +40,7 @@ impl From<MemoryError> for LimiterError {
             MemoryError::OutOfSystemMemory => Self::OutOfSystemMemory,
             MemoryError::OutOfBoundsGrowth => Self::OutOfBoundsGrowth,
             MemoryError::ResourceLimiterDeniedAllocation => Self::ResourceLimiterDeniedAllocation,
-            MemoryError::OutOfFuel => Self::OutOfFuel,
+            MemoryError::OutOfFuel { required_fuel } => Self::OutOfFuel { required_fuel },
             error => panic!("unexpected `MemoryError`: {error}"),
         }
     }
@@ -53,7 +55,7 @@ impl From<TableError> for LimiterError {
             | TableError::FillOutOfBounds
             | TableError::InitOutOfBounds => Self::OutOfBoundsGrowth,
             TableError::ResourceLimiterDeniedAllocation => Self::ResourceLimiterDeniedAllocation,
-            TableError::OutOfFuel => Self::OutOfFuel,
+            TableError::OutOfFuel { required_fuel } => Self::OutOfFuel { required_fuel },
             error => panic!("unexpected `TableError`: {error}"),
         }
     }

crates/core/src/memory/error.rs

@@ -21,7 +21,7 @@ pub enum MemoryError {
     /// The maximum size of the memory type overflows the system index type.
     MaximumSizeOverflow,
     /// Encountered if a `memory.grow` operation runs out of fuel.
-    OutOfFuel,
+    OutOfFuel { required_fuel: u64 },
 }
 
 impl Error for MemoryError {}
@@ -45,7 +45,9 @@ impl Display for MemoryError {
             Self::MaximumSizeOverflow => {
                 "the maximum size of the memory type overflows the system index type"
             }
-            Self::OutOfFuel => "out of fuel",
+            Self::OutOfFuel { required_fuel } => {
+                return write!(f, "not enough fuel. required={required_fuel}")
+            }
         };
         write!(f, "{message}")
     }
@@ -57,7 +59,7 @@ impl From<LimiterError> for MemoryError {
             LimiterError::OutOfSystemMemory => Self::OutOfSystemMemory,
             LimiterError::OutOfBoundsGrowth => Self::OutOfBoundsGrowth,
             LimiterError::ResourceLimiterDeniedAllocation => Self::ResourceLimiterDeniedAllocation,
-            LimiterError::OutOfFuel => Self::OutOfFuel,
+            LimiterError::OutOfFuel { required_fuel } => Self::OutOfFuel { required_fuel },
         }
     }
 }

crates/core/src/memory/mod.rs

@@ -21,7 +21,7 @@ pub use self::{
     error::MemoryError,
     ty::{MemoryType, MemoryTypeBuilder},
 };
-use crate::{Fuel, ResourceLimiterRef};
+use crate::{Fuel, FuelError, ResourceLimiterRef};
 
 #[cfg(feature = "simd")]
 pub use self::access::ExtendInto;
@@ -237,11 +237,10 @@ impl Memory {
             let additional_bytes = additional
                 .checked_mul(bytes_per_page)
                 .expect("additional size is within [min, max) page bounds");
-            if fuel
-                .consume_fuel_if(|costs| costs.fuel_for_copying_bytes(additional_bytes))
-                .is_err()
+            if let Err(FuelError::OutOfFuel { required_fuel }) =
+                fuel.consume_fuel_if(|costs| costs.fuel_for_copying_bytes(additional_bytes))
             {
-                return notify_limiter(limiter, MemoryError::OutOfFuel);
+                return notify_limiter(limiter, MemoryError::OutOfFuel { required_fuel });
             }
         }
         // At this point all checks passed to grow the linear memory:

crates/core/src/table/error.rs

@@ -29,7 +29,7 @@ pub enum TableError {
     /// Occurs when operating with a [`Table`](crate::Table) and mismatching element types.
     ElementTypeMismatch,
     /// The operation ran out of fuel before completion.
-    OutOfFuel,
+    OutOfFuel { required_fuel: u64 },
 }
 
 impl Error for TableError {}
@@ -51,7 +51,9 @@ impl Display for TableError {
             Self::CopyOutOfBounds => "out of bounds table access: `table.copy`",
             Self::SetOutOfBounds => "out of bounds table access: `table.set`",
             Self::ElementTypeMismatch => "encountered mismatching table element type",
-            Self::OutOfFuel => "out of fuel",
+            Self::OutOfFuel { required_fuel } => {
+                return write!(f, "not enough fuel: required={required_fuel}")
+            }
         };
         write!(f, "{message}")
     }
@@ -63,15 +65,15 @@ impl From<LimiterError> for TableError {
             LimiterError::OutOfSystemMemory => Self::OutOfSystemMemory,
             LimiterError::OutOfBoundsGrowth => Self::GrowOutOfBounds,
             LimiterError::ResourceLimiterDeniedAllocation => Self::ResourceLimiterDeniedAllocation,
-            LimiterError::OutOfFuel => Self::OutOfFuel,
+            LimiterError::OutOfFuel { required_fuel } => Self::OutOfFuel { required_fuel },
         }
     }
 }
 
 impl From<FuelError> for TableError {
     fn from(error: FuelError) -> Self {
         match error {
-            FuelError::OutOfFuel => Self::OutOfFuel,
+            FuelError::OutOfFuel { required_fuel } => Self::OutOfFuel { required_fuel },
             FuelError::FuelMeteringDisabled => panic!("fuel metering is disabled"),
         }
     }

crates/core/src/table/mod.rs

@@ -170,7 +170,9 @@ impl Table {
         if let Some(fuel) = fuel {
             match fuel.consume_fuel(|costs| costs.fuel_for_copying_values(delta)) {
                 Ok(_) | Err(FuelError::FuelMeteringDisabled) => {}
-                Err(FuelError::OutOfFuel) => return notify_limiter(limiter, TableError::OutOfFuel),
+                Err(FuelError::OutOfFuel { required_fuel }) => {
+                    return notify_limiter(limiter, TableError::OutOfFuel { required_fuel })
+                }
             }
         }
         if self.elements.try_reserve(delta_size).is_err() {

crates/wasmi/src/engine/code_map.rs

@@ -8,8 +8,8 @@
 use super::{FuncTranslationDriver, FuncTranslator, TranslationError, ValidatingFuncTranslator};
 use crate::{
     collections::arena::{Arena, ArenaIndex},
-    core::{Fuel, FuelCostsProvider, FuelError, TrapCode, UntypedVal},
-    engine::utils::unreachable_unchecked,
+    core::{Fuel, FuelCostsProvider, FuelError, UntypedVal},
+    engine::{utils::unreachable_unchecked, ResumableOutOfFuelError},
     ir::{index::InternalFunc, Instruction},
     module::{FuncIdx, ModuleHeader},
     Config,
@@ -628,7 +628,9 @@ impl UncompiledFuncEntity {
         };
         if let Some(fuel) = fuel {
             match fuel.consume_fuel(compilation_fuel) {
-                Err(FuelError::OutOfFuel) => return Err(Error::from(TrapCode::OutOfFuel)),
+                Err(FuelError::OutOfFuel { required_fuel }) => {
+                    return Err(Error::from(ResumableOutOfFuelError::new(required_fuel)))
+                }
                 Ok(_) | Err(FuelError::FuelMeteringDisabled) => {}
             }
         }

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

@@ -1,4 +1,4 @@
-pub use self::call::{dispatch_host_func, ResumableHostError};
+pub use self::call::dispatch_host_func;
 use super::{cache::CachedInstance, InstructionPtr, Stack};
 use crate::{
     core::{hint, wasm, ReadAs, TrapCode, UntypedVal, WriteAs},
@@ -70,7 +70,18 @@ pub fn execute_instrs<'engine>(
 ) -> Result<(), Error> {
     let instance = stack.calls.instance_expect();
     let cache = CachedInstance::new(store.inner_mut(), instance);
-    Executor::new(stack, code_map, cache).execute(store)
+    let mut executor = Executor::new(stack, code_map, cache);
+    if let Err(error) = executor.execute(store) {
+        if error.is_out_of_fuel() {
+            if let Some(frame) = executor.stack.calls.peek_mut() {
+                // Note: we need to update the instruction pointer to make it possible to
+                //       resume execution at the current instruction after running out of fuel.
+                frame.update_instr_ptr(executor.ip);
+            }
+        }
+        return Err(error);
+    }
+    Ok(())
 }
 
 /// An execution context for executing a Wasmi function frame.
@@ -118,7 +129,7 @@ impl<'engine> Executor<'engine> {
 
     /// Executes the function frame until it returns or traps.
     #[inline(always)]
-    fn execute(mut self, store: &mut PrunedStore) -> Result<(), Error> {
+    fn execute(&mut self, store: &mut PrunedStore) -> Result<(), Error> {
         use Instruction as Instr;
         loop {
             match *self.ip.get() {

crates/wasmi/src/engine/executor/instrs/call.rs

@@ -7,6 +7,7 @@ use crate::{
         utils::unreachable_unchecked,
         EngineFunc,
         FuncInOut,
+        ResumableHostTrapError,
     },
     func::{FuncEntity, HostFuncEntity},
     ir::{index, Instruction, Reg, RegSpan},
@@ -16,7 +17,7 @@ use crate::{
     FuncRef,
     Instance,
 };
-use core::{array, fmt};
+use core::array;
 
 /// Dispatches and executes the host function.
 ///
@@ -63,52 +64,6 @@ pub enum CallKind {
     Tail,
 }
 
-/// Error returned from a called host function in a resumable state.
-#[derive(Debug)]
-pub struct ResumableHostError {
-    /// The error returned by the called host function.
-    host_error: Error,
-    /// The host function that returned the error.
-    host_func: Func,
-    /// The result registers of the caller of the host function.
-    caller_results: RegSpan,
-}
-
-impl core::error::Error for ResumableHostError {}
-
-impl fmt::Display for ResumableHostError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        self.host_error.fmt(f)
-    }
-}
-
-impl ResumableHostError {
-    /// Creates a new [`ResumableHostError`].
-    #[cold]
-    pub(crate) fn new(host_error: Error, host_func: Func, caller_results: RegSpan) -> Self {
-        Self {
-            host_error,
-            host_func,
-            caller_results,
-        }
-    }
-
-    /// Consumes `self` to return the underlying [`Error`].
-    pub(crate) fn into_error(self) -> Error {
-        self.host_error
-    }
-
-    /// Returns the [`Func`] of the [`ResumableHostError`].
-    pub(crate) fn host_func(&self) -> &Func {
-        &self.host_func
-    }
-
-    /// Returns the caller results [`RegSpan`] of the [`ResumableHostError`].
-    pub(crate) fn caller_results(&self) -> &RegSpan {
-        &self.caller_results
-    }
-}
-
 trait CallContext {
     const KIND: CallKind;
     const HAS_PARAMS: bool;
@@ -497,11 +452,11 @@ impl Executor<'_> {
     /// # Note
     ///
     /// This uses the value stack to store parameters and results of the host function call.
-    /// Returns an [`ErrorKind::ResumableHost`] variant if the host function returned an error
+    /// Returns an [`ErrorKind::ResumableHostTrap`] variant if the host function returned an error
     /// and there are still call frames on the call stack making it possible to resume the
     /// execution at a later point in time.
     ///
-    /// [`ErrorKind::ResumableHost`]: crate::error::ErrorKind::ResumableHost
+    /// [`ErrorKind::ResumableHostTrap`]: crate::error::ErrorKind::ResumableHostTrap
     fn execute_host_func<C: CallContext>(
         &mut self,
         store: &mut PrunedStore,
@@ -535,7 +490,7 @@ impl Executor<'_> {
         self.dispatch_host_func(store, host_func, &instance)
             .map_err(|error| match self.stack.calls.is_empty() {
                 true => error,
-                false => ResumableHostError::new(error, *func, results).into(),
+                false => ResumableHostTrapError::new(error, *func, results).into(),
             })?;
         self.cache.update(store.inner_mut(), &instance);
         let results = results.iter(len_results);

crates/wasmi/src/engine/executor/instrs/memory.rs

@@ -1,7 +1,7 @@
 use super::{Executor, InstructionPtr};
 use crate::{
     core::{MemoryError, ResourceLimiterRef, TrapCode},
-    engine::utils::unreachable_unchecked,
+    engine::{utils::unreachable_unchecked, ResumableOutOfFuelError},
     ir::{
         index::{Data, Memory},
         Const16,
@@ -120,14 +120,15 @@ impl Executor<'_> {
                 unsafe { self.cache.update_memory(store) };
                 return_value
             }
-            Err(
-                MemoryError::OutOfBoundsGrowth
-                | MemoryError::OutOfFuel
-                | MemoryError::OutOfSystemMemory,
-            ) => match memory.ty().is_64() {
-                true => u64::MAX,
-                false => u64::from(u32::MAX),
-            },
+            Err(MemoryError::OutOfBoundsGrowth | MemoryError::OutOfSystemMemory) => {
+                match memory.ty().is_64() {
+                    true => u64::MAX,
+                    false => u64::from(u32::MAX),
+                }
+            }
+            Err(MemoryError::OutOfFuel { required_fuel }) => {
+                return Err(Error::from(ResumableOutOfFuelError::new(required_fuel)))
+            }
             Err(MemoryError::ResourceLimiterDeniedAllocation) => {
                 return Err(Error::from(TrapCode::GrowthOperationLimited))
             }