timer_lib/
lib.rs

1//! Tokio-based timers for one-shot and recurring async work.
2//!
3//! `timer-lib` provides a handle-first API for scheduling async callbacks and
4//! observing their lifecycle.
5//!
6//! # Overview
7//!
8//! - [`Timer`] runs one-shot or recurring work.
9//! - [`TimerBuilder`] reduces setup boilerplate for common configurations.
10//! - [`TimerRegistry`] tracks timers by ID and supports bulk operations.
11//! - [`TimerEvents`] exposes broadcast lifecycle events.
12//! - [`TimerCompletion`] exposes lossless completed-run delivery.
13//! - [`TimerSnapshot`] and [`RegisteredTimer`] expose introspection-friendly state.
14//!
15//! # Examples
16//!
17//! Start a one-shot timer and wait for it to finish:
18//!
19//! ```rust
20//! use std::time::Duration;
21//! use timer_lib::{Timer, TimerError, TimerFinishReason};
22//!
23//! # let runtime = tokio::runtime::Builder::new_current_thread()
24//! #     .enable_all()
25//! #     .build()
26//! #     .unwrap();
27//! # runtime.block_on(async {
28//! let timer = Timer::new();
29//! timer
30//!     .start_once(Duration::from_millis(10), || async { Ok::<(), TimerError>(()) })
31//!     .await
32//!     .unwrap();
33//!
34//! let outcome = timer.join().await.unwrap();
35//! assert_eq!(outcome.reason, TimerFinishReason::Completed);
36//! # });
37//! ```
38//!
39//! Build a recurring timer:
40//!
41//! ```rust
42//! use std::time::Duration;
43//! use timer_lib::{RecurringSchedule, Timer, TimerError, TimerFinishReason};
44//!
45//! # let runtime = tokio::runtime::Builder::new_current_thread()
46//! #     .enable_all()
47//! #     .build()
48//! #     .unwrap();
49//! # runtime.block_on(async {
50//! let timer = Timer::recurring(RecurringSchedule::new(Duration::from_millis(10)).with_expiration_count(2))
51//!     .start(|| async { Ok::<(), TimerError>(()) })
52//!     .await
53//!     .unwrap();
54//!
55//! let outcome = timer.join().await.unwrap();
56//! assert_eq!(outcome.reason, TimerFinishReason::Completed);
57//! assert_eq!(outcome.statistics.execution_count, 2);
58//! # });
59//! ```
60//!
61//! Observe completion without relying on lossy broadcast delivery:
62//!
63//! ```rust
64//! use std::time::Duration;
65//! use timer_lib::{Timer, TimerError};
66//!
67//! # let runtime = tokio::runtime::Builder::new_current_thread()
68//! #     .enable_all()
69//! #     .build()
70//! #     .unwrap();
71//! # runtime.block_on(async {
72//! let timer = Timer::new();
73//! let mut completion = timer.completion();
74//! let run_id = timer
75//!     .start_once(Duration::from_millis(10), || async { Ok::<(), TimerError>(()) })
76//!     .await
77//!     .unwrap();
78//!
79//! let outcome = completion.wait_for_run(run_id).await.unwrap();
80//! assert_eq!(outcome.run_id, run_id);
81//! # });
82//! ```
83//!
84//! Start a one-shot timer at an absolute deadline:
85//!
86//! ```rust
87//! use std::time::Duration;
88//! use timer_lib::{Timer, TimerError, TimerFinishReason};
89//! use tokio::time::Instant;
90//!
91//! # let runtime = tokio::runtime::Builder::new_current_thread()
92//! #     .enable_all()
93//! #     .build()
94//! #     .unwrap();
95//! # runtime.block_on(async {
96//! let deadline = Instant::now() + Duration::from_millis(10);
97//! let timer = Timer::at(deadline)
98//!     .start(|| async { Ok::<(), TimerError>(()) })
99//!     .await
100//!     .unwrap();
101//!
102//! let outcome = timer.join().await.unwrap();
103//! assert_eq!(outcome.reason, TimerFinishReason::Completed);
104//! # });
105//! ```
106//!
107//! # Runtime
108//!
109//! This crate currently targets Tokio.
110//!
111//! # Errors
112//!
113//! Public operations return [`TimerError`] for invalid configuration or invalid
114//! lifecycle transitions.
115
116pub mod errors;
117pub mod registry;
118pub mod timer;
119
120pub use errors::TimerError;
121pub use registry::TimerRegistry;
122#[deprecated(note = "Use TimerRegistry instead.")]
123pub type TimerManager = TimerRegistry;
124pub use registry::RegisteredTimer;
125#[cfg(feature = "test-util")]
126pub use timer::MockRuntime;
127pub use timer::{
128    RecurringCadence, RecurringSchedule, RetryBackoff, RetryPolicy, Timer, TimerBuilder,
129    TimerCallback, TimerCompletion, TimerEvent, TimerEvents, TimerFinishReason, TimerMetadata,
130    TimerOutcome, TimerSnapshot, TimerState, TimerStatistics,
131};
132
133// Rust guideline compliant 2026-02-21
timer_lib/lib.rs

timer_lib/
lib.rs
