elevator_core/
hooks.rs

1//! Lifecycle hooks for injecting custom logic before/after simulation phases.
2//!
3//! # Example
4//!
5//! ```rust
6//! use elevator_core::prelude::*;
7//! use elevator_core::hooks::Phase;
8//!
9//! let mut sim = SimulationBuilder::new()
10//!     .before(Phase::Dispatch, |world| {
11//!         // Inspect world state before dispatch runs
12//!         let idle_count = world.iter_idle_elevators().count();
13//!         let _ = idle_count; // use it
14//!     })
15//!     .build()
16//!     .unwrap();
17//!
18//! sim.step(); // hooks fire during each step
19//! ```
20
21use crate::ids::GroupId;
22use crate::world::World;
23use std::collections::HashMap;
24
25/// Simulation phase identifier for hook registration.
26///
27/// Each variant corresponds to one phase in the tick loop. Hooks registered
28/// for a phase run immediately before or after that phase executes.
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
30#[non_exhaustive]
31pub enum Phase {
32    /// Advance transient rider states (Boarding→Riding, Exiting→Arrived).
33    AdvanceTransient,
34    /// Assign idle elevators to stops via dispatch strategy.
35    Dispatch,
36    /// Update elevator position and velocity.
37    Movement,
38    /// Tick door finite-state machines.
39    Doors,
40    /// Board and exit riders.
41    Loading,
42    /// Reposition idle elevators for better coverage.
43    Reposition,
44    /// Aggregate metrics from tick events.
45    Metrics,
46}
47
48/// A boxed closure that receives mutable world access during a phase hook.
49pub(crate) type PhaseHook = Box<dyn Fn(&mut World) + Send + Sync>;
50
51/// Storage for before/after hooks keyed by phase.
52#[derive(Default)]
53pub(crate) struct PhaseHooks {
54    /// Hooks to run before each phase.
55    before: HashMap<Phase, Vec<PhaseHook>>,
56    /// Hooks to run after each phase.
57    after: HashMap<Phase, Vec<PhaseHook>>,
58    /// Hooks to run before a phase for a specific group.
59    before_group: HashMap<(Phase, GroupId), Vec<PhaseHook>>,
60    /// Hooks to run after a phase for a specific group.
61    after_group: HashMap<(Phase, GroupId), Vec<PhaseHook>>,
62}
63
64impl PhaseHooks {
65    /// Run all before-hooks for the given phase.
66    pub(crate) fn run_before(&self, phase: Phase, world: &mut World) {
67        if let Some(hooks) = self.before.get(&phase) {
68            for hook in hooks {
69                hook(world);
70            }
71        }
72    }
73
74    /// Run all after-hooks for the given phase.
75    pub(crate) fn run_after(&self, phase: Phase, world: &mut World) {
76        if let Some(hooks) = self.after.get(&phase) {
77            for hook in hooks {
78                hook(world);
79            }
80        }
81    }
82
83    /// Register a hook to run before a phase.
84    pub(crate) fn add_before(&mut self, phase: Phase, hook: PhaseHook) {
85        self.before.entry(phase).or_default().push(hook);
86    }
87
88    /// Register a hook to run after a phase.
89    pub(crate) fn add_after(&mut self, phase: Phase, hook: PhaseHook) {
90        self.after.entry(phase).or_default().push(hook);
91    }
92
93    /// Run all before-hooks for the given phase and group.
94    pub(crate) fn run_before_group(&self, phase: Phase, group: GroupId, world: &mut World) {
95        if let Some(hooks) = self.before_group.get(&(phase, group)) {
96            for hook in hooks {
97                hook(world);
98            }
99        }
100    }
101
102    /// Run all after-hooks for the given phase and group.
103    pub(crate) fn run_after_group(&self, phase: Phase, group: GroupId, world: &mut World) {
104        if let Some(hooks) = self.after_group.get(&(phase, group)) {
105            for hook in hooks {
106                hook(world);
107            }
108        }
109    }
110
111    /// Register a hook to run before a phase for a specific group.
112    pub(crate) fn add_before_group(&mut self, phase: Phase, group: GroupId, hook: PhaseHook) {
113        self.before_group
114            .entry((phase, group))
115            .or_default()
116            .push(hook);
117    }
118
119    /// Register a hook to run after a phase for a specific group.
120    pub(crate) fn add_after_group(&mut self, phase: Phase, group: GroupId, hook: PhaseHook) {
121        self.after_group
122            .entry((phase, group))
123            .or_default()
124            .push(hook);
125    }
126}
elevator_core/hooks.rs

elevator_core/
hooks.rs
