des_sim/execution/
phase.rs

1//! The `phase` module defines the different phases within a simulation tick,
2//! including micro-steps for event and source processing.
3//!
4//! It provides structures like `MicroStepHandler` to manage the execution flow
5//! within a tick and `MicroStepResult` to determine the next action.
6
7mod event;
8mod handler;
9mod source;
10
11use crate::context::ActiveExecutorContext;
12use crate::modeling::model::Model;
13use crate::primitive::time::MicroStepStatus;
14use crate::primitive::time::{MicroStep, SimTime};
15pub use event::*;
16pub use handler::*;
17pub use source::*;
18
19/// A wrapper for an execution context awaiting micro-step continuation validation.
20///
21/// This structure holds a "pending" context that has not yet been approved by
22/// a `ContinueStrategy`. By wrapping the `ActiveExecutorContext`, it enforces
23/// a pattern where the execution engine must explicitly call `into_active_executor()`
24/// after validation, effectively confirming that the simulation state is authorized
25/// to proceed to the next step.
26pub struct UncheckedActiveExecutor<E, M: Model<E>> {
27    active_executor: ActiveExecutorContext<E, M>,
28    current_micro_step: MicroStep,
29}
30
31impl<E, M: Model<E>> UncheckedActiveExecutor<E, M> {
32    pub(crate) fn new(
33        executor: ActiveExecutorContext<E, M>,
34        current_micro_step: MicroStep,
35    ) -> Self {
36        Self {
37            active_executor: executor,
38            current_micro_step,
39        }
40    }
41
42    /// Returns the current simulation time.
43    pub fn current_tick(&self) -> SimTime {
44        self.active_executor.current_tick_status.current()
45    }
46
47    /// Returns the current micro-step index.
48    pub fn current_micro_step(&self) -> MicroStep {
49        self.current_micro_step
50    }
51
52    /// Consumes this wrapper and returns the validated `ActiveExecutorContext`.
53    ///
54    /// This method is intended to be called only after a strategy has verified
55    /// that it is safe to continue the simulation.
56    pub fn into_active_executor(self) -> ActiveExecutorContext<E, M> {
57        self.active_executor
58    }
59}
60
61/// The result of a micro-step execution.
62///
63/// This enum dictates the next phase of the simulation, differentiating between
64/// whether execution should continue to the next micro-step (`Continue`) or
65/// terminate the current tick (`Complete`).
66pub enum MicroStepResult<E, M: Model<E>> {
67    /// Indicates that the simulation can continue. The `UncheckedActiveExecutor`
68    /// is passed forward to be validated by the assigned `ContinueStrategy`.
69    Continue(UncheckedActiveExecutor<E, M>),
70    /// Indicates that the current tick is finished. The `ActiveExecutorContext`
71    /// and the final `MicroStepStatus` are returned to finalize the tick's state.
72    Complete(ActiveExecutorContext<E, M>, MicroStepStatus),
73}
des_sim/execution/phase.rs

des_sim/execution/
phase.rs
