1use 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#[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 #[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 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 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 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_until(|| clock.timer_count() == 0, Duration::from_secs(2));
659
660 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 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 clock.cancel_callbacks();
693
694 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}