From 84daa5fd70ff016d21d3d274e44d74f7caae1e31 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 5 Jun 2026 09:39:03 +0100 Subject: [PATCH] implements PLN-0090 --- .../services/vm_runtime/frame_scheduler.rs | 97 +++++++++++++++++++ .../src/services/vm_runtime/lifecycle.rs | 2 + .../src/services/vm_runtime/mod.rs | 3 + .../src/services/vm_runtime/tick.rs | 12 +++ discussion/index.ndjson | 2 +- ...N-0090-add-render-frame-pacing-contract.md | 2 +- 6 files changed, 116 insertions(+), 2 deletions(-) create mode 100644 crates/console/prometeu-system/src/services/vm_runtime/frame_scheduler.rs diff --git a/crates/console/prometeu-system/src/services/vm_runtime/frame_scheduler.rs b/crates/console/prometeu-system/src/services/vm_runtime/frame_scheduler.rs new file mode 100644 index 00000000..00ded757 --- /dev/null +++ b/crates/console/prometeu-system/src/services/vm_runtime/frame_scheduler.rs @@ -0,0 +1,97 @@ +use prometeu_hal::FrameId; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FrameAuthorizationError { + GameFrameAlreadyActive { active_frame_id: FrameId }, +} + +#[derive(Debug, Clone, Default)] +pub struct FrameScheduler { + next_game_frame_id: FrameId, + active_game_frame_id: Option, + completed_game_frames: u64, + logical_frame_overruns: u64, +} + +impl FrameScheduler { + pub fn authorize_game_frame(&mut self) -> Result { + if let Some(active_frame_id) = self.active_game_frame_id { + return Err(FrameAuthorizationError::GameFrameAlreadyActive { active_frame_id }); + } + + let frame_id = self.next_game_frame_id; + self.next_game_frame_id = self.next_game_frame_id.next(); + self.active_game_frame_id = Some(frame_id); + Ok(frame_id) + } + + pub fn complete_game_frame(&mut self) -> Option { + let completed = self.active_game_frame_id.take(); + if completed.is_some() { + self.completed_game_frames = self.completed_game_frames.wrapping_add(1); + } + completed + } + + pub fn record_logical_frame_overrun(&mut self) { + self.logical_frame_overruns = self.logical_frame_overruns.wrapping_add(1); + } + + pub fn active_game_frame_id(&self) -> Option { + self.active_game_frame_id + } + + pub fn completed_game_frames(&self) -> u64 { + self.completed_game_frames + } + + pub fn logical_frame_overruns(&self) -> u64 { + self.logical_frame_overruns + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn authorizes_one_game_frame_until_completion() { + let mut scheduler = FrameScheduler::default(); + + assert_eq!(scheduler.authorize_game_frame(), Ok(FrameId::ZERO)); + assert_eq!( + scheduler.authorize_game_frame(), + Err(FrameAuthorizationError::GameFrameAlreadyActive { active_frame_id: FrameId::ZERO }) + ); + + assert_eq!(scheduler.complete_game_frame(), Some(FrameId::ZERO)); + assert_eq!(scheduler.authorize_game_frame(), Ok(FrameId::new(1))); + } + + #[test] + fn completion_is_sequential_without_catch_up_frames() { + let mut scheduler = FrameScheduler::default(); + + for expected in 0..3 { + let frame_id = scheduler.authorize_game_frame().expect("frame authorization"); + assert_eq!(frame_id, FrameId::new(expected)); + assert_eq!(scheduler.complete_game_frame(), Some(FrameId::new(expected))); + } + + assert_eq!(scheduler.completed_game_frames(), 3); + } + + #[test] + fn records_logical_frame_overrun_without_advancing_frame_id() { + let mut scheduler = FrameScheduler::default(); + + assert_eq!(scheduler.authorize_game_frame(), Ok(FrameId::ZERO)); + scheduler.record_logical_frame_overrun(); + scheduler.record_logical_frame_overrun(); + + assert_eq!(scheduler.logical_frame_overruns(), 2); + assert_eq!(scheduler.active_game_frame_id(), Some(FrameId::ZERO)); + assert_eq!(scheduler.complete_game_frame(), Some(FrameId::ZERO)); + assert_eq!(scheduler.authorize_game_frame(), Ok(FrameId::new(1))); + } +} diff --git a/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs b/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs index 8fab82b8..10b570b9 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs @@ -22,6 +22,7 @@ impl VirtualMachineRuntime { current_cartridge_title: String::new(), current_cartridge_app_version: String::new(), current_cartridge_app_mode: AppMode::Game, + frame_scheduler: FrameScheduler::default(), render_manager: RenderManager::new(AppMode::Game), gfx2d_commands: Vec::new(), gfxui_commands: Vec::new(), @@ -119,6 +120,7 @@ impl VirtualMachineRuntime { self.current_cartridge_title.clear(); self.current_cartridge_app_version.clear(); self.current_cartridge_app_mode = AppMode::Game; + self.frame_scheduler = FrameScheduler::default(); self.render_manager = RenderManager::new(AppMode::Game); self.gfx2d_commands.clear(); self.gfxui_commands.clear(); diff --git a/crates/console/prometeu-system/src/services/vm_runtime/mod.rs b/crates/console/prometeu-system/src/services/vm_runtime/mod.rs index 41aeeb6f..c6b9ec44 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/mod.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/mod.rs @@ -1,4 +1,5 @@ mod dispatch; +mod frame_scheduler; mod lifecycle; pub mod render_manager; #[cfg(test)] @@ -6,6 +7,7 @@ mod tests; mod tick; use crate::CrashReport; +pub use frame_scheduler::FrameScheduler; use prometeu_bytecode::string_materialization_count; use prometeu_hal::app_mode::AppMode; use prometeu_hal::log::LogService; @@ -28,6 +30,7 @@ pub struct VirtualMachineRuntime { pub current_cartridge_title: String, pub current_cartridge_app_version: String, pub current_cartridge_app_mode: AppMode, + pub frame_scheduler: FrameScheduler, pub render_manager: RenderManager, pub gfx2d_commands: Vec, pub gfxui_commands: Vec, diff --git a/crates/console/prometeu-system/src/services/vm_runtime/tick.rs b/crates/console/prometeu-system/src/services/vm_runtime/tick.rs index fa26df0b..e242b805 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/tick.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/tick.rs @@ -141,6 +141,11 @@ impl VirtualMachineRuntime { self.update_fs(log_service, fs, fs_state); if !self.logical_frame_active { + if self.current_cartridge_app_mode == AppMode::Game { + self.frame_scheduler + .authorize_game_frame() + .expect("logical frame cannot start while another Game frame is active"); + } self.logical_frame_active = true; self.logical_frame_remaining_cycles = Self::CYCLES_PER_LOGICAL_FRAME; self.begin_logical_frame(signals, hw); @@ -317,6 +322,9 @@ impl VirtualMachineRuntime { self.logical_frame_index += 1; self.logical_frame_active = false; self.logical_frame_remaining_cycles = 0; + if self.current_cartridge_app_mode == AppMode::Game { + self.frame_scheduler.complete_game_frame(); + } if run.reason == LogicalFrameEndingReason::FrameSync { self.needs_prepare_entry_call = true; @@ -326,6 +334,10 @@ impl VirtualMachineRuntime { self.paused = true; self.debug_step_request = false; } + } else if run.reason == LogicalFrameEndingReason::BudgetExhausted + && self.current_cartridge_app_mode == AppMode::Game + { + self.frame_scheduler.record_logical_frame_overrun(); } } Err(e) => { diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 8152b547..35c3813e 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,6 +1,6 @@ {"type":"meta","next_id":{"DSC":42,"AGD":42,"DEC":32,"PLN":98,"LSN":48,"CLSN":1}} {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."} -{"type":"discussion","id":"DSC-0040","status":"in_progress","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-05","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[{"id":"AGD-0040","file":"AGD-0040-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-04","updated_at":"2026-06-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-06-05","ref_agenda":"AGD-0040"}],"plans":[{"id":"PLN-0087","file":"PLN-0087-fix-game2d-packet-overlay-composition.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0088","file":"PLN-0088-define-read-only-render-resource-boundary.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0089","file":"PLN-0089-introduce-render-handoff-abstraction.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0090","file":"PLN-0090-add-render-frame-pacing-contract.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0091","file":"PLN-0091-implement-appmode-render-policy-matrix.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0092","file":"PLN-0092-add-render-epoch-ownership-transitions.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0093","file":"PLN-0093-add-render-telemetry-counters-and-events.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0094","file":"PLN-0094-specify-async-render-boundary.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0095","file":"PLN-0095-prototype-local-render-worker-capability.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0096","file":"PLN-0096-define-render-shutdown-and-failure-handling.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0097","file":"PLN-0097-add-async-render-integration-test-matrix.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0040","status":"in_progress","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-05","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[{"id":"AGD-0040","file":"AGD-0040-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-04","updated_at":"2026-06-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-06-05","ref_agenda":"AGD-0040"}],"plans":[{"id":"PLN-0087","file":"PLN-0087-fix-game2d-packet-overlay-composition.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0088","file":"PLN-0088-define-read-only-render-resource-boundary.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0089","file":"PLN-0089-introduce-render-handoff-abstraction.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0090","file":"PLN-0090-add-render-frame-pacing-contract.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0091","file":"PLN-0091-implement-appmode-render-policy-matrix.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0092","file":"PLN-0092-add-render-epoch-ownership-transitions.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0093","file":"PLN-0093-add-render-telemetry-counters-and-events.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0094","file":"PLN-0094-specify-async-render-boundary.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0095","file":"PLN-0095-prototype-local-render-worker-capability.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0096","file":"PLN-0096-define-render-shutdown-and-failure-handling.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0097","file":"PLN-0097-add-async-render-integration-test-matrix.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]}],"lessons":[]} {"type":"discussion","id":"DSC-0041","status":"open","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-06-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]} {"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} diff --git a/discussion/workflow/plans/PLN-0090-add-render-frame-pacing-contract.md b/discussion/workflow/plans/PLN-0090-add-render-frame-pacing-contract.md index d097ee40..78511780 100644 --- a/discussion/workflow/plans/PLN-0090-add-render-frame-pacing-contract.md +++ b/discussion/workflow/plans/PLN-0090-add-render-frame-pacing-contract.md @@ -2,7 +2,7 @@ id: PLN-0090 ticket: vm-render-parallel-execution-boundary title: Add Render Frame Pacing Contract -status: open +status: done created: 2026-06-05 ref_decisions: [DEC-0031] tags: [runtime, frame-clock, scheduler, vm]