des_sim/modeling/
source.rs

1//! The `source` module defines the `Source` trait, which is used to create
2//! event generators within the simulation.
3//!
4//! Sources are responsible for scheduling events, either periodically or based
5//! on specific conditions, and can be configured to fire once or repeatedly.
6//! This module also re-exports `SourceReadyEntry` and `SourceView` for
7//! interacting with sources.
8
9use crate::context::{SourceContext, UserContext};
10use crate::modeling::model::Model;
11use crate::primitive::time::Duration;
12
13// Re-exporting these types to keep the internal `source_handler` module private
14// while exposing a clean API for modeling.
15pub use crate::source_handler::{SourceReadyEntry, SourceView};
16
17/// Defines the interface for a simulation source.
18///
19/// Sources are responsible for scheduling events or influencing the simulation
20/// based on their internal logic.
21pub trait Source<E, M: Model<E>>: Send {
22    /// Callback executed when the source is registered.
23    ///
24    /// This is invoked regardless of whether the simulation has started or is currently running.
25    /// The `context` provides access to either [SourceContext] (at startup) or
26    /// [EventContext](crate::context::EventContext) (during runtime).
27    ///
28    /// # Warning
29    ///
30    /// If this method schedules an event with [Duration::zero()] that re-registers this
31    /// source, it may result in an infinite micro-step loop.
32    fn on_registered(&mut self, context: &mut dyn UserContext<E, M>, model: &M)
33    -> Option<Duration>;
34
35    /// Executes the source's primary logic when triggered.
36    ///
37    /// # Returns
38    ///
39    /// The [Duration] until the next scheduled fire event, or `None` if no
40    /// further events should be scheduled.
41    fn fire(&mut self, context: &mut SourceContext<E, M>, model: &M) -> Option<Duration>;
42}
des_sim/modeling/source.rs

des_sim/modeling/
source.rs
