feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...

This commit is contained in:
2026-10-13 12:18:18 +01:00
parent 23dc6fc66d
commit 0af8b2b1fe
39 changed files with 1381 additions and 70 deletions
@@ -7,6 +7,7 @@ mod collections_tests;
mod control;
mod dynamic;
mod gc;
mod lifecycle;
mod loader;
mod random;
mod reference;
@@ -49,6 +50,8 @@ use prometeu_test_support::program::{TestProgram, int64_signature};
pub enum LogicalFrameEndingReason {
/// Execution reached a `FRAME_SYNC` instruction, marking the end of the logical frame.
FrameSync,
/// The outer lifecycle callback returned; gameplay has not resumed.
LifecycleComplete,
/// The cycle budget for the current host tick was exhausted before reaching `FRAME_SYNC`.
BudgetExhausted,
/// A `HALT` instruction was executed, terminating the program.
@@ -109,6 +112,8 @@ pub struct VirtualMachine {
cycles: u64,
/// Stop flag: true if a `HALT` opcode was encountered.
halted: bool,
lifecycle: Option<lifecycle::LifecycleCall>,
lifecycle_failure: Option<LogicalFrameEndingReason>,
/// Set of ROM addresses used for software breakpoints in the debugger.
breakpoints: std::collections::HashSet<usize>,
/// GC: number of newly allocated live objects threshold to trigger a collection at safepoint.
@@ -229,6 +234,8 @@ impl VirtualMachine {
heap: Heap::with_budget(&budget),
cycles: 0,
halted: true,
lifecycle: None,
lifecycle_failure: None,
breakpoints: std::collections::HashSet::new(),
gc_alloc_threshold: 1024, // conservative default; tests may override
last_gc_live_count: 0,
@@ -257,7 +264,7 @@ impl VirtualMachine {
/// 1. Fetch: Read the opcode from memory.
/// 2. Decode: Identify what operation to perform.
/// 3. Execute: Perform the operation, updating stacks, memory, or calling peripherals.
pub fn step(
fn step_inner(
&mut self,
native: &mut dyn NativeInterface,
ctx: &mut HostContext,
@@ -1039,6 +1046,14 @@ impl VirtualMachine {
return self.execute_collection(opcode, ty, field, start_pc as u32);
}
OpCode::FrameSync => {
if self.lifecycle.is_some() {
return Err(self.trap(
TRAP_TYPE,
opcode as u16,
"FRAME_SYNC is forbidden in lifecycle hooks".into(),
start_pc as u32,
));
}
// Marks the logical end of a frame: consume cycles and signal to the driver
self.cycles += OpCode::FrameSync.cycles();
self.handle_safepoint()
@@ -1152,7 +1167,11 @@ mod tests {
typed_test_vm(
code,
constant_pool,
vec![FunctionDecl { max_stack_slots: 256, ..Default::default() }],
vec![FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 256,
..Default::default()
}],
)
}
fn limited_session(code: Vec<u8>, limits: RuntimeLimits) -> VirtualMachine {
@@ -1196,6 +1215,7 @@ mod tests {
TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
@@ -1511,8 +1531,13 @@ mod tests {
rom,
vec![],
vec![
FunctionDecl { max_stack_slots: 256, ..Default::default() },
FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 256,
..Default::default()
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: func_addr as u32,
signature: int64_signature(1, 1),
max_stack_slots: 256,
@@ -1593,8 +1618,13 @@ mod tests {
rom2,
vec![],
vec![
FunctionDecl { max_stack_slots: 256, ..Default::default() },
FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 256,
..Default::default()
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: func_addr2 as u32,
signature: int64_signature(0, 1),
max_stack_slots: 256,
@@ -1834,6 +1864,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -2449,6 +2480,7 @@ mod tests {
let header = TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
@@ -2964,6 +2996,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 1),
@@ -2974,6 +3007,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
signature: scalar_signature(2, 1, 1),
@@ -3025,6 +3059,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 1),
@@ -3035,6 +3070,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
signature: scalar_signature(0, 2, 1),
@@ -3085,6 +3121,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 1),
@@ -3095,6 +3132,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
signature: scalar_signature(1, 0, 1),
@@ -3210,6 +3248,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
local_slots: 1,
@@ -3269,6 +3308,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 4),
@@ -3279,6 +3319,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
local_slots: 1,
@@ -3391,6 +3432,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3439,6 +3481,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3506,6 +3549,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3556,6 +3600,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3606,6 +3651,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3661,6 +3707,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),