des-sim 0.1.0

Classical Event-Driven Simple Simulator Crate for Discrete Event System.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

//! The `hook` module defines the `Hook` trait, which provides a powerful mechanism
//! for observing and interacting with the simulation's lifecycle.
//!
//! By implementing this trait, users can inject custom logic at various points
//! during the simulation, such as before/after ticks, micro-steps, source firings,
//! and event processing. This is invaluable for logging, debugging, data collection,
//! and dynamic control of the simulation.

pub mod instance;

use crate::modeling::event::Event;
use crate::modeling::model::Model;
use crate::primitive::time::{Duration, MicroStep, SimTime};
use crate::source_handler::{SourceReadyEntry, SourceView};

/// A trait for hooking into lifecycle events of a simulation for extension or monitoring.
///
/// Implementing `Hook` allows for logging, tracing, state assertions, or dynamic
/// intervention during simulation execution. Since every method receives the
/// precise simulation state (time, step, model context), this trait provides the
/// foundation for building powerful diagnostic and analysis tools.
pub trait Hook<E, M: Model<E>> {
    // --- Simulation Lifecycle ---

    /// Invoked immediately before the simulation starts.
    fn before_simulation(&self, model: &M);

    /// Invoked immediately after the simulation finishes.
    fn after_simulation(&self, model: &M, end_tick: SimTime);

    // --- Tick Lifecycle ---

    /// Invoked at the beginning of a tick process.
    ///
    /// # Arguments
    /// * `skipped_duration` - The time skipped since the previous tick. When use not-skippable `Runner`, always 0 duration.
    fn before_tick(&self, model: &M, current_tick: SimTime, skipped_duration: Duration);

    /// Invoked immediately after a tick process has completed.
    fn after_tick(&self, model: &M, current_tick: SimTime, last_micro_step: MicroStep);

    /// Invoked at the beginning of a micro-step.
    fn before_micro_step(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);

    /// Invoked at the end of a micro-step.
    fn after_micro_step(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);

    /// Invoked when remaining tasks (events or sources) are discarded due to execution limits.
    fn on_discard_remain_micro_step(
        &self,
        model: &M,
        current_tick: SimTime,
        first_discarded_micro_step: MicroStep,
        discarded_sources: &[SourceReadyEntry],
        discarded_events: &[Event<E>],
    );

    // --- Source Lifecycle ---

    /// Invoked when a source registration begins.
    fn before_register_source(&self, model: &M, name: &str);

    /// Invoked when a source registration completes.
    fn after_register_source(&self, model: &M, name: &str);

    /// Invoked at the beginning of the source processing phase.
    fn before_source_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);

    /// Invoked immediately before an individual source fires.
    fn before_source(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        source_view: &SourceView,
    );

    /// Invoked immediately after an individual source fires.
    fn after_source(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        source_view: &SourceView,
        computed_next_fire: Option<SimTime>,
    );

    /// Invoked when a scheduled source is canceled.
    fn cancel_source(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        scheduled_at: SimTime,
        source_view: &SourceView,
    );

    /// Invoked when a source is explicitly discarded.
    fn discard_source(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        source_view: &SourceView,
    );

    /// Invoked at the end of the source processing phase.
    fn after_source_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);

    // --- Event Lifecycle ---

    /// Invoked at the beginning of the event processing phase.
    fn before_event_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);

    /// Invoked immediately before an event is processed.
    fn before_event(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        event: &Event<E>,
    );

    /// Invoked immediately after an event is processed.
    fn after_event(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        event: &Event<E>,
    );

    /// Invoked when a scheduled event is canceled.
    fn cancel_event(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        scheduled_at: SimTime,
        event: &Event<E>,
    );

    /// Invoked when an event is discarded.
    fn discard_event(
        &self,
        model: &M,
        current_tick: SimTime,
        current_micro_step: MicroStep,
        event: &Event<E>,
    );

    /// Invoked at the end of the event processing phase.
    fn after_event_phase(&self, model: &M, current_tick: SimTime, current_micro_step: MicroStep);
}