Struct ExecutionScheduler 

pub struct ExecutionScheduler { /* private fields */ }

The hot-path execution scheduler.

Implementations

impl ExecutionScheduler

pub fn new( registry: Arc<Mutex<AgentRegistry>>, context: Arc<RwLock<Context>>, agent_ids: &[AgentId], ) -> Self

Creates a new scheduler.

pub fn set_parallel_execution(&mut self, enabled: bool)

Enables or disables the parallel wave executor (default off).

Sound only when the phase’s agents correctly declare their AgentAccess: eligible agents must touch no World and write disjoint deck slots. With the default (all-Exclusive) declarations every wave is a singleton, so this is behaviourally identical to sequential execution.

pub fn set_telemetry_sender(&mut self, sender: Sender<TelemetryEvent>)

Connects the read-only observation tunnel to the DCC. The scheduler then publishes per-agent cost samples and per-component access snapshots so the cold path can fit cost models and recommend layouts. Non-blocking: if the channel is full the sample is dropped (telemetry is best-effort).

pub fn deck_mut(&mut self) -> &mut OutputDeck

Mutable access to the last frame’s [OutputDeck] — drained by the engine at the I/O boundary (e.g. GPU submit / present).

pub fn budget_channel(&self) -> &BudgetChannel

Returns a reference to the budget channel for the DCC to send budgets.

pub fn register_plugin(&mut self, plugin: EnginePlugin)

Registers an engine plugin.

pub fn set_phase_order(&mut self, order: &[ExecutionPhase])

Sets the phase execution order.

pub fn insert_after(&mut self, existing: ExecutionPhase, new: ExecutionPhase)

Inserts a phase after an existing phase.

pub fn insert_before(&mut self, existing: ExecutionPhase, new: ExecutionPhase)

Inserts a phase before an existing phase.

pub fn remove_phase(&mut self, phase: ExecutionPhase)

Removes a phase from the order.

pub fn run_frame(&mut self, world: &mut World, runtime: Arc<Runtime>)

Executes the complete frame cycle.

This is called every frame by the engine loop.

Fixed-timestep sequencing

Rendering runs at the display’s variable rate, but the simulation must advance in fixed increments to stay frame-rate independent and deterministic. The scheduler reconciles the two with an accumulator:

1. Measure the real wall-clock delta since the previous frame, clamped to [MAX_FRAME_DELTA_SECONDS] (spiral-of-death guard), and add it to sim_accumulator.
2. The fixed step is the smallest fixed_timestep declared by any registered agent (a single sim clock — physics owns it via its GORNA strategy). If no agent declares one, the frame degrades to the legacy “everything once per frame” path with no behaviour change.
3. Consume whole steps: steps = floor(accumulator / fixed_delta), capped at [MAX_SIM_STEPS]; the remainder carries over and yields the render interpolation_alpha.
4. Run the fixed-timestep agents (TRANSFORM-phase physics) steps times — a fixed-update sub-loop — so the provider advances N discrete sub-steps. Then run the regular phase loop once, excluding the agents already stepped, so OUTPUT-phase render fires a single time.
5. Publish the fresh Time (delta, fixed_delta, alpha) into the runtime resource before the render phase reads it.

Substrate Flows project once per frame; the GORNA completion map, budget arbitration, and telemetry all observe each individual agent invocation (a sub-step counts as a real run, with its own cost sample).