1use 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#[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 #[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 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 #[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 #[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 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 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}