trellis_runner/watchers/
mod.rs

1#![allow(clippy::type_complexity)]
2
3use crate::engine::EngineSignal;
4use crate::state::{StateView, UserState};
5
6use std::sync::{Arc, Mutex};
7
8#[cfg(feature = "writing")]
9mod csv_file;
10
11mod failure;
12mod metrics;
13
14#[cfg(feature = "plotting")]
15mod plot;
16
17mod sampler;
18mod tracing;
19
20#[cfg(feature = "writing")]
21pub use csv_file::CsvProgressWriter;
22
23#[cfg(feature = "plotting")]
24pub use plot::PlotObserver;
25
26pub use tracing::Tracer;
27
28/// Core observer trait for the engine event system.
29///
30/// Observers receive a stream of signal events during execution
31/// along with a read-only view over the iteration state
32///
33/// ### Design
34/// - Uses `&self` to support shared observers (`Arc`)
35/// - State mutation must use interior mutability if required
36/// - Must be object-safe to allow dynamic dispatch
37pub trait Observe<S: UserState>: Send + Sync {
38    fn observe(&self, name: &'static str, state: StateView<'_, S>, event: &EngineSignal<S::Float>);
39}
40
41/// Blanket implementation for shared observers.
42///
43/// This allows `Arc<T>` to be used directly as an observer.
44impl<S, T> Observe<S> for Arc<T>
45where
46    S: UserState,
47    T: Observe<S> + ?Sized,
48{
49    fn observe(&self, name: &'static str, state: StateView<'_, S>, event: &EngineSignal<S::Float>) {
50        (**self).observe(name, state, event)
51    }
52}
53
54/// Frequency control for observer execution.
55///
56/// Allows observers to be:
57/// - always active
58/// - sampled at intervals
59/// - triggered only on termination
60/// - disabled entirely
61#[derive(Copy, Clone, Debug, Eq, PartialEq)]
62pub enum Frequency {
63    Always,
64    Every(usize),
65    OnExit,
66    Never,
67}
68
69impl Frequency {
70    fn should_run<F>(&self, event: &EngineSignal<F>, iteration: usize) -> bool {
71        match self {
72            Self::Never => false,
73            Self::Always => true,
74            Self::OnExit => matches!(event, EngineSignal::Termination(_)),
75            Self::Every(n) => *n != 0 && iteration.is_multiple_of(*n),
76        }
77    }
78}
79
80/// Container for all registered observers.
81///
82/// Observers are stored as `(observer, frequency)` pairs and dispatched
83/// during engine execution.
84pub struct Observers<S> {
85    inner: Vec<(Arc<Mutex<dyn Observe<S>>>, Frequency)>,
86}
87
88impl<S: UserState> Observers<S> {
89    /// Create an empty observer set.
90    pub fn new() -> Self {
91        Self { inner: Vec::new() }
92    }
93
94    /// Attach a new observer with a frequency policy.
95    pub fn attach(&mut self, observer: Arc<Mutex<dyn Observe<S>>>, frequency: Frequency) {
96        self.inner.push((observer, frequency));
97    }
98
99    /// Dispatch an event to all eligible observers.
100    ///
101    /// Observers are filtered using their [`Frequency`] policy.
102    pub fn dispatch(
103        &self,
104        ident: &'static str,
105        state: StateView<'_, S>,
106        event: &EngineSignal<S::Float>,
107    ) {
108        let iter = state.iteration();
109
110        for (obs, freq) in &self.inner {
111            if !freq.should_run(event, iter) {
112                continue;
113            }
114
115            let obs = obs.lock().unwrap();
116            obs.observe(ident, state, event);
117        }
118    }
119}
trellis_runner/watchers/mod.rs

trellis_runner/watchers/
mod.rs
