use crate::Property;
use std::{
collections::BTreeMap,
fmt,
rc::Rc,
sync::atomic::{AtomicU64, Ordering},
time::{Duration, Instant},
};
#[doc(hidden)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TimerCommand {
Start,
Stop,
Restart,
}
impl TimerCommand {
pub fn parse(name: &str) -> Option<Self> {
Some(match name {
"start" => Self::Start,
"stop" => Self::Stop,
"restart" => Self::Restart,
_ => return None,
})
}
}
#[doc(hidden)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct TimerConfig {
interval: Duration,
repeat: bool,
triggered_on_start: bool,
}
impl TimerConfig {
pub fn new(milliseconds: i64, repeat: bool, triggered_on_start: bool) -> Option<Self> {
(milliseconds > 0).then(|| Self {
interval: Duration::from_millis(milliseconds.min(i64::from(u32::MAX)) as u64),
repeat,
triggered_on_start,
})
}
pub fn try_read<E>(
running: impl FnOnce() -> Result<bool, E>,
interval: impl FnOnce() -> Result<i64, E>,
repeat: impl FnOnce() -> Result<bool, E>,
immediate: impl FnOnce() -> Result<bool, E>,
) -> Result<Option<Self>, E> {
if !running()? {
return Ok(None);
}
Ok(Self::new(interval()?, repeat()?, immediate()?))
}
pub fn read(
running: impl FnOnce() -> bool,
interval: impl FnOnce() -> i64,
repeat: impl FnOnce() -> bool,
immediate: impl FnOnce() -> bool,
) -> Option<Self> {
Self::try_read(
|| Ok::<_, std::convert::Infallible>(running()),
|| Ok(interval()),
|| Ok(repeat()),
|| Ok(immediate()),
)
.unwrap_or_else(|error| match error {})
}
}
#[doc(hidden)]
pub struct TimerSlot {
key: u64,
revision: Property<u64>,
}
impl Default for TimerSlot {
#[expect(
clippy::expect_used,
reason = "timer IDs must stay unique even if the counter reaches its limit"
)]
fn default() -> Self {
static NEXT: AtomicU64 = AtomicU64::new(1);
let key = NEXT
.try_update(Ordering::Relaxed, Ordering::Relaxed, |key| {
key.checked_add(1)
})
.expect("timer identities exhausted");
Self {
key,
revision: Property::default(),
}
}
}
impl TimerSlot {
pub fn try_command<E>(
&self,
command: TimerCommand,
running: impl FnOnce() -> Result<bool, E>,
set_running: impl FnOnce(bool) -> Result<(), E>,
) -> Result<(), E> {
match command {
TimerCommand::Start if running()? => Ok(()),
TimerCommand::Start | TimerCommand::Restart => {
self.restart();
set_running(true)
}
TimerCommand::Stop => set_running(false),
}
}
pub fn command(
&self,
command: TimerCommand,
running: impl FnOnce() -> bool,
set_running: impl FnOnce(bool),
) {
self.try_command(
command,
|| Ok::<_, std::convert::Infallible>(running()),
|value| {
set_running(value);
Ok(())
},
)
.unwrap_or_else(|error| match error {})
}
pub fn revision(&self) -> u64 {
self.revision.get(|| 0)
}
#[expect(
clippy::expect_used,
reason = "timer revision IDs must stay unique even if the counter reaches its limit"
)]
pub fn restart(&self) {
self.revision.set(
self.revision()
.checked_add(1)
.expect("timer revision exhausted"),
);
}
pub fn try_tick_is_current<E>(
&self,
tick: &TimerTick,
config: impl FnOnce() -> Result<Option<TimerConfig>, E>,
) -> Result<bool, E> {
crate::property::watch_reads(|reads| {
Ok(self.revision() == tick.revision
&& config()? == Some(tick.config)
&& !reads.changed())
})
}
pub fn tick_is_current(
&self,
tick: &TimerTick,
config: impl FnOnce() -> Option<TimerConfig>,
) -> bool {
self.try_tick_is_current(tick, || Ok::<_, std::convert::Infallible>(config()))
.unwrap_or_else(|error| match error {})
}
pub fn try_deliver<E>(
&self,
tick: &TimerTick,
config: impl FnOnce() -> Result<Option<TimerConfig>, E>,
stop: impl FnOnce() -> Result<(), E>,
triggered: impl FnOnce() -> Result<(), E>,
) -> Result<bool, E> {
if !self.try_tick_is_current(tick, config)? {
return Ok(false);
}
if tick.completed {
stop()?;
}
triggered()?;
Ok(true)
}
pub fn deliver(
&self,
tick: &TimerTick,
config: impl FnOnce() -> Option<TimerConfig>,
stop: impl FnOnce(),
triggered: impl FnOnce(),
) -> bool {
self.try_deliver(
tick,
|| Ok::<_, std::convert::Infallible>(config()),
|| {
stop();
Ok(())
},
|| {
triggered();
Ok(())
},
)
.unwrap_or_else(|error| match error {})
}
pub fn register(
&self,
config: TimerConfig,
deliver: impl Fn(TimerTick) -> bool + 'static,
) -> TimerRegistration {
TimerRegistration {
key: self.key,
config,
revision: self.revision(),
deliver: Rc::new(deliver),
}
}
}
#[doc(hidden)]
#[derive(Clone)]
pub struct TimerRegistration {
key: u64,
revision: u64,
config: TimerConfig,
deliver: Rc<dyn Fn(TimerTick) -> bool>,
}
impl fmt::Debug for TimerRegistration {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("TimerRegistration")
.field("key", &self.key)
.field("revision", &self.revision)
.field("config", &self.config)
.finish()
}
}
impl PartialEq for TimerRegistration {
fn eq(&self, other: &Self) -> bool {
self.key == other.key && self.revision == other.revision && self.config == other.config
}
}
#[doc(hidden)]
pub struct TimerTick {
pub config: TimerConfig,
pub revision: u64,
pub completed: bool,
}
#[doc(hidden)]
pub struct TimerDelivery {
registration: TimerRegistration,
completed: bool,
}
impl TimerDelivery {
pub fn fire(self) -> bool {
(self.registration.deliver)(TimerTick {
config: self.registration.config,
revision: self.registration.revision,
completed: self.completed,
})
}
}
struct Entry {
registration: TimerRegistration,
deadline: Option<Instant>,
initial_trigger: bool,
}
#[doc(hidden)]
#[derive(Default)]
pub struct TimerQueue {
entries: BTreeMap<u64, Entry>,
}
impl TimerQueue {
pub fn sync<'a>(
&mut self,
now: Instant,
registrations: impl IntoIterator<Item = &'a TimerRegistration>,
) {
let mut previous = std::mem::take(&mut self.entries);
for registration in registrations {
let old = previous.remove(®istration.key);
let entry =
if let Some(old) = old.as_ref().filter(|old| old.registration == *registration) {
Entry {
registration: registration.clone(),
deadline: old.deadline,
initial_trigger: old.initial_trigger,
}
} else {
let initial_trigger = registration.config.triggered_on_start
&& old.is_none_or(|old| old.registration.revision != registration.revision);
let deadline = if initial_trigger {
Some(now)
} else {
now.checked_add(registration.config.interval)
};
Entry {
registration: registration.clone(),
deadline,
initial_trigger,
}
};
self.entries.insert(registration.key, entry);
}
}
pub fn deadline(&self) -> Option<Instant> {
self.entries
.values()
.filter_map(|entry| entry.deadline)
.min()
}
pub fn next_due(&mut self, now: Instant) -> Option<TimerDelivery> {
let entry = self
.entries
.values_mut()
.filter(|entry| entry.deadline.is_some_and(|deadline| deadline <= now))
.min_by_key(|entry| entry.deadline)?;
let deadline = entry.deadline?;
let config = entry.registration.config;
let completed = !entry.initial_trigger && !config.repeat;
entry.initial_trigger = false;
entry.deadline = if completed {
None
} else {
let remainder =
(now.duration_since(deadline).as_nanos() % config.interval.as_nanos()) as u64;
now.checked_add(config.interval - Duration::from_nanos(remainder))
};
Some(TimerDelivery {
registration: entry.registration.clone(),
completed,
})
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::cell::RefCell;
#[test]
fn late_periods_coalesce_without_moving_the_original_cadence() {
let slot = TimerSlot::default();
let start = Instant::now();
let at = |millis| start + Duration::from_millis(millis);
let config = TimerConfig::new(100, true, false).unwrap();
let registration = slot.register(config, |tick| !tick.completed);
let mut queue = TimerQueue::default();
queue.sync(start, [®istration]);
assert!(queue.next_due(at(352)).unwrap().fire());
assert!(queue.next_due(at(352)).is_none());
assert_eq!(queue.deadline(), Some(at(400)));
queue.sync(at(365), [®istration]);
assert_eq!(queue.deadline(), Some(at(400)));
let faster = slot.register(TimerConfig::new(30, true, false).unwrap(), |_| true);
queue.sync(at(372), [&faster]);
assert_eq!(queue.deadline(), Some(at(402)));
queue.sync(at(373), []);
assert!(queue.deadline().is_none());
queue.sync(at(800), [&faster]);
assert_eq!(queue.deadline(), Some(at(830)));
}
#[test]
fn immediate_single_shot_delivers_start_then_completion() {
let slot = TimerSlot::default();
let start = Instant::now();
let config = TimerConfig::new(80, false, true).unwrap();
let completed = Rc::new(RefCell::new(Vec::new()));
let phases = completed.clone();
let registration = slot.register(config, move |tick| {
phases.borrow_mut().push(tick.completed);
true
});
let mut queue = TimerQueue::default();
queue.sync(start, [®istration]);
assert!(queue.next_due(start).unwrap().fire());
assert!(
queue
.next_due(start + Duration::from_millis(80))
.unwrap()
.fire()
);
assert_eq!(&*completed.borrow(), &[false, true]);
queue.sync(start + Duration::from_millis(81), [®istration]);
assert!(queue.deadline().is_none());
}
}