/build/source/src/execution/resumable.rs

Source
//! TODO

use alloc::vec::Vec;
use core::num::NonZeroU64;

use crate::{
    execution::runtime_structure::{store::Hostcode, value_stack::Stack},
    FuncAddr, Value,
};

/// A [`WasmResumable`] is an object used to resume execution of Wasm code.
///
/// # Safety
///
/// TODO:
///
/// - stack must be initialized with correct parameters to function
///   referenced by function address
/// - program counter must be valid for the bytecode of function referenced by the function address
/// - stp must point to the correct sidetable entry for the function referenced by function address
#[derive(Debug, Clone)]
pub struct WasmResumable {
    pub(crate) stack: Stack,
    pub(crate) pc: usize,
    pub(crate) stp: usize,
    pub(crate) current_func_addr: FuncAddr,
    pub(crate) maybe_fuel: Option<u64>,
}

impl WasmResumable {
    pub fn fuel(&self) -> Option<u64> {
        self.maybe_fuel
    }

    pub fn fuel_mut(&mut self) -> &mut Option<u64> {
        &mut self.maybe_fuel
    }
}

/// A [`HostCall`] object contains information required for executing a specific
/// host function.
#[derive(Clone, Debug)]
pub struct HostCall {
    /// Must contain the correct parameter types for the host function with host
    /// code `hostcode`.
    pub params: Vec<Value>,
    pub hostcode: Hostcode,
}

/// A [`HostResumable`] is used to resume execution after executing its
/// [`HostCall`].
///
/// When a host function is called, a [`HostResumable`] and [`HostCall`] are
/// returned. After the [`HostCall`] was used to execute the host function, the
/// [`HostResumable`] is used together with the return values of the host call
/// to resume execution.
#[derive(Debug)]
pub struct HostResumable {
    pub(crate) host_func_addr: FuncAddr,
    pub(crate) inner_resumable: Option<WasmResumable>,
    /// Hack: This is `Some` only if `inner_resumable` is `None`. In that case
    /// it is used to store the maybe_fuel, so it can be returned in
    /// [`RunState::Finished`] later.
    pub(crate) maybe_fuel: Option<Option<u64>>,
}

#[derive(Debug)]
pub enum Resumable {
    Wasm(WasmResumable),
    Host {
        host_call: HostCall,
        host_resumable: HostResumable,
    },
}

impl Resumable {
    /// Tries to convert this [`Resumable`] into a [`WasmResumable`]
    pub fn as_wasm(self) -> Option<WasmResumable> {
        match self {
            Self::Wasm(wasm_resumable) => Some(wasm_resumable),
            Self::Host { .. } => None,
        }
    }

    /// Tries to convert this [`Resumable`] into a [`HostCall`] and
    /// [`HostResumable`]
    pub fn as_host(self) -> Option<(HostCall, HostResumable)> {
        match self {
            Self::Wasm(_) => None,
            Self::Host {
                host_call,
                host_resumable,
            } => Some((host_call, host_resumable)),
        }
    }
}

/// Represents the state of a possibly interrupted resumable.
pub enum RunState {
    /// represents a resumable that has executed completely with return values `values` and possibly remaining fuel
    /// `maybe_remaining_fuel` (has `Some(remaining_fuel)` for fuel-metered operations and `None` otherwise)
    Finished {
        values: Vec<Value>,
        maybe_remaining_fuel: Option<u64>,
    },
    /// represents a resumable that has ran out of fuel during execution, missing at least `required_fuel` units of fuel
    /// to continue further execution (this is None if unknown).
    Resumable {
        resumable: WasmResumable,
        required_fuel: Option<NonZeroU64>,
    },
    /// A host function was called by Wasm code. Use the [`HostCall`] to execute
    /// the host function and resume execution using the [`HostResumable`] and
    /// the return values produced by execution.
    HostCalled {
        host_call: HostCall,
        resumable: HostResumable,
    },
}

Line	Count	Source
1		//! TODO
2
3		use alloc::vec::Vec;
4		use core::num::NonZeroU64;
5
6		use crate::{
7		execution::runtime_structure::{store::Hostcode, value_stack::Stack},
8		FuncAddr, Value,
9		};
10
11		/// A [`WasmResumable`] is an object used to resume execution of Wasm code.
12		///
13		/// # Safety
14		///
15		/// TODO:
16		///
17		/// - stack must be initialized with correct parameters to function
18		/// referenced by function address
19		/// - program counter must be valid for the bytecode of function referenced by the function address
20		/// - stp must point to the correct sidetable entry for the function referenced by function address
21		#[derive(Debug, Clone)]
22		pub struct WasmResumable {
23		pub(crate) stack: Stack,
24		pub(crate) pc: usize,
25		pub(crate) stp: usize,
26		pub(crate) current_func_addr: FuncAddr,
27		pub(crate) maybe_fuel: Option<u64>,
28		}
29
30		impl WasmResumable {
31	0	pub fn fuel(&self) -> Option<u64> {
32	0	self.maybe_fuel
33	0	}
34
35	47	pub fn fuel_mut(&mut self) -> &mut Option<u64> {
36	47	&mut self.maybe_fuel
37	47	}
38		}
39
40		/// A [`HostCall`] object contains information required for executing a specific
41		/// host function.
42		#[derive(Clone, Debug)]
43		pub struct HostCall {
44		/// Must contain the correct parameter types for the host function with host
45		/// code `hostcode`.
46		pub params: Vec<Value>,
47		pub hostcode: Hostcode,
48		}
49
50		/// A [`HostResumable`] is used to resume execution after executing its
51		/// [`HostCall`].
52		///
53		/// When a host function is called, a [`HostResumable`] and [`HostCall`] are
54		/// returned. After the [`HostCall`] was used to execute the host function, the
55		/// [`HostResumable`] is used together with the return values of the host call
56		/// to resume execution.
57		#[derive(Debug)]
58		pub struct HostResumable {
59		pub(crate) host_func_addr: FuncAddr,
60		pub(crate) inner_resumable: Option<WasmResumable>,
61		/// Hack: This is `Some` only if `inner_resumable` is `None`. In that case
62		/// it is used to store the maybe_fuel, so it can be returned in
63		/// [`RunState::Finished`] later.
64		pub(crate) maybe_fuel: Option<Option<u64>>,
65		}
66
67		#[derive(Debug)]
68		pub enum Resumable {
69		Wasm(WasmResumable),
70		Host {
71		host_call: HostCall,
72		host_resumable: HostResumable,
73		},
74		}
75
76		impl Resumable {
77		/// Tries to convert this [`Resumable`] into a [`WasmResumable`]
78	0	pub fn as_wasm(self) -> Option<WasmResumable> {
79	0	match self {
80	0	Self::Wasm(wasm_resumable) => Some(wasm_resumable),
81	0	Self::Host { .. } => None,
82		}
83	0	}
84
85		/// Tries to convert this [`Resumable`] into a [`HostCall`] and
86		/// [`HostResumable`]
87	0	pub fn as_host(self) -> Option<(HostCall, HostResumable)> {
88	0	match self {
89	0	Self::Wasm(_) => None,
90		Self::Host {
91	0	host_call,
92	0	host_resumable,
93	0	} => Some((host_call, host_resumable)),
94		}
95	0	}
96		}
97
98		/// Represents the state of a possibly interrupted resumable.
99		pub enum RunState {
100		/// represents a resumable that has executed completely with return values `values` and possibly remaining fuel
101		/// `maybe_remaining_fuel` (has `Some(remaining_fuel)` for fuel-metered operations and `None` otherwise)
102		Finished {
103		values: Vec<Value>,
104		maybe_remaining_fuel: Option<u64>,
105		},
106		/// represents a resumable that has ran out of fuel during execution, missing at least `required_fuel` units of fuel
107		/// to continue further execution (this is None if unknown).
108		Resumable {
109		resumable: WasmResumable,
110		required_fuel: Option<NonZeroU64>,
111		},
112		/// A host function was called by Wasm code. Use the [`HostCall`] to execute
113		/// the host function and resume execution using the [`HostResumable`] and
114		/// the return values produced by execution.
115		HostCalled {
116		host_call: HostCall,
117		resumable: HostResumable,
118		},
119		}

Coverage Report

Created: 2026-07-03 16:00