Skip to main content

nautilus_common/live/
clock.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//! Live clock implementation using Tokio for real-time operations.
17
18use std::{collections::BTreeMap, ops::Deref, sync::Arc};
19
20use nautilus_core::{
21    AtomicTime, DurationNanos, UnixNanos, correctness::check_predicate_true,
22    time::get_atomic_clock_realtime,
23};
24use ustr::Ustr;
25
26use super::timer::LiveTimer;
27use crate::{
28    clock::{
29        CallbackRegistry, Clock, replace_existing_timer, validate_and_prepare_schedule,
30        validate_and_prepare_time_alert, validate_and_prepare_timer,
31    },
32    runner::{TimeEventSender, purge_closed_time_event_callbacks, try_get_time_event_sender},
33    timer::{TimeEventCallback, TimerInterval, TimerSchedule, create_valid_interval},
34};
35
36/// A real-time clock which uses system time.
37///
38/// Timestamps are guaranteed to be unique and monotonically increasing.
39///
40/// # Threading
41///
42/// The clock holds thread-local runtime state and must remain on its originating thread.
43#[derive(Debug)]
44pub struct LiveClock {
45    time: &'static AtomicTime,
46    timers: BTreeMap<Ustr, LiveTimer>,
47    callbacks: CallbackRegistry,
48    sender: Option<Arc<dyn TimeEventSender>>,
49    sender_deferred: bool,
50}
51
52impl LiveClock {
53    /// Creates a new [`LiveClock`] instance.
54    #[must_use]
55    pub fn new(sender: Option<Arc<dyn TimeEventSender>>) -> Self {
56        Self {
57            time: get_atomic_clock_realtime(),
58            timers: BTreeMap::new(),
59            callbacks: CallbackRegistry::new(),
60            sender,
61            sender_deferred: false,
62        }
63    }
64
65    fn clear_expired_timers(&mut self) {
66        self.timers.retain(|_, timer| !timer.is_expired());
67        purge_closed_time_event_callbacks();
68    }
69
70    fn replace_existing_timer_if_needed(&mut self, name: &Ustr) {
71        replace_existing_timer(&mut self.timers, name);
72    }
73    fn register_timer(
74        &mut self,
75        name: Ustr,
76        interval: TimerInterval,
77        start_time_ns: UnixNanos,
78        stop_time_ns: Option<UnixNanos>,
79        callback: Option<TimeEventCallback>,
80        fire_immediately: bool,
81    ) -> anyhow::Result<()> {
82        check_predicate_true(
83            callback.is_some() | self.callbacks.has_any_callback(&name),
84            "No callbacks provided",
85        )?;
86
87        self.replace_existing_timer_if_needed(&name);
88        if let Some(callback) = callback {
89            self.callbacks.register_callback(name, callback);
90        }
91
92        let callback = self
93            .callbacks
94            .get_callback(&name)
95            .expect("Callback should exist");
96
97        let sender = self.resolve_time_event_sender();
98
99        let mut timer = LiveTimer::new(
100            name,
101            interval,
102            start_time_ns,
103            stop_time_ns,
104            callback,
105            fire_immediately,
106            sender,
107        );
108        timer.start();
109
110        self.clear_expired_timers();
111        self.timers.insert(name, timer);
112
113        Ok(())
114    }
115}
116
117impl Default for LiveClock {
118    /// Creates a new default [`LiveClock`] instance.
119    ///
120    /// Uses `try_get_time_event_sender()` to allow creation before channels are initialized.
121    fn default() -> Self {
122        let mut clock = Self::new(try_get_time_event_sender());
123        clock.sender_deferred = clock.sender.is_none();
124        clock
125    }
126}
127
128impl Deref for LiveClock {
129    type Target = AtomicTime;
130
131    fn deref(&self) -> &Self::Target {
132        self.time
133    }
134}
135
136impl Clock for LiveClock {
137    fn timestamp_ns(&self) -> UnixNanos {
138        self.time.get_time_ns()
139    }
140
141    fn timestamp_us(&self) -> u64 {
142        self.time.get_time_us()
143    }
144
145    fn timestamp_ms(&self) -> u64 {
146        self.time.get_time_ms()
147    }
148
149    fn timestamp(&self) -> f64 {
150        self.time.get_time()
151    }
152
153    fn timer_names(&self) -> Vec<&str> {
154        self.timers
155            .iter()
156            .filter(|(_, timer)| !timer.is_expired())
157            .map(|(k, _)| k.as_str())
158            .collect()
159    }
160
161    fn timer_count(&self) -> usize {
162        self.timers
163            .iter()
164            .filter(|(_, timer)| !timer.is_expired())
165            .count()
166    }
167
168    fn timer_exists(&self, name: &Ustr) -> bool {
169        self.timers
170            .get(name)
171            .is_some_and(|timer| !timer.is_expired())
172    }
173
174    fn register_default_handler(&mut self, handler: TimeEventCallback) {
175        self.callbacks.register_default_handler(handler);
176    }
177
178    fn cancel_default_handler(&mut self) {
179        self.callbacks.cancel_default_handler();
180    }
181
182    fn cancel_callbacks(&mut self) {
183        self.callbacks.clear();
184    }
185
186    fn set_time_alert_ns(
187        &mut self,
188        name: &str,
189        alert_time_ns: UnixNanos,
190        callback: Option<TimeEventCallback>,
191        allow_past: Option<bool>,
192    ) -> anyhow::Result<()> {
193        let ts_now = self.get_time_ns();
194        let (name, alert_time_ns) =
195            validate_and_prepare_time_alert(name, alert_time_ns, allow_past, ts_now)?;
196
197        check_predicate_true(
198            callback.is_some() | self.callbacks.has_any_callback(&name),
199            "No callbacks provided",
200        )?;
201
202        self.replace_existing_timer_if_needed(&name);
203        if let Some(callback) = callback {
204            self.callbacks.register_callback(name, callback);
205        }
206
207        let callback = self
208            .callbacks
209            .get_callback(&name)
210            .expect("Callback should exist");
211
212        // Safe to calculate interval now that we've ensured alert_time_ns >= ts_now
213        let interval_ns = create_valid_interval(alert_time_ns - ts_now);
214        let fire_immediately = alert_time_ns == ts_now;
215        let sender = self.resolve_time_event_sender();
216
217        let mut timer = LiveTimer::new(
218            name,
219            interval_ns,
220            ts_now,
221            Some(alert_time_ns),
222            callback,
223            fire_immediately,
224            sender,
225        );
226
227        timer.start();
228
229        self.clear_expired_timers();
230        self.timers.insert(name, timer);
231
232        Ok(())
233    }
234
235    fn set_timer_ns(
236        &mut self,
237        name: &str,
238        interval_ns: DurationNanos,
239        start_time_ns: Option<UnixNanos>,
240        stop_time_ns: Option<UnixNanos>,
241        callback: Option<TimeEventCallback>,
242        allow_past: Option<bool>,
243        fire_immediately: Option<bool>,
244    ) -> anyhow::Result<()> {
245        let (name, start_time_ns, stop_time_ns, _, fire_immediately) = validate_and_prepare_timer(
246            name,
247            interval_ns,
248            start_time_ns,
249            stop_time_ns,
250            allow_past,
251            fire_immediately,
252            self.get_time_ns(),
253        )?;
254        self.register_timer(
255            name,
256            TimerInterval::Fixed(create_valid_interval(interval_ns)),
257            start_time_ns,
258            stop_time_ns,
259            callback,
260            fire_immediately,
261        )
262    }
263
264    fn set_timer_schedule(
265        &mut self,
266        name: &str,
267        schedule: Arc<dyn TimerSchedule>,
268        stop_time_ns: Option<UnixNanos>,
269        callback: Option<TimeEventCallback>,
270        allow_past: Option<bool>,
271        fire_immediately: Option<bool>,
272    ) -> anyhow::Result<()> {
273        let start_time_ns = schedule.start_time_ns();
274        let interval = TimerInterval::Schedule(schedule);
275        let (name, start_time_ns, stop_time_ns, _, fire_immediately) =
276            validate_and_prepare_schedule(
277                name,
278                &interval,
279                Some(start_time_ns),
280                stop_time_ns,
281                allow_past,
282                fire_immediately,
283                self.get_time_ns(),
284            )?;
285        self.register_timer(
286            name,
287            interval,
288            start_time_ns,
289            stop_time_ns,
290            callback,
291            fire_immediately,
292        )
293    }
294
295    fn next_time_ns(&self, name: &str) -> Option<UnixNanos> {
296        self.timers
297            .get(&Ustr::from(name))
298            .filter(|timer| !timer.is_expired())
299            .map(LiveTimer::next_time_ns)
300    }
301
302    fn cancel_timer(&mut self, name: &str) {
303        let timer = self.timers.remove(&Ustr::from(name));
304        if let Some(mut timer) = timer {
305            timer.cancel();
306        }
307    }
308
309    fn cancel_timers(&mut self) {
310        for timer in &mut self.timers.values_mut() {
311            timer.cancel();
312        }
313
314        self.timers.clear();
315    }
316
317    fn reset(&mut self) {
318        self.cancel_timers();
319        self.callbacks.clear();
320    }
321}
322
323impl LiveClock {
324    fn resolve_time_event_sender(&mut self) -> Option<Arc<dyn TimeEventSender>> {
325        if self.sender.is_none() && self.sender_deferred {
326            self.sender = try_get_time_event_sender();
327        }
328
329        self.sender.clone()
330    }
331}
332
333#[cfg(test)]
334#[cfg(not(all(feature = "simulation", madsim)))]
335mod tests {
336    use std::{
337        sync::{
338            Arc,
339            atomic::{AtomicBool, AtomicUsize, Ordering},
340            mpsc,
341        },
342        time::Duration,
343    };
344
345    use nautilus_core::{DurationNanos, UnixNanos, time::get_atomic_clock_realtime};
346    use parking_lot::Mutex;
347    use rstest::rstest;
348    use ustr::Ustr;
349
350    use super::*;
351    use crate::{
352        calendar::CalendarSchedule,
353        clock::Clock,
354        runner::{TimeEventMessage, TimeEventSender, replace_time_event_sender},
355        testing::wait_until,
356        timer::{TimeEvent, TimeEventCallback},
357    };
358
359    #[derive(Debug)]
360    struct CollectingSender {
361        events: Arc<Mutex<Vec<(TimeEvent, UnixNanos)>>>,
362    }
363
364    impl CollectingSender {
365        fn new(events: Arc<Mutex<Vec<(TimeEvent, UnixNanos)>>>) -> Self {
366            Self { events }
367        }
368    }
369
370    impl TimeEventSender for CollectingSender {
371        fn send(&self, message: TimeEventMessage) {
372            let now_ns = get_atomic_clock_realtime().get_time_ns();
373            let event = message.event().clone();
374            message.dispatch();
375            self.events.lock().push((event, now_ns));
376        }
377    }
378
379    #[derive(Debug)]
380    struct QueuedSender(mpsc::Sender<TimeEventMessage>);
381
382    impl TimeEventSender for QueuedSender {
383        fn send(&self, message: TimeEventMessage) {
384            self.0.send(message).unwrap();
385        }
386    }
387
388    #[rstest]
389    #[case::alert(false)]
390    #[case::timer(true)]
391    fn test_live_clock_revokes_queued_callbacks(
392        #[case] recurring: bool,
393        #[values(false, true)] named: bool,
394        #[values(false, true)] local: bool,
395    ) {
396        let (tx, rx) = mpsc::channel();
397        let sender = Arc::new(QueuedSender(tx));
398        let mut clock = LiveClock::new(Some(sender));
399        let calls = Arc::new(AtomicUsize::new(0));
400        let callback_calls = calls.clone();
401        let callback = move |_: TimeEvent| {
402            callback_calls.fetch_add(1, Ordering::Relaxed);
403        };
404
405        let callback = if local {
406            TimeEventCallback::RustLocal(std::rc::Rc::new(callback))
407        } else {
408            TimeEventCallback::from(callback)
409        };
410
411        clock.register_default_handler(callback.clone());
412        for retire in [false, true] {
413            let explicit = named.then(|| callback.clone());
414
415            if recurring {
416                clock
417                    .set_timer_ns(
418                        "queued",
419                        DurationNanos::from_secs(60),
420                        None,
421                        None,
422                        explicit,
423                        None,
424                        Some(true),
425                    )
426                    .unwrap();
427            } else {
428                clock
429                    .set_time_alert_ns("queued", clock.timestamp_ns(), explicit, None)
430                    .unwrap();
431            }
432
433            let message = rx.recv_timeout(Duration::from_secs(2)).unwrap();
434            clock.cancel_timers();
435            if retire {
436                clock.cancel_default_handler();
437                clock.cancel_callbacks();
438            }
439
440            assert!(message.dispatch());
441            assert_eq!(calls.load(Ordering::Relaxed), 1);
442        }
443    }
444
445    #[derive(Debug)]
446    struct PausingCollectingSender {
447        collector: CollectingSender,
448        paused_tx: mpsc::Sender<()>,
449        release_rx: Mutex<mpsc::Receiver<()>>,
450        pause_once: AtomicBool,
451    }
452
453    impl PausingCollectingSender {
454        fn new(
455            events: Arc<Mutex<Vec<(TimeEvent, UnixNanos)>>>,
456        ) -> (Arc<Self>, mpsc::Receiver<()>, mpsc::Sender<()>) {
457            let (paused_tx, paused_rx) = mpsc::channel();
458            let (release_tx, release_rx) = mpsc::channel();
459            let sender = Arc::new(Self {
460                collector: CollectingSender::new(events),
461                paused_tx,
462                release_rx: Mutex::new(release_rx),
463                pause_once: AtomicBool::new(true),
464            });
465            (sender, paused_rx, release_tx)
466        }
467    }
468
469    impl TimeEventSender for PausingCollectingSender {
470        fn send(&self, message: TimeEventMessage) {
471            self.collector.send(message);
472
473            if self.pause_once.swap(false, Ordering::SeqCst) {
474                self.paused_tx.send(()).expect("timer send should pause");
475                self.release_rx
476                    .lock()
477                    .recv()
478                    .expect("timer send should release");
479            }
480        }
481    }
482
483    fn wait_for_events(
484        events: &Arc<Mutex<Vec<(TimeEvent, UnixNanos)>>>,
485        target: usize,
486        timeout: Duration,
487    ) {
488        wait_until(|| events.lock().len() >= target, timeout);
489    }
490
491    #[rstest]
492    fn test_live_clock_timer_replacement_cancels_previous_task() {
493        let events = Arc::new(Mutex::new(Vec::new()));
494        let (sender, paused_rx, release_tx) = PausingCollectingSender::new(Arc::clone(&events));
495
496        let mut clock = LiveClock::new(Some(sender));
497        clock.register_default_handler(TimeEventCallback::from(|_| {}));
498
499        let fast_interval = DurationNanos::from_millis(10);
500        clock
501            .set_timer_ns("replace", fast_interval, None, None, None, None, None)
502            .unwrap();
503
504        paused_rx
505            .recv_timeout(Duration::from_secs(2))
506            .expect("fast timer send should pause");
507        events.lock().clear();
508
509        let slow_interval = DurationNanos::from_millis(30);
510        clock
511            .set_timer_ns("replace", slow_interval, None, None, None, None, None)
512            .unwrap();
513        release_tx.send(()).expect("fast timer send should release");
514
515        wait_for_events(&events, 3, Duration::from_secs(2));
516
517        let snapshot = events.lock().clone();
518        let diffs: Vec<DurationNanos> = snapshot
519            .array_windows()
520            .map(|[a, b]| b.0.ts_event - a.0.ts_event)
521            .collect();
522
523        assert!(!diffs.is_empty());
524        for diff in diffs {
525            assert_eq!(diff, slow_interval);
526        }
527
528        clock.cancel_timers();
529    }
530
531    #[rstest]
532    fn test_live_clock_time_alert_persists_callback() {
533        let events = Arc::new(Mutex::new(Vec::new()));
534        let sender = Arc::new(CollectingSender::new(Arc::clone(&events)));
535
536        let mut clock = LiveClock::new(Some(sender));
537        clock.register_default_handler(TimeEventCallback::from(|_| {}));
538
539        let now = clock.timestamp_ns();
540        let alert_time = now + DurationNanos::from_mins(1);
541
542        clock
543            .set_time_alert_ns("alert-callback", alert_time, None, None)
544            .unwrap();
545
546        assert!(
547            clock
548                .callbacks
549                .has_any_callback(&Ustr::from("alert-callback"))
550        );
551
552        clock.cancel_timers();
553    }
554
555    #[rstest]
556    fn test_default_live_clock_resolves_sender_after_initialization() {
557        std::thread::spawn(|| {
558            let events = Arc::new(Mutex::new(Vec::new()));
559            let sender = Arc::new(CollectingSender::new(Arc::clone(&events)));
560            let mut clock = LiveClock::default();
561            assert!(clock.sender.is_none());
562
563            replace_time_event_sender(sender);
564            let mut explicit_senderless = LiveClock::new(None);
565            assert!(explicit_senderless.resolve_time_event_sender().is_none());
566
567            let alert_time = clock.timestamp_ns();
568            clock
569                .set_time_alert_ns(
570                    "late-sender",
571                    alert_time,
572                    Some(TimeEventCallback::from(|_| {})),
573                    None,
574                )
575                .unwrap();
576            wait_for_events(&events, 1, Duration::from_secs(2));
577
578            assert!(clock.sender.is_some());
579            let events = events.lock();
580            assert_eq!(events.len(), 1);
581            assert_eq!(events[0].0.name, Ustr::from("late-sender"));
582        })
583        .join()
584        .expect("live clock sender test thread should join");
585    }
586
587    #[rstest]
588    fn test_live_clock_reset_stops_active_timers() {
589        let events = Arc::new(Mutex::new(Vec::new()));
590        let (sender, paused_rx, release_tx) = PausingCollectingSender::new(Arc::clone(&events));
591
592        let mut clock = LiveClock::new(Some(sender.clone()));
593
594        clock
595            .set_timer_ns(
596                "reset-test",
597                DurationNanos::from_millis(15),
598                None,
599                None,
600                Some(TimeEventCallback::from(|_| {})),
601                None,
602                None,
603            )
604            .unwrap();
605
606        paused_rx
607            .recv_timeout(Duration::from_secs(2))
608            .expect("timer send should pause");
609
610        assert_eq!(events.lock().len(), 1);
611        assert_eq!(clock.timer_count(), 1);
612
613        clock.reset();
614        release_tx.send(()).expect("timer send should release");
615
616        // Only the test and clock retain the sender after the canceled task exits
617        wait_until(|| Arc::strong_count(&sender) == 2, Duration::from_secs(2));
618
619        assert_eq!(events.lock().len(), 1);
620        assert_eq!(clock.timer_count(), 0);
621        assert!(clock.timer_names().is_empty());
622        assert!(!clock.callbacks.has_any_callback(&Ustr::from("reset-test")));
623    }
624
625    #[rstest]
626    fn test_live_clock_timer_exists_consistent_after_expiry() {
627        let events = Arc::new(Mutex::new(Vec::new()));
628        let (sender, paused_rx, release_tx) = PausingCollectingSender::new(Arc::clone(&events));
629
630        let mut clock = LiveClock::new(Some(sender));
631        clock.register_default_handler(TimeEventCallback::from(|_| {}));
632
633        let name = Ustr::from("expiring");
634        let interval_ns = DurationNanos::from_millis(10);
635        let start_time = clock.timestamp_ns();
636        let stop_time = start_time + DurationNanos::from_millis(30);
637
638        clock
639            .set_timer_ns(
640                name.as_str(),
641                interval_ns,
642                Some(start_time),
643                Some(stop_time),
644                None,
645                None,
646                None,
647            )
648            .unwrap();
649
650        paused_rx
651            .recv_timeout(Duration::from_secs(2))
652            .expect("timer send should pause");
653
654        assert!(clock.timer_exists(&name));
655        release_tx.send(()).expect("timer send should release");
656
657        // Wait for the timer task to run past its stop time and finish
658        wait_until(|| clock.timer_count() == 0, Duration::from_secs(2));
659
660        // An expired timer is purged only lazily on the next set/cancel call,
661        // so the entry still sits in the map; the introspection surfaces
662        // must nevertheless agree it is gone
663        assert!(clock.timers.contains_key(&name));
664        assert!(!clock.timer_exists(&name));
665        assert_eq!(clock.timer_count(), 0);
666        assert!(clock.timer_names().is_empty());
667        assert!(clock.next_time_ns(name.as_str()).is_none());
668    }
669
670    #[rstest]
671    fn test_live_clock_failed_set_time_alert_ns_preserves_existing_timer() {
672        let events = Arc::new(Mutex::new(Vec::new()));
673        let sender = Arc::new(CollectingSender::new(Arc::clone(&events)));
674
675        // No default handler registered
676        let mut clock = LiveClock::new(Some(sender));
677
678        let now = clock.timestamp_ns();
679        let alert_time = now + DurationNanos::from_mins(1);
680
681        clock
682            .set_time_alert_ns(
683                "alert",
684                alert_time,
685                Some(TimeEventCallback::from(|_| {})),
686                None,
687            )
688            .unwrap();
689        assert_eq!(clock.next_time_ns("alert"), Some(alert_time));
690
691        // Callbacks released (e.g. partial component teardown) while the alert still lives
692        clock.cancel_callbacks();
693
694        // Rescheduling without a callback fails the predicate check; the error
695        // return must not have destroyed the previously scheduled alert
696        let err = clock
697            .set_time_alert_ns("alert", alert_time + DurationNanos::new(1000), None, None)
698            .unwrap_err();
699        assert!(
700            err.to_string().contains("No callbacks provided"),
701            "unexpected error: {err}"
702        );
703        assert!(clock.timer_exists(&Ustr::from("alert")));
704        assert_eq!(clock.next_time_ns("alert"), Some(alert_time));
705
706        clock.cancel_timers();
707    }
708    #[rstest]
709    fn test_live_clock_registers_deadline_schedule_with_default_callback_and_inclusive_stop() {
710        let events = Arc::new(Mutex::new(Vec::new()));
711        let sender = Arc::new(CollectingSender::new(events.clone()));
712        let mut clock = LiveClock::new(Some(sender));
713        clock.register_default_handler(TimeEventCallback::from(|_| {}));
714        let origin = clock.timestamp_ns();
715        let first = origin + DurationNanos::from_millis(200);
716
717        let schedule = Arc::new(
718            CalendarSchedule::new(
719                &origin.to_datetime_utc().to_zoned(jiff::tz::TimeZone::UTC),
720                jiff::Span::new().milliseconds(200),
721            )
722            .unwrap(),
723        );
724        clock
725            .set_timer_schedule("deadline", schedule, Some(first), None, None, None)
726            .unwrap();
727        assert_eq!(clock.next_time_ns("deadline"), Some(first));
728        wait_until(|| clock.timer_count() == 0, Duration::from_secs(2));
729        let recorded = events.lock();
730        assert_eq!(recorded.len(), 1);
731        assert_eq!(recorded[0].0.name, Ustr::from("deadline"));
732        assert_eq!(recorded[0].0.ts_event, first);
733        assert!(recorded[0].0.ts_init >= first);
734        assert_eq!(clock.next_time_ns("deadline"), None);
735    }
736}