Skip to main content

aylis_core/
timing.rs

1//! A precisão dos timers ([`TimerPrecision`]) e o esperar até um instante com ela.
2//!
3//! O núcleo não chama o sistema: a plataforma registra como pedir ao sistema o relógio de 1 ms
4//! ([`set_resolution_hook`]; no Windows, o `timeBeginPeriod`, que sem pedido acorda em degraus
5//! de ~15,6 ms). Os pedidos são contados: enquanto um timer `high` ou `exact` estiver ligado, o
6//! relógio fino fica pedido; o último a desligar devolve.
7
8use std::sync::Mutex;
9use std::sync::atomic::{AtomicBool, Ordering};
10use std::time::{Duration, Instant};
11
12/// Quanto um timer pode atrasar.
13#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
14pub enum TimerPrecision {
15    /// O relógio normal do sistema (no Windows, degraus de ~15,6 ms): o que menos gasta CPU e
16    /// bateria. O padrão.
17    #[default]
18    Normal,
19    /// ~1 ms: pede ao sistema o relógio fino enquanto o timer estiver ligado.
20    High,
21    /// Abaixo de 0,1 ms: dorme até ~1,5 ms antes e termina esperando ativo (um núcleo ocupado
22    /// nesse trecho).
23    Exact,
24}
25
26impl crate::prop::PropEnum for TimerPrecision {
27    const NAMES: &'static [&'static str] = &["normal", "high", "exact"];
28    fn from_index(index: usize) -> Option<Self> {
29        [Self::Normal, Self::High, Self::Exact].get(index).copied()
30    }
31    fn index(self) -> usize {
32        self as usize
33    }
34}
35
36/// Quanto antes do prazo o `exact` para de dormir e passa a esperar ativo.
37pub const SPIN: Duration = Duration::from_micros(1500);
38
39struct Resolution {
40    hook: Option<fn(bool)>,
41    requests: usize,
42}
43
44static RESOLUTION: Mutex<Resolution> = Mutex::new(Resolution { hook: None, requests: 0 });
45
46/// A plataforma registra como ligar (`true`) e desligar o relógio fino do sistema.
47pub fn set_resolution_hook(hook: fn(bool)) {
48    if let Ok(mut r) = RESOLUTION.lock() {
49        r.hook = Some(hook);
50        // Timers criados antes de a plataforma começar.
51        if r.requests > 0 {
52            hook(true);
53        }
54    }
55}
56
57/// Pede (`true`) ou devolve o relógio fino; os pedidos são contados.
58pub fn fine_clock(on: bool) {
59    let Ok(mut r) = RESOLUTION.lock() else { return };
60    let before = r.requests;
61    r.requests = if on { before + 1 } else { before.saturating_sub(1) };
62    if let Some(hook) = r.hook
63        && (before == 0) != (r.requests == 0)
64    {
65        hook(r.requests > 0);
66    }
67}
68
69/// Espera até `deadline` com a precisão pedida, numa thread que não é a da tela (o `exact`
70/// ocupa a CPU no fim). Acorda antes se `stop` ligar (quem liga chama `unpark` na thread).
71/// Devolve `false` se parou.
72pub fn park_until(deadline: Instant, precision: TimerPrecision, stop: &AtomicBool) -> bool {
73    let margin = if precision == TimerPrecision::Exact { SPIN } else { Duration::ZERO };
74    loop {
75        if stop.load(Ordering::Relaxed) {
76            return false;
77        }
78        let now = Instant::now();
79        if now + margin >= deadline {
80            break;
81        }
82        std::thread::park_timeout(deadline - margin - now);
83    }
84    while Instant::now() < deadline {
85        std::hint::spin_loop();
86    }
87    !stop.load(Ordering::Relaxed)
88}
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93    use std::sync::atomic::AtomicUsize;
94
95    static CALLS: AtomicUsize = AtomicUsize::new(0);
96
97    fn hook(on: bool) {
98        CALLS.fetch_add(if on { 1 } else { 100 }, Ordering::SeqCst);
99    }
100
101    #[test]
102    fn requests_are_counted_and_exact_is_exact() {
103        set_resolution_hook(hook);
104        fine_clock(true);
105        fine_clock(true);
106        fine_clock(false);
107        assert_eq!(CALLS.load(Ordering::SeqCst), 1, "só o primeiro pedido liga");
108        fine_clock(false);
109        assert_eq!(CALLS.load(Ordering::SeqCst), 101, "o último devolve");
110        // Dentro do `SPIN` (o trecho de dormir depende do relógio fino, que aqui é de mentira).
111        let deadline = Instant::now() + Duration::from_millis(1);
112        assert!(park_until(deadline, TimerPrecision::Exact, &AtomicBool::new(false)));
113        let late = Instant::now() - deadline;
114        assert!(late < Duration::from_millis(1), "atrasou {late:?}");
115    }
116}