rust_widgets 2.9.2

// SPDX-FileCopyrightText: Copyright (c) 2026 Mike Li/Mikewolfli/Wei Li(mikewolfli@163.com)
// SPDX-License-Identifier: MIT

//! Runtime timer manager that emits `Event::Timer` into the event queue.
use super::event_queue::EventSender;
#[cfg(not(alloc_frugal))]
use super::types::Event;
#[cfg(not(alloc_frugal))]
use crate::compat::Condvar;
use crate::compat::{format, lock, Box, HashMap, Instant, MiniToString, Mutex, String, Vec};
use crate::core::ObjectId;
use alloc::collections::BinaryHeap;
use alloc::sync::Arc;
use core::cmp::Ordering;
use core::time::Duration;
#[cfg(not(alloc_frugal))]
use std::thread;
struct TimerEntry {
    interval: Duration,
    repeating: bool,
    next_fire: Instant,
    /// How late this timer is allowed to fire, so a coarse timer can be coalesced with
    /// neighbours instead of waking the loop for each one.
    tolerance: Duration,
    /// Identity of the heap entry that currently describes this timer.
    ///
    /// A heap cannot remove an arbitrary element efficiently, so a re-arm or a stop leaves the old
    /// deadline in place and bumps this generation. When the stale entry reaches the top it fails
    /// the generation check and is discarded. This is what makes insert/remove O(log n) without a
    /// second index that could drift from the map.
    generation: u64,
}

/// A scheduled deadline in the timer min-heap (W-P09).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct HeapDeadline {
    fire_at: Instant,
    target: ObjectId,
    id: u32,
    generation: u64,
}

impl Ord for HeapDeadline {
    /// Reversed so `BinaryHeap` (a max-heap) pops the **earliest** deadline first.
    fn cmp(&self, other: &Self) -> Ordering {
        other
            .fire_at
            .cmp(&self.fire_at)
            .then_with(|| other.target.cmp(&self.target))
            .then_with(|| other.id.cmp(&self.id))
            .then_with(|| other.generation.cmp(&self.generation))
    }
}

impl PartialOrd for HeapDeadline {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl TimerEntry {
    /// The moment at which this timer may fire: its deadline plus its tolerance.
    ///
    /// Both the due check and the worker's wake calculation read this one expression; two
    /// spellings of "when does it fire" is what would let the worker park past a coarse
    /// timer's actual deadline.
    fn fire_at(&self) -> Instant {
        // `next_fire` was validated against the clock's ceiling when the timer started, and the
        // tolerance is tens of milliseconds, so the addition cannot overflow in practice.
        self.next_fire + self.tolerance
    }
}

/// How precisely a timer must fire.
///
/// # Why tolerance is a timer property
///
/// A progress-bar repaint and a caret blink tolerate tens of milliseconds of lateness; a
/// countdown or a metronome does not. Delivering both at the clock's resolution makes an idle
/// application wake once per coarse timer, which is the difference between a laptop that naps
/// and one that does not. A tolerance of zero is the precise behaviour every existing caller
/// already got, so this is opt-in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TimerPrecision {
    /// Fire as soon as the deadline passes. The default, and what `start_timer` uses.
    #[default]
    Precise,
    /// Fire within 50 ms of the deadline, allowing the scheduler to batch wake-ups.
    Coarse,
}

impl TimerPrecision {
    /// The tolerated lateness in milliseconds.
    pub const fn tolerance_ms(self) -> u64 {
        match self {
            Self::Precise => 0,
            // A multiple of the conventional 16 ms frame: a coarse timer can be serviced on a
            // frame boundary without being late enough to be visible.
            Self::Coarse => 50,
        }
    }

    /// The tolerance as a `Duration`.
    pub fn tolerance(self) -> Duration {
        Duration::from_millis(self.tolerance_ms())
    }
}

/// Computes `Instant::now() + interval`, returning `Err` instead of panicking when the
/// deadline is not representable on the platform clock.
///
/// `compat::Instant` is `std::time::Instant` on desktop (which has `checked_add`) and a thin
/// wrapper on the frugal profile (which does not), so the two arms meet here rather than
/// branching at the call site.
#[cfg(not(alloc_frugal))]
fn next_fire_deadline(interval: Duration) -> Result<Instant, String> {
    Instant::now()
        .checked_add(interval)
        .ok_or_else(|| format!("timer interval {interval:?} overflows the platform clock"))
}

/// The frugal spelling of [`next_fire_deadline`].
#[cfg(alloc_frugal)]
fn next_fire_deadline(interval: Duration) -> Result<Instant, String> {
    // The frugal `Instant` wrapper has no `checked_add` and its `Add` impl panics on overflow.
    // A monotonic clock on every supported target can represent far more than this ceiling, so
    // rejecting the `Duration::MAX`-scale tail here keeps the `Add` below panic-free without
    // naming a platform-specific limit.
    const CEILING: Duration = Duration::from_secs(10 * 365 * 24 * 3600);
    if interval > CEILING {
        return Err(format!("timer interval {interval:?} overflows the platform clock"));
    }
    Ok(Instant::now() + interval)
}

#[derive(Default)]
struct TimerState {
    timers: HashMap<(ObjectId, u32), TimerEntry>,
    /// Min-heap of deadlines. Stale entries (a re-armed or stopped timer's old generation) are
    /// discarded lazily when they reach the top, so `nearest_deadline` is O(1) amortised instead
    /// of the O(n) scan it used to be (W-P09).
    deadlines: BinaryHeap<HeapDeadline>,
    /// Monotonic source of heap-entry identities.
    next_generation: u64,
    running: bool,
}

impl TimerState {
    /// Whether `deadline` still describes the timer's current schedule.
    fn is_live(&self, deadline: &HeapDeadline) -> bool {
        self.timers
            .get(&(deadline.target, deadline.id))
            .is_some_and(|entry| entry.generation == deadline.generation)
    }

    /// Pops stale heap tops and returns the earliest live fire time, if any.
    ///
    /// Only the threaded worker parks on a deadline; the `mini` pump drains due timers on every
    /// call, so it does not need to ask for the next one.
    #[cfg(not(alloc_frugal))]
    fn discard_stale_and_peek(&mut self) -> Option<Instant> {
        loop {
            let top = *self.deadlines.peek()?;
            if self.is_live(&top) {
                return Some(top.fire_at);
            }
            self.deadlines.pop();
        }
    }

    /// Allocates a generation and records the timer plus its heap entry.
    fn schedule(
        &mut self,
        key: (ObjectId, u32),
        interval: Duration,
        repeating: bool,
        next_fire: Instant,
        tolerance: Duration,
    ) {
        self.next_generation = self.next_generation.wrapping_add(1);
        let generation = self.next_generation;
        let entry = TimerEntry { interval, repeating, next_fire, tolerance, generation };
        // `fire_at` is `next_fire + tolerance`; spelling it here keeps the heap key and the
        // entry's own answer identical by construction.
        let fire_at = entry.fire_at();
        self.timers.insert(key, entry);
        self.deadlines.push(HeapDeadline { fire_at, target: key.0, id: key.1, generation });
    }
}

/// Shared timer state plus the signal the worker waits on (D09-EVT-05).
///
/// # Why the worker no longer polls every 2 ms
///
/// The old worker slept a fixed 2 ms between scans, so an idle `EventLoop` kept a
/// thread waking ~500 times per second and re-locking the timer map even with **zero**
/// timers registered, and the scan cost grew linearly with the number of live timers.
/// The signal below lets the worker block until something actually changes.
///
/// The worker waits on `state`'s monitor under `signal`. Every mutation of the timer
/// set (`start_timer`, `stop_timer`, `stop_timers_for_target`, `clear`, and the drop of
/// the manager's last handle) notifies it, so:
///
/// * with no timers, it parks on the monitor until a timer is added or the manager stops;
/// * with timers, it parks at most until the earliest deadline (`wait_timeout`), so a due
///   timer is not delayed beyond the clock resolution;
/// * a concurrent add/remove/stop interrupts the park immediately rather than waiting
///   out the previous deadline.
///
/// The classic condition-variable pattern is preserved: the flag (`running`) and the
/// set (which timers exist) are only read while holding the same mutex the notifier
/// holds when it changes them, so no wake-up can be lost between a state change and the
/// park.
#[cfg(not(alloc_frugal))]
struct TimerShared {
    state: Mutex<TimerState>,
    signal: Condvar,
    /// Number of worker iterations observed since the manager was created.
    ///
    /// This is a diagnostic counter, and it is what lets a regression test assert that an
    /// idle manager **stops polling** rather than waking on a fixed interval (D09-EVT-05):
    /// a parked worker does not increment it, whereas the old 2 ms scan did. It is kept
    /// uncompiled-out so the timer producer (`Event::timer`) that the event-variant gate
    /// scans for stays in this file's production region; the single relaxed atomic
    /// increment per worker iteration is negligible next to the work the worker does.
    #[allow(dead_code)]
    wake_count: core::sync::atomic::AtomicU64,
}

#[cfg(not(alloc_frugal))]
impl TimerShared {
    /// Wakes the worker after a state change (a timer added, removed, or stopped).
    fn notify(&self) {
        self.signal.notify_one();
    }
}

/// Emits timer events into the event queue for one-shot and repeating timers.
pub struct TimerManager {
    #[cfg(not(alloc_frugal))]
    state: Arc<TimerShared>,
    #[cfg(alloc_frugal)]
    state: Arc<Mutex<TimerState>>,
    #[cfg(not(alloc_frugal))]
    thread_handle: Option<thread::JoinHandle<()>>,
    /// Field kept in `mini` so the shared method bodies compile unchanged.
    ///
    /// `mini` has no timer thread — the caller drives `pump`, so there is no handle to
    /// join. This mirrors the threaded field rather than forking every method, which is
    /// the same profile-parity pattern `EventLoop` uses.
    #[cfg(alloc_frugal)]
    #[cfg_attr(alloc_frugal, allow(dead_code))]
    thread_handle: Option<()>,
    /// Sender used by the mini `pump` to post due timer events.
    #[cfg(alloc_frugal)]
    sender: EventSender,
}

impl TimerManager {
    /// Create a timer manager bound to an event sender.
    #[cfg(not(alloc_frugal))]
    pub fn new(sender: EventSender) -> Self {
        let shared = Arc::new(TimerShared {
            state: Mutex::new(TimerState {
                timers: HashMap::new(),
                running: true,
                ..Default::default()
            }),
            signal: Condvar::new(),
            wake_count: core::sync::atomic::AtomicU64::new(0),
        });

        let worker_shared = Arc::clone(&shared);
        let worker_sender = sender;
        // D09-EVT-05: the worker parks on the condvar instead of polling.
        //
        // * No timers -> `wait` (unbounded) until notified. An idle manager therefore
        //   performs **no** periodic wake-ups.
        // * Timers present -> `wait_timeout` for the nearest deadline, so a short timer
        //   fires as soon as it is due rather than on a fixed 2 ms tick, and a late
        //   notification recomputes the wait rather than delaying the next check.
        let thread_handle = thread::spawn(move || {
            // Scratch buffer reused across every wake. It used to be allocated fresh on each loop
            // iteration, which meant a `Vec` per timer tick even when no timer was due.
            let mut due_events: Vec<(ObjectId, u32)> = Vec::new();
            loop {
                worker_shared.wake_count.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
                due_events.clear();

                {
                    let mut guard = lock(&worker_shared.state);
                    if !guard.running {
                        return;
                    }

                    let now = Instant::now();

                    // W-P09: fire from the min-heap. Each iteration either pops a due timer or
                    // stops at the first deadline still in the future, so the cost is
                    // O(due · log n) rather than O(n) for every wake-up. Stale generations (a
                    // re-armed or stopped timer) are dropped as they reach the top.
                    while let Some(top) = guard.deadlines.peek().copied() {
                        if !guard.is_live(&top) {
                            guard.deadlines.pop();
                            continue;
                        }
                        if now < top.fire_at {
                            break;
                        }
                        guard.deadlines.pop();
                        let key = (top.target, top.id);
                        let (repeating, interval, tolerance) = match guard.timers.get(&key) {
                            Some(entry) => (entry.repeating, entry.interval, entry.tolerance),
                            None => continue,
                        };
                        due_events.push(key);
                        if repeating {
                            // Use Instant::now() + interval to avoid cumulative drift.
                            // If a timer fires late due to load, reset based on current time
                            // so subsequent firings are not delayed by the accumulated drift.
                            let next_fire = Instant::now() + interval;
                            guard.next_generation = guard.next_generation.wrapping_add(1);
                            let generation = guard.next_generation;
                            if let Some(entry) = guard.timers.get_mut(&key) {
                                entry.next_fire = next_fire;
                                entry.generation = generation;
                            }
                            guard.deadlines.push(HeapDeadline {
                                fire_at: next_fire + tolerance,
                                target: key.0,
                                id: key.1,
                                generation,
                            });
                        } else {
                            guard.timers.remove(&key);
                        }
                    }

                    if due_events.is_empty() {
                        // Nothing to emit: park until the nearest deadline, or indefinitely when
                        // no timer is registered. `spurious_wakeup` loops rather than assuming
                        // the notification was the one we expected — the state is re-read under
                        // the lock each time, which is the condition-variable contract.
                        match guard.discard_stale_and_peek() {
                            Some(deadline) => {
                                let wait_for = deadline.saturating_duration_since(Instant::now());
                                // A deadline already in the past collapses to a zero timeout,
                                // which returns immediately; the next loop iteration then fires
                                // it, so no due timer is missed.
                                let _ = worker_shared.signal.wait_timeout(guard, wait_for);
                            }
                            None => {
                                guard = worker_shared
                                    .signal
                                    .wait(guard)
                                    .unwrap_or_else(|poisoned| poisoned.into_inner());
                            }
                        }
                        continue;
                    }
                }

                for (target, id) in due_events.drain(..) {
                    if worker_sender.post(target, Event::timer(id)).is_err() {
                        lock(&worker_shared.state).timers.remove(&(target, id));
                    }
                }
            }
        });

        Self { state: shared, thread_handle: Some(thread_handle) }
    }

    /// Creates a timer manager for `mini`, which has no background thread.
    ///
    /// Timers fire when the caller drives `pump`, so this stores the sender that
    /// `pump` posts through instead of spawning. Single-threaded by design: `mini`
    /// carries no `Send`/`Sync` requirement on the queue.
    #[cfg(alloc_frugal)]
    pub fn new(sender: EventSender) -> Self {
        let state = Arc::new(Mutex::new(TimerState {
            timers: HashMap::new(),
            running: true,
            ..Default::default()
        }));
        Self { state, sender, thread_handle: None }
    }

    /// Acquire the lock on timer state, recovering from poisoning.
    #[cfg(not(alloc_frugal))]
    fn lock_timers(&self) -> crate::compat::MutexGuard<'_, TimerState> {
        lock(&self.state.state)
    }

    /// Acquire the lock on timer state, recovering from poisoning.
    #[cfg(alloc_frugal)]
    fn lock_timers(&self) -> crate::compat::MutexGuard<'_, TimerState> {
        lock(&self.state)
    }

    /// Wake the worker after a state change (D09-EVT-05).
    ///
    /// A no-op under `mini`, which has no worker thread and no condvar; the caller's
    /// `pump` observes the changed set directly.
    #[cfg(not(alloc_frugal))]
    fn notify_worker(&self) {
        self.state.notify();
    }

    /// Wake the worker after a state change (D09-EVT-05).
    #[cfg(alloc_frugal)]
    fn notify_worker(&self) {}

    /// Start or replace a timer for `(target, id)`.
    ///
    /// The timer fires as soon as its deadline passes ([`TimerPrecision::Precise`]). Use
    /// [`Self::start_timer_with_precision`] for a timer that tolerates being serviced slightly
    /// late.
    pub fn start_timer(
        &self,
        target: ObjectId,
        id: u32,
        interval: Duration,
        repeating: bool,
    ) -> Result<(), String> {
        self.start_timer_with_precision(target, id, interval, repeating, TimerPrecision::Precise)
    }

    /// Start or replace a timer with an explicit wake-up precision.
    ///
    /// A [`TimerPrecision::Coarse`] timer may fire up to its tolerance late, which lets the
    /// worker wake once for several timers whose deadlines are close together instead of once
    /// per deadline. Its interval still restarts from the actual fire time, so a coarse timer
    /// does not accumulate drift beyond one tolerance per firing.
    pub fn start_timer_with_precision(
        &self,
        target: ObjectId,
        id: u32,
        interval: Duration,
        repeating: bool,
        precision: TimerPrecision,
    ) -> Result<(), String> {
        if interval.is_zero() {
            return Err("timer interval must be > 0".to_string());
        }

        let next_fire = next_fire_deadline(interval)?;
        let tolerance = precision.tolerance();
        self.lock_timers().schedule((target, id), interval, repeating, next_fire, tolerance);
        // The worker may be parked indefinitely (no timers) or until an older deadline;
        // an added timer can be nearer than that, so it must be woken to recompute.
        self.notify_worker();
        Ok(())
    }

    /// Stop one timer by `(target, id)`.
    pub fn stop_timer(&self, target: ObjectId, id: u32) -> bool {
        let removed = self.lock_timers().timers.remove(&(target, id)).is_some();
        if removed {
            // The stopped timer may have been the nearest deadline; the worker must
            // recompute rather than wake at a deadline that no longer exists.
            self.notify_worker();
        }
        removed
    }

    /// Stop all timers belonging to one target.
    pub fn stop_timers_for_target(&self, target: ObjectId) -> usize {
        let mut guard = self.lock_timers();
        let before = guard.timers.len();
        guard.timers.retain(|(timer_target, _), _| *timer_target != target);
        let removed = before.saturating_sub(guard.timers.len());
        drop(guard);
        if removed > 0 {
            // The nearest deadline may have belonged to this target.
            self.notify_worker();
        }
        removed
    }

    /// Remove all active timers.
    pub fn clear(&self) {
        let had_timers = {
            let mut guard = self.lock_timers();
            let had = !guard.timers.is_empty();
            guard.timers.clear();
            guard.deadlines.clear();
            had
        };
        if had_timers {
            // Waking here turns "cleared" into a prompt recompute instead of the
            // worker sleeping out a deadline for a timer that no longer exists.
            self.notify_worker();
        }
    }

    /// Pump due timers synchronously, posting their `Event::Timer` events.
    ///
    /// Mini mode has no background worker thread, so callers (e.g. an event
    /// loop iteration) invoke this periodically to fire due timers.
    #[cfg(alloc_frugal)]
    pub fn pump(&self) {
        let mut due_events = Vec::new();

        {
            let mut guard = lock(&self.state);
            if !guard.running {
                return;
            }

            let now = Instant::now();
            // W-P09: the same min-heap discipline as the threaded worker. Only the due set has to
            // outlive the lock, so one buffer is enough.
            while let Some(top) = guard.deadlines.peek().copied() {
                if !guard.is_live(&top) {
                    guard.deadlines.pop();
                    continue;
                }
                if now < top.fire_at {
                    break;
                }
                guard.deadlines.pop();
                let key = (top.target, top.id);
                let (repeating, interval, tolerance) = match guard.timers.get(&key) {
                    Some(entry) => (entry.repeating, entry.interval, entry.tolerance),
                    None => continue,
                };
                due_events.push(key);
                if repeating {
                    // Reset based on current time to avoid cumulative drift.
                    let next_fire = Instant::now() + interval;
                    guard.next_generation = guard.next_generation.wrapping_add(1);
                    let generation = guard.next_generation;
                    if let Some(entry) = guard.timers.get_mut(&key) {
                        entry.next_fire = next_fire;
                        entry.generation = generation;
                    }
                    guard.deadlines.push(HeapDeadline {
                        fire_at: next_fire + tolerance,
                        target: key.0,
                        id: key.1,
                        generation,
                    });
                } else {
                    guard.timers.remove(&key);
                }
            }
        }

        for (target, id) in due_events {
            let _ = self.sender.post(target, crate::event::types::Event::timer(id));
        }
    }
}

#[cfg(not(alloc_frugal))]
impl Drop for TimerManager {
    fn drop(&mut self) {
        {
            let mut guard = lock(&self.state.state);
            guard.running = false;
            guard.timers.clear();
        }
        // D09-EVT-05: the worker may be parked in `wait` (no timers) or `wait_timeout`,
        // so clearing `running` is not enough — it has to be woken to observe the flag,
        // or `join` below would block until its next deadline.
        self.state.signal.notify_all();
        // `mini` has no `JoinHandle` here — the field is `Option<()>` to keep this
        // body shared with the threaded arm — so there is nothing to join and no
        // worker to stop beyond clearing `running` above.
        if let Some(handle) = self.thread_handle.take() {
            if let Err(e) = handle.join() {
                log::error!("[timer-manager] Thread join failed: {e:?}");
            }
        }
    }
}

/// Idle task that runs when the event loop has no higher-priority events (BLUE11 R8.5).
///
/// Priority is expressed as a cooldown rather than a queue: the event loop ticks
/// the task every frame with [`IdleTask::tick`], and the callback actually runs
/// only once `threshold_frames` frames have elapsed since it last ran. A large
/// threshold therefore means "only when things are quiet".
pub struct IdleTask {
    /// Caller-assigned identifier. The task machinery never rewrites it, so it
    /// stays whatever `new` was given; it is the only stable way to refer to a
    /// task across ticks.
    pub id: u64,
    /// The work to perform. Called from the event loop with no arguments; it
    /// cannot report failure, so a task that fails must log internally.
    /// Boxed and `Send` because the manager owns tasks across threads.
    pub callback: Box<dyn FnMut() + Send>,
    /// Minimum number of frames between runs. `0` means the callback runs on
    /// every tick, which defeats the point of an idle task but is permitted.
    pub threshold_frames: u32,
    /// Frames elapsed since the last run. Managed by [`IdleTask::tick`]; public
    /// for inspection, but writing it changes when the next run happens.
    pub frames_since_run: u32,
}

impl IdleTask {
    /// Creates a task that has not yet run, so its first run happens after
    /// `threshold_frames` ticks rather than on the first one.
    pub fn new<F>(id: u64, threshold_frames: u32, callback: F) -> Self
    where
        F: FnMut() + Send + 'static,
    {
        Self { id, callback: Box::new(callback), threshold_frames, frames_since_run: 0 }
    }

    /// Called each frame by the event loop. Returns true if the task ran this frame.
    pub fn tick(&mut self) -> bool {
        self.frames_since_run += 1;
        if self.frames_since_run >= self.threshold_frames {
            self.frames_since_run = 0;
            (self.callback)();
            true
        } else {
            false
        }
    }
}

#[cfg(all(test, not(alloc_frugal), not(target_arch = "wasm32")))]
mod tests {
    use super::*;
    use crate::event::EventQueue;
    #[cfg(not(alloc_frugal))]
    use std::thread;
    #[cfg(not(alloc_frugal))]
    use std::time::Instant;

    #[test]
    fn one_shot_timer_emits_single_event() {
        let queue = EventQueue::new();
        let manager = TimerManager::new(queue.sender());
        manager
            .start_timer(7, 11, Duration::from_millis(20), false)
            .expect("one-shot timer should start");

        let deadline = Instant::now() + Duration::from_millis(400);
        let mut hit_count = 0usize;

        while Instant::now() < deadline {
            if let Some((target, event, _priority)) = queue.dequeue() {
                if target == 7 && matches!(event, Event::Timer { id: 11 }) {
                    hit_count += 1;
                }
            }
            thread::sleep(Duration::from_millis(2));
        }

        assert_eq!(hit_count, 1);
    }

    #[test]
    fn repeating_timer_can_be_stopped() {
        let queue = EventQueue::new();
        let manager = TimerManager::new(queue.sender());
        manager
            .start_timer(9, 3, Duration::from_millis(15), true)
            .expect("repeating timer should start");

        let deadline = Instant::now() + Duration::from_millis(300);
        let mut hits = 0usize;

        while Instant::now() < deadline && hits < 2 {
            if let Some((target, event, _priority)) = queue.dequeue() {
                if target == 9 && matches!(event, Event::Timer { id: 3 }) {
                    hits += 1;
                }
            }
            thread::sleep(Duration::from_millis(2));
        }

        assert!(hits >= 2);
        assert!(manager.stop_timer(9, 3));

        let post_stop_deadline = Instant::now() + Duration::from_millis(120);
        let mut post_stop_hits = 0usize;
        while Instant::now() < post_stop_deadline {
            if let Some((target, event, _priority)) = queue.dequeue() {
                if target == 9 && matches!(event, Event::Timer { id: 3 }) {
                    post_stop_hits += 1;
                }
            }
            thread::sleep(Duration::from_millis(2));
        }

        assert_eq!(post_stop_hits, 0);
    }

    /// An interval that overflows the platform clock is rejected as an `Err`, and the existing
    /// timer for the same key is not replaced.
    #[test]
    fn an_unrepresentable_interval_is_rejected_without_replacing() {
        let queue = EventQueue::new();
        let manager = TimerManager::new(queue.sender());
        manager.start_timer(5, 1, Duration::from_millis(10), false).expect("a valid timer starts");

        let result = manager.start_timer(5, 1, Duration::MAX, false);
        assert!(result.is_err(), "an unrepresentable time must be an Err, not a panic");
        assert!(manager.stop_timer(5, 1), "the previous timer must still be present");
    }

    /// D09-EVT-05: with zero timers the worker parks instead of polling every 2 ms.
    ///
    /// # The defect this pins
    ///
    /// The worker slept a fixed 2 ms each round, so an idle `TimerManager` woke ~500
    /// times per second and re-locked the timer map for nothing. The worker now blocks on
    /// the condition variable when the set is empty, so the number of worker iterations
    /// over a quiet window must stay at the handful needed to reach the park — not the
    /// dozens a 2 ms poll produces.
    #[test]
    fn idle_manager_does_not_poll_periodically() {
        let queue = EventQueue::new();
        let manager = TimerManager::new(queue.sender());

        // Give the worker time to take the lock once and park. A 2 ms poll would run
        // ~75 iterations in this window; a parked worker runs a small constant (with
        // headroom for the odd spurious wake-up).
        thread::sleep(Duration::from_millis(150));
        let iterations = manager.state.wake_count.load(core::sync::atomic::Ordering::SeqCst);
        assert!(
            iterations < 20,
            "an idle TimerManager must not poll periodically; it ran {iterations} worker \
             iterations in 150 ms, which is a fixed-interval scan rather than a park"
        );
    }

    /// D09-EVT-05: a short timer is delivered promptly once started from a parked worker.
    ///
    /// The parked worker must be woken by the registration (`notify_one`) and fire at the
    /// deadline, not be stranded until an old timeout elapses.
    #[test]
    fn a_short_timer_started_from_a_parked_worker_is_not_delayed() {
        let queue = EventQueue::new();
        let manager = TimerManager::new(queue.sender());

        // Let the worker reach the unbounded wait first, so the registration must wake it.
        thread::sleep(Duration::from_millis(30));

        let start = Instant::now();
        manager
            .start_timer(21, 5, Duration::from_millis(20), false)
            .expect("a short timer should start");

        let deadline = start + Duration::from_millis(500);
        let mut fired_at = None;
        while Instant::now() < deadline {
            if let Some((target, event, _)) = queue.dequeue() {
                if target == 21 && matches!(event, Event::Timer { id: 5 }) {
                    fired_at = Some(Instant::now());
                    break;
                }
            }
            thread::sleep(Duration::from_millis(2));
        }

        let fired_at = fired_at.expect("the short timer must fire");
        let latency = fired_at.saturating_duration_since(start);
        assert!(
            latency < Duration::from_millis(250),
            "a 20 ms timer must not be delayed beyond tolerance; it took {latency:?} \
             to be observed"
        );
    }

    /// D09-EVT-05: concurrent add/remove/stop from another thread wake the parked worker
    /// and the manager still stops (joins) without deadlock.
    ///
    /// The worker parks with an empty set; the mutations below happen while it is parked,
    /// so each must notify or the worker would either miss the wake or block the final
    /// `drop`/`join`. A watchdog thread turns a deadlock into a test failure rather than a
    /// hung suite.
    #[test]
    fn concurrent_mutations_wake_a_parked_worker_without_deadlock() {
        use std::sync::mpsc::channel;

        let (done_tx, done_rx) = channel();
        let worker = thread::spawn(move || {
            let queue = EventQueue::new();
            let manager = TimerManager::new(queue.sender());

            // Park with no timers.
            thread::sleep(Duration::from_millis(20));

            // Add, clear, and stop while parked; none may block.
            manager.start_timer(1, 1, Duration::from_millis(5), false).unwrap();
            manager.stop_timers_for_target(1);
            manager.start_timer(2, 2, Duration::from_millis(5), true).unwrap();
            assert!(manager.stop_timer(2, 2));
            manager.clear();

            // A timer started after all that must still fire, proving the worker was
            // woken and stayed live rather than exiting on a lost notification.
            manager.start_timer(3, 3, Duration::from_millis(10), false).unwrap();
            let deadline = Instant::now() + Duration::from_millis(500);
            let mut fired = false;
            while Instant::now() < deadline {
                if let Some((target, event, _)) = queue.dequeue() {
                    if target == 3 && matches!(event, Event::Timer { id: 3 }) {
                        fired = true;
                        break;
                    }
                }
                thread::sleep(Duration::from_millis(2));
            }
            assert!(fired, "a timer started after the parked mutations must still fire");

            // Dropping the manager joins the parked worker; this must return.
            drop(manager);
            let _ = done_tx.send(());
        });

        match done_rx.recv_timeout(Duration::from_secs(5)) {
            Ok(()) => {}
            Err(_) => panic!("the timer worker deadlocked on a concurrent mutation or stop"),
        }
        worker.join().expect("the timer worker thread must join cleanly");
    }
}

#[cfg(all(test, alloc_frugal))]
mod mini_tests {
    use super::*;
    use crate::event::EventQueue;

    #[test]
    fn mini_pump_fires_due_timers() {
        let queue = EventQueue::new();
        let manager = TimerManager::new(queue.sender());
        manager
            .start_timer(7, 11, Duration::from_millis(1), false)
            .expect("one-shot timer should start");

        let mut found = false;
        for _ in 0..1000 {
            manager.pump();
            if let Some((target, event, _priority)) = queue.dequeue() {
                if target == 7 && matches!(event, crate::event::types::Event::Timer { id: 11 }) {
                    found = true;
                    break;
                }
            }
            std::thread::sleep(Duration::from_millis(1));
        }

        assert!(found, "mini pump should have posted the due timer event");
    }

    /// A coarse timer tolerates lateness while a precise one does not, and the tolerance
    /// participates in the wake calculation rather than only in the due check.
    #[test]
    fn timer_precision_expresses_tolerated_lateness() {
        assert_eq!(TimerPrecision::Precise.tolerance_ms(), 0);
        assert_eq!(TimerPrecision::Precise.tolerance(), Duration::ZERO);
        assert!(TimerPrecision::Coarse.tolerance_ms() > 0);
        assert_eq!(TimerPrecision::default(), TimerPrecision::Precise);

        let deadline = Instant::now() + Duration::from_millis(10);
        let entry = TimerEntry {
            interval: Duration::from_millis(10),
            repeating: false,
            next_fire: deadline,
            tolerance: TimerPrecision::Coarse.tolerance(),
            generation: 1,
        };
        assert_eq!(entry.fire_at(), deadline + TimerPrecision::Coarse.tolerance());
    }

    /// W-P09: the deadline index reports the earliest timer instead of scanning the map.
    #[test]
    fn the_timer_heap_reports_the_earliest_deadline() {
        let now = Instant::now();
        let mut state = TimerState { running: true, ..Default::default() };
        state.schedule(
            (1, 1),
            Duration::from_millis(100),
            false,
            now + Duration::from_millis(100),
            Duration::ZERO,
        );
        state.schedule(
            (2, 2),
            Duration::from_millis(50),
            false,
            now + Duration::from_millis(50),
            Duration::ZERO,
        );
        state.schedule(
            (3, 3),
            Duration::from_millis(200),
            false,
            now + Duration::from_millis(200),
            Duration::ZERO,
        );
        assert_eq!(state.discard_stale_and_peek(), Some(now + Duration::from_millis(50)));
        assert_eq!(state.timers.len(), 3, "peeking must not consume live entries");
    }

    /// W-P09: re-arming a timer retires the previous deadline without a linear search.
    #[test]
    fn a_rearmed_timer_retires_its_old_deadline() {
        let now = Instant::now();
        let mut state = TimerState { running: true, ..Default::default() };
        state.schedule(
            (1, 1),
            Duration::from_millis(10),
            false,
            now + Duration::from_millis(10),
            Duration::ZERO,
        );
        let first = state.timers.get(&(1, 1)).expect("scheduled").generation;
        state.schedule(
            (1, 1),
            Duration::from_millis(500),
            false,
            now + Duration::from_millis(500),
            Duration::ZERO,
        );
        let second = state.timers.get(&(1, 1)).expect("re-scheduled").generation;
        assert_ne!(first, second, "a re-arm must allocate a new generation");
        assert_eq!(
            state.discard_stale_and_peek(),
            Some(now + Duration::from_millis(500)),
            "the stale earlier deadline must be discarded, not reported"
        );
        assert_eq!(state.deadlines.len(), 1, "the stale entry is gone");
    }

    /// W-P09: stopping a timer leaves no live deadline behind (the heap entry is discarded lazily).
    #[test]
    fn a_stopped_timer_has_no_live_deadline() {
        let now = Instant::now();
        let mut state = TimerState { running: true, ..Default::default() };
        state.schedule(
            (1, 1),
            Duration::from_millis(10),
            false,
            now + Duration::from_millis(10),
            Duration::ZERO,
        );
        state.timers.remove(&(1, 1));
        assert_eq!(state.discard_stale_and_peek(), None);
        assert!(state.deadlines.is_empty(), "the stale entry is discarded on the way out");
    }
}