Skip to main content

nautilus_common/clock/
virtual.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Deterministic clock for controlled time advancement.
17
18use std::{
19    collections::{BTreeMap, BinaryHeap},
20    ops::Deref,
21    sync::Arc,
22};
23
24use nautilus_core::{
25    AtomicTime, DurationNanos, UUID4, UnixNanos, correctness::check_predicate_true,
26    string::formatting::Separable,
27};
28use ustr::Ustr;
29
30use super::{
31    CallbackRegistry, Clock, replace_existing_timer, validate_and_prepare_schedule,
32    validate_and_prepare_time_alert, validate_and_prepare_timer,
33};
34use crate::timer::{
35    ScheduledTimeEvent, TimeEvent, TimeEventCallback, TimeEventHandler, TimerInterval,
36    TimerSchedule, VirtualTimer, create_valid_interval,
37};
38
39/// A deterministic clock for controlled time advancement.
40///
41/// The clock stores a manual timestamp, schedules [`VirtualTimer`] instances, and returns due events
42/// without waiting for wall-clock time.
43///
44/// # Threading
45///
46/// This clock is thread-affine; use it only from the thread that created it.
47#[derive(Debug)]
48pub struct VirtualClock {
49    time: AtomicTime,
50    timers: BTreeMap<Ustr, VirtualTimer>,
51    pub(super) timer_queue: BinaryHeap<ScheduledTimeEvent>,
52    callbacks: CallbackRegistry,
53}
54
55impl VirtualClock {
56    /// Creates a virtual clock at the UNIX epoch with no timers or callbacks.
57    #[must_use]
58    pub fn new() -> Self {
59        Self {
60            time: AtomicTime::new(false, UnixNanos::default()),
61            timers: BTreeMap::new(),
62            timer_queue: BinaryHeap::new(),
63            callbacks: CallbackRegistry::new(),
64        }
65    }
66
67    /// Advances active timers through `to_time_ns` and returns their due events.
68    ///
69    /// Events at `to_time_ns` are included and returned in ascending order by event timestamp and
70    /// timer name. If `set_time` is `true`, the stored clock timestamp is also set to `to_time_ns`;
71    /// otherwise the stored timestamp remains unchanged.
72    ///
73    /// # Warnings
74    ///
75    /// Logs a warning if at least 1,000,000 time events are allocated during advancement.
76    ///
77    /// # Panics
78    ///
79    /// Panics if `to_time_ns` is less than the current internal clock time.
80    pub fn advance_time(&mut self, to_time_ns: UnixNanos, set_time: bool) -> Vec<TimeEvent> {
81        const WARN_TIME_EVENTS_THRESHOLD: usize = 1_000_000;
82
83        let from_time_ns = self.time.get_time_ns();
84
85        assert!(
86            to_time_ns >= from_time_ns,
87            "Invariant: time must be non-decreasing, `to_time_ns` {to_time_ns} < `from_time_ns` {from_time_ns}"
88        );
89
90        if set_time {
91            self.time.set_time(to_time_ns);
92        }
93
94        let mut events: Vec<TimeEvent> = Vec::new();
95
96        while self
97            .timer_queue
98            .peek()
99            .is_some_and(|entry| entry.0.ts_event <= to_time_ns)
100        {
101            let entry = self
102                .timer_queue
103                .pop()
104                .expect("timer queue peeked Some but pop returned None");
105
106            let Some((event, next_event)) = self.advance_timer_from_entry(&entry.0) else {
107                continue;
108            };
109
110            events.push(event);
111
112            if let Some(next_event) = next_event {
113                self.timer_queue.push(next_event);
114            }
115        }
116
117        self.compact_timer_queue_if_needed();
118
119        if events.len() >= WARN_TIME_EVENTS_THRESHOLD {
120            log::warn!(
121                "Allocated {} time events during clock advancement from {} to {}, \
122                 consider stopping the timer between large time ranges with no data points",
123                events.len().separate_with_commas(),
124                from_time_ns,
125                to_time_ns
126            );
127        }
128
129        events.sort_by(|a, b| {
130            a.ts_event
131                .cmp(&b.ts_event)
132                .then_with(|| a.name.cmp(&b.name))
133        });
134
135        events
136    }
137
138    /// Returns the earliest queued timer deadline, if any.
139    ///
140    /// Canceled or replaced timers can leave stale deadlines until [`Self::advance_time`]
141    /// removes them. Advancing to a deadline can also expire a timer without an event.
142    #[must_use]
143    pub fn next_event_time_ns(&self) -> Option<UnixNanos> {
144        self.timer_queue.peek().map(|entry| entry.0.ts_event)
145    }
146
147    /// Matches time events with their registered callbacks, preserving input order.
148    ///
149    /// A named callback takes precedence over the default callback for each event.
150    ///
151    /// # Panics
152    ///
153    /// Panics if an event has neither a named nor default callback.
154    #[must_use]
155    pub fn match_handlers(&self, events: Vec<TimeEvent>) -> Vec<TimeEventHandler> {
156        events
157            .into_iter()
158            .map(|event| self.callbacks.get_handler(event))
159            .collect()
160    }
161
162    fn replace_existing_timer_if_needed(&mut self, name: &Ustr) {
163        replace_existing_timer(&mut self.timers, name);
164        self.compact_timer_queue_if_needed();
165    }
166
167    fn insert_timer(&mut self, timer: VirtualTimer) {
168        self.timer_queue.push(Self::scheduled_event(&timer));
169        self.timers.insert(timer.name, timer);
170        self.compact_timer_queue_if_needed();
171    }
172
173    fn advance_timer_from_entry(
174        &mut self,
175        entry: &TimeEvent,
176    ) -> Option<(TimeEvent, Option<ScheduledTimeEvent>)> {
177        let timer = self.timers.get_mut(&entry.name)?;
178        if timer.next_time_ns() != entry.ts_event {
179            return None;
180        }
181
182        let Some((event, _)) = timer.next() else {
183            self.timers.remove(&entry.name);
184            return None;
185        };
186
187        let next_entry = if timer.is_expired() {
188            self.timers.remove(&entry.name);
189            None
190        } else {
191            Some(Self::scheduled_event(timer))
192        };
193
194        Some((event, next_entry))
195    }
196
197    fn compact_timer_queue_if_needed(&mut self) {
198        if self.timer_queue.len() > self.timers.len().saturating_mul(2) {
199            self.compact_timer_queue();
200        }
201    }
202
203    fn compact_timer_queue(&mut self) {
204        self.timer_queue = self.timers.values().map(Self::scheduled_event).collect();
205    }
206
207    fn scheduled_event(timer: &VirtualTimer) -> ScheduledTimeEvent {
208        ScheduledTimeEvent::new(TimeEvent::new(
209            timer.name,
210            UUID4::new(),
211            timer.next_time_ns(),
212            timer.next_time_ns(),
213        ))
214    }
215    fn register_timer(
216        &mut self,
217        name: Ustr,
218        interval: TimerInterval,
219        start_time_ns: UnixNanos,
220        stop_time_ns: Option<UnixNanos>,
221        callback: Option<TimeEventCallback>,
222        fire_immediately: bool,
223    ) -> anyhow::Result<()> {
224        check_predicate_true(
225            callback.is_some() | self.callbacks.has_any_callback(&name),
226            "No callbacks provided",
227        )?;
228
229        self.replace_existing_timer_if_needed(&name);
230        if let Some(callback) = callback {
231            self.callbacks.register_callback(name, callback);
232        }
233
234        let timer = VirtualTimer::new(
235            name,
236            interval,
237            start_time_ns,
238            stop_time_ns,
239            fire_immediately,
240        );
241        self.insert_timer(timer);
242
243        Ok(())
244    }
245}
246
247impl Default for VirtualClock {
248    /// Creates a new default [`VirtualClock`] instance.
249    fn default() -> Self {
250        Self::new()
251    }
252}
253
254impl Deref for VirtualClock {
255    type Target = AtomicTime;
256
257    fn deref(&self) -> &Self::Target {
258        &self.time
259    }
260}
261
262impl Clock for VirtualClock {
263    fn timestamp_ns(&self) -> UnixNanos {
264        self.time.get_time_ns()
265    }
266
267    fn timestamp_us(&self) -> u64 {
268        self.time.get_time_us()
269    }
270
271    fn timestamp_ms(&self) -> u64 {
272        self.time.get_time_ms()
273    }
274
275    fn timestamp(&self) -> f64 {
276        self.time.get_time()
277    }
278
279    fn timer_names(&self) -> Vec<&str> {
280        self.timers
281            .iter()
282            .filter(|(_, timer)| !timer.is_expired())
283            .map(|(k, _)| k.as_str())
284            .collect()
285    }
286
287    fn timer_count(&self) -> usize {
288        self.timers
289            .iter()
290            .filter(|(_, timer)| !timer.is_expired())
291            .count()
292    }
293
294    fn timer_exists(&self, name: &Ustr) -> bool {
295        self.timers
296            .get(name)
297            .is_some_and(|timer| !timer.is_expired())
298    }
299
300    fn register_default_handler(&mut self, callback: TimeEventCallback) {
301        self.callbacks.register_default_handler(callback);
302    }
303
304    fn cancel_default_handler(&mut self) {
305        self.callbacks.cancel_default_handler();
306    }
307
308    fn cancel_callbacks(&mut self) {
309        self.callbacks.clear();
310    }
311
312    fn set_time_alert_ns(
313        &mut self,
314        name: &str,
315        alert_time_ns: UnixNanos,
316        callback: Option<TimeEventCallback>,
317        allow_past: Option<bool>,
318    ) -> anyhow::Result<()> {
319        let ts_now = self.get_time_ns();
320        let (name, alert_time_ns) =
321            validate_and_prepare_time_alert(name, alert_time_ns, allow_past, ts_now)?;
322
323        check_predicate_true(
324            callback.is_some() | self.callbacks.has_any_callback(&name),
325            "No callbacks provided",
326        )?;
327
328        self.replace_existing_timer_if_needed(&name);
329
330        if let Some(callback) = callback {
331            self.callbacks.register_callback(name, callback);
332        }
333
334        // Safe to calculate interval now that we've ensured alert_time_ns >= ts_now
335        let interval_ns = create_valid_interval(alert_time_ns - ts_now);
336        let fire_immediately = alert_time_ns == ts_now;
337
338        let timer = VirtualTimer::new(
339            name,
340            interval_ns,
341            ts_now,
342            Some(alert_time_ns),
343            fire_immediately,
344        );
345        self.insert_timer(timer);
346
347        Ok(())
348    }
349
350    fn set_timer_ns(
351        &mut self,
352        name: &str,
353        interval_ns: DurationNanos,
354        start_time_ns: Option<UnixNanos>,
355        stop_time_ns: Option<UnixNanos>,
356        callback: Option<TimeEventCallback>,
357        allow_past: Option<bool>,
358        fire_immediately: Option<bool>,
359    ) -> anyhow::Result<()> {
360        let (name, start_time_ns, stop_time_ns, _, fire_immediately) = validate_and_prepare_timer(
361            name,
362            interval_ns,
363            start_time_ns,
364            stop_time_ns,
365            allow_past,
366            fire_immediately,
367            self.get_time_ns(),
368        )?;
369        self.register_timer(
370            name,
371            TimerInterval::Fixed(create_valid_interval(interval_ns)),
372            start_time_ns,
373            stop_time_ns,
374            callback,
375            fire_immediately,
376        )
377    }
378
379    fn set_timer_schedule(
380        &mut self,
381        name: &str,
382        schedule: Arc<dyn TimerSchedule>,
383        stop_time_ns: Option<UnixNanos>,
384        callback: Option<TimeEventCallback>,
385        allow_past: Option<bool>,
386        fire_immediately: Option<bool>,
387    ) -> anyhow::Result<()> {
388        let start_time_ns = schedule.start_time_ns();
389        let interval = TimerInterval::Schedule(schedule);
390        let (name, start_time_ns, stop_time_ns, _, fire_immediately) =
391            validate_and_prepare_schedule(
392                name,
393                &interval,
394                Some(start_time_ns),
395                stop_time_ns,
396                allow_past,
397                fire_immediately,
398                self.get_time_ns(),
399            )?;
400        self.register_timer(
401            name,
402            interval,
403            start_time_ns,
404            stop_time_ns,
405            callback,
406            fire_immediately,
407        )
408    }
409
410    fn next_time_ns(&self, name: &str) -> Option<UnixNanos> {
411        self.timers
412            .get(&Ustr::from(name))
413            .filter(|timer| !timer.is_expired())
414            .map(VirtualTimer::next_time_ns)
415    }
416
417    fn cancel_timer(&mut self, name: &str) {
418        let timer = self.timers.remove(&Ustr::from(name));
419        if let Some(mut timer) = timer {
420            timer.cancel();
421        }
422
423        self.compact_timer_queue_if_needed();
424    }
425
426    fn cancel_timers(&mut self) {
427        for timer in &mut self.timers.values_mut() {
428            timer.cancel();
429        }
430
431        self.timers.clear();
432        self.timer_queue.clear();
433    }
434
435    fn reset(&mut self) {
436        self.time = AtomicTime::new(false, UnixNanos::default());
437        self.timers = BTreeMap::new();
438        self.timer_queue = BinaryHeap::new();
439        self.callbacks.clear();
440    }
441}