ixa/triggers/
periodic_time.rs

1use super::TriggerCriterion;
2use crate::{Context, ExecutionPhase};
3
4/// Trigger criterion for regular simulation time intervals.
5///
6/// [`PeriodicTimeTrigger`] observes the simulation clock and emits repeatedly at a configured
7/// period and execution phase.
8///
9/// ## Construction
10///
11/// ```rust,ignore
12/// PeriodicTimeTrigger::every(period)
13/// PeriodicTimeTrigger::every_with_phase(period, phase)
14/// PeriodicTimeTrigger::every(period).with_phase(phase) // Equivalent to `every_with_phase`
15/// PeriodicTimeTrigger::every(period).start_with_delay(delay)
16/// PeriodicTimeTrigger::every(period).start_at(start_time)
17/// ```
18///
19/// ## Observation
20///
21/// The observation data passed to
22/// [`TriggerCriterion::emit_with`](super::TriggerCriterion::emit_with) is
23/// [`PeriodicTimeTriggerEvent`]. It contains the simulation time observed when the scheduled
24/// periodic plan runs, the configured period, and the phase used to schedule it:
25///
26/// ```rust,ignore
27/// pub struct PeriodicTimeTriggerEvent {
28///     pub time: f64,
29///     pub period: f64,
30///     pub phase: ExecutionPhase,
31/// }
32/// ```
33///
34/// ## Semantics
35///
36/// This trigger uses the same rescheduling behavior as periodic plans: when the scheduled callback
37/// runs, the next occurrence is scheduled at `current_time + period` if there are still plans in the
38/// queue. Unlike [`Context::add_periodic_plan_with_phase`](crate::Context::add_periodic_plan_with_phase),
39/// the first occurrence is seeded explicitly so it can start at the current time, after a delay, or
40/// at an absolute simulation time.
41///
42/// By default, the first occurrence is scheduled at `context.get_current_time()` when the trigger is
43/// installed, and the execution phase is
44/// [`ExecutionPhase::Normal`](crate::ExecutionPhase::Normal).
45///
46/// The period must be positive, finite, and not NaN. A delay must be non-negative, finite, and not
47/// NaN. An absolute start time must be finite and not NaN; the context validates at trigger
48/// installation that it is not in the past.
49/// Builder inputs are converted to `f64` before these checks are applied.
50///
51/// Since time is monotonic, this criterion does not use [`Direction`](super::Direction) or
52/// [`TriggerMode`](super::TriggerMode). It emits whenever its periodic schedule executes. If several
53/// plans are scheduled for the same time, the selected [`ExecutionPhase`](crate::ExecutionPhase)
54/// controls phase ordering.
55///
56/// ## Example
57///
58/// ```rust
59/// use ixa::{Context, ExecutionPhase, IxaEvent};
60/// use ixa::triggers::{ContextTriggersExt, PeriodicTimeTrigger, TriggerCriterion};
61///
62/// #[derive(IxaEvent)]
63/// struct ReportTimeReached {
64///     time: f64,
65///     period: f64,
66///     phase: ExecutionPhase,
67/// }
68///
69/// let mut context = Context::new();
70///
71/// context.register_trigger(
72///     PeriodicTimeTrigger::every(7.0)
73///         .with_phase(ExecutionPhase::Last)
74///         .start_with_delay(7.0)
75///         .emit_with(|observation| ReportTimeReached {
76///             time: observation.time,
77///             period: observation.period,
78///             phase: observation.phase,
79///         }),
80/// );
81///
82/// context.subscribe_to_event(|_context, _event: ReportTimeReached| {
83///     // collect periodic reports
84/// });
85/// ```
86///
87pub struct PeriodicTimeTrigger {
88    period: f64,
89    start: PeriodicTimeTriggerStart,
90    phase: ExecutionPhase,
91}
92
93enum PeriodicTimeTriggerStart {
94    CurrentTime,
95    Delay(f64),
96    At(f64),
97}
98
99#[derive(Clone, Copy, Debug)]
100pub struct PeriodicTimeTriggerEvent {
101    pub time: f64,
102    pub period: f64,
103    pub phase: ExecutionPhase,
104}
105
106impl PeriodicTimeTrigger {
107    #[must_use]
108    pub fn every(period: impl Into<f64>) -> Self {
109        let period = period.into();
110        validate_period(period);
111        Self {
112            period,
113            start: PeriodicTimeTriggerStart::CurrentTime,
114            phase: ExecutionPhase::Normal,
115        }
116    }
117
118    #[must_use]
119    pub fn every_with_phase(period: impl Into<f64>, phase: ExecutionPhase) -> Self {
120        let period = period.into();
121        validate_period(period);
122        Self {
123            period,
124            start: PeriodicTimeTriggerStart::CurrentTime,
125            phase,
126        }
127    }
128
129    #[must_use]
130    pub fn with_phase(mut self, phase: ExecutionPhase) -> Self {
131        self.phase = phase;
132        self
133    }
134
135    #[must_use]
136    pub fn start_with_delay(mut self, delay: impl Into<f64>) -> Self {
137        let delay = delay.into();
138        assert!(
139            delay >= 0.0 && !delay.is_nan() && !delay.is_infinite(),
140            "delay must be greater than or equal to 0"
141        );
142        self.start = PeriodicTimeTriggerStart::Delay(delay);
143        self
144    }
145
146    #[must_use]
147    pub fn start_at(mut self, start_time: impl Into<f64>) -> Self {
148        let start_time = start_time.into();
149        assert!(
150            !start_time.is_nan(),
151            "start_time {start_time} is invalid: cannot be NaN"
152        );
153        assert!(
154            !start_time.is_infinite(),
155            "start_time {start_time} is invalid: cannot be infinite"
156        );
157        self.start = PeriodicTimeTriggerStart::At(start_time);
158        self
159    }
160}
161
162impl TriggerCriterion for PeriodicTimeTrigger {
163    type Observation = PeriodicTimeTriggerEvent;
164
165    fn install<F>(self, context: &mut Context, on_match: F)
166    where
167        F: Fn(&mut Context, Self::Observation) + 'static,
168    {
169        let start_time = match self.start {
170            PeriodicTimeTriggerStart::CurrentTime => context.get_current_time(),
171            PeriodicTimeTriggerStart::Delay(delay) => context.get_current_time() + delay,
172            PeriodicTimeTriggerStart::At(start_time) => start_time,
173        };
174        let period = self.period;
175        let phase = self.phase;
176
177        context.add_plan_with_phase(
178            start_time,
179            move |context| {
180                context.evaluate_periodic_and_schedule_next(
181                    period,
182                    move |context| {
183                        on_match(
184                            context,
185                            PeriodicTimeTriggerEvent {
186                                time: context.get_current_time(),
187                                period,
188                                phase,
189                            },
190                        );
191                    },
192                    phase,
193                );
194            },
195            phase,
196        );
197    }
198}
199
200fn validate_period(period: f64) {
201    assert!(
202        period > 0.0 && !period.is_nan() && !period.is_infinite(),
203        "period must be greater than 0"
204    );
205}
ixa/triggers/periodic_time.rs

ixa/triggers/
periodic_time.rs
