des_sim/modeling/
hook.rs

1//! The `hook` module defines the `Hook` trait, which provides a powerful mechanism
2//! for observing and interacting with the simulation's lifecycle.
3//!
4//! By implementing this trait, users can inject custom logic at various points
5//! during the simulation, such as before/after ticks, micro-steps, source firings,
6//! and event processing. This is invaluable for logging, debugging, data collection,
7//! and dynamic control of the simulation.
8
9pub mod instance;
10
11use crate::modeling::event::Event;
12use crate::modeling::model::Model;
13use crate::primitive::time::{Duration, MicroStep, SimTime};
14use crate::source_handler::{SourceReadyEntry, SourceView};
15
16/// A trait for hooking into lifecycle events of a simulation for extension or monitoring.
17///
18/// Implementing `Hook` allows for logging, tracing, state assertions, or dynamic
19/// intervention during simulation execution. Since every method receives the
20/// precise simulation state (time, step, model context), this trait provides the
21/// foundation for building powerful diagnostic and analysis tools.
22pub trait Hook<E, M: Model<E>> {
23    // --- Simulation Lifecycle ---
24
25    /// Invoked immediately before the simulation starts.
26    fn before_simulation(&self, model: &M);
27
28    /// Invoked immediately after the simulation finishes.
29    fn after_simulation(&self, model: &M, end_tick: SimTime);
30
31    // --- Tick Lifecycle ---
32
33    /// Invoked at the beginning of a tick process.
34    ///
35    /// # Arguments
36    /// * `skipped_duration` - The time skipped since the previous tick. When use not-skippable `Runner`, always 0 duration.
37    fn before_tick(&self, model: &M, current_tick: SimTime, skipped_duration: Duration);
38
39    /// Invoked immediately after a tick process has completed.
40    fn after_tick(&self, model: &M, current_tick: SimTime, last_micro_step: MicroStep);
41
42    /// Invoked at the beginning of a micro-step.
43    fn before_micro_step(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);
44
45    /// Invoked at the end of a micro-step.
46    fn after_micro_step(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);
47
48    /// Invoked when remaining tasks (events or sources) are discarded due to execution limits.
49    fn on_discard_remain_micro_step(
50        &self,
51        model: &M,
52        current_tick: SimTime,
53        first_discarded_micro_step: MicroStep,
54        discarded_sources: &[SourceReadyEntry],
55        discarded_events: &[Event<E>],
56    );
57
58    // --- Source Lifecycle ---
59
60    /// Invoked when a source registration begins.
61    fn before_register_source(&self, model: &M, name: &str);
62
63    /// Invoked when a source registration completes.
64    fn after_register_source(&self, model: &M, name: &str);
65
66    /// Invoked at the beginning of the source processing phase.
67    fn before_source_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);
68
69    /// Invoked immediately before an individual source fires.
70    fn before_source(
71        &self,
72        model: &M,
73        current_tick: SimTime,
74        current_micro_step: MicroStep,
75        source_view: &SourceView,
76    );
77
78    /// Invoked immediately after an individual source fires.
79    fn after_source(
80        &self,
81        model: &M,
82        current_tick: SimTime,
83        current_micro_step: MicroStep,
84        source_view: &SourceView,
85        computed_next_fire: Option<SimTime>,
86    );
87
88    /// Invoked when a scheduled source is canceled.
89    fn cancel_source(
90        &self,
91        model: &M,
92        current_tick: SimTime,
93        current_micro_step: MicroStep,
94        scheduled_at: SimTime,
95        source_view: &SourceView,
96    );
97
98    /// Invoked when a source is explicitly discarded.
99    fn discard_source(
100        &self,
101        model: &M,
102        current_tick: SimTime,
103        current_micro_step: MicroStep,
104        source_view: &SourceView,
105    );
106
107    /// Invoked at the end of the source processing phase.
108    fn after_source_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);
109
110    // --- Event Lifecycle ---
111
112    /// Invoked at the beginning of the event processing phase.
113    fn before_event_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);
114
115    /// Invoked immediately before an event is processed.
116    fn before_event(
117        &self,
118        model: &M,
119        current_tick: SimTime,
120        current_micro_step: MicroStep,
121        event: &Event<E>,
122    );
123
124    /// Invoked immediately after an event is processed.
125    fn after_event(
126        &self,
127        model: &M,
128        current_tick: SimTime,
129        current_micro_step: MicroStep,
130        event: &Event<E>,
131    );
132
133    /// Invoked when a scheduled event is canceled.
134    fn cancel_event(
135        &self,
136        model: &M,
137        current_tick: SimTime,
138        current_micro_step: MicroStep,
139        scheduled_at: SimTime,
140        event: &Event<E>,
141    );
142
143    /// Invoked when an event is discarded.
144    fn discard_event(
145        &self,
146        model: &M,
147        current_tick: SimTime,
148        current_micro_step: MicroStep,
149        event: &Event<E>,
150    );
151
152    /// Invoked at the end of the event processing phase.
153    fn after_event_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);
154}
des_sim/modeling/hook.rs

des_sim/modeling/
hook.rs
