tokio_osinterval/
lib.rs

1//! `tokio-osinterval` provides [`OsInterval`], an alternative to
2//! [`tokio::time::Interval`] that drives its periodic ticks from the
3//! operating system's native async-capable timer facility instead of
4//! tokio's userspace timer wheel.
5//!
6//! Backends:
7//!
8//! | Platform                         | Backend                                  |
9//! |----------------------------------|------------------------------------------|
10//! | Linux / Android                  | `timerfd_create(CLOCK_MONOTONIC, …)`     |
11//! | macOS / iOS / *BSD               | `kqueue` + `EVFILT_TIMER`                |
12//! | Windows                          | `CreateThreadpoolTimer`                  |
13//! | Other / `--no-default-features`  | `tokio::time::sleep_until` fallback      |
14//!
15//! The public API mirrors [`tokio::time::Interval`] closely so swapping
16//! is mostly an import change.
17//!
18//! # Example
19//!
20//! ```no_run
21//! use std::time::Duration;
22//! use tokio_osinterval::interval;
23//!
24//! # async fn run() {
25//! let mut ticker = interval(Duration::from_millis(100));
26//! for _ in 0..5 {
27//!     ticker.tick().await;
28//!     // do periodic work
29//! }
30//! # }
31//! ```
32//!
33//! # Differences from [`tokio::time::Interval`]
34//!
35//! * Each `OsInterval` owns one kernel timer object (an fd or
36//!   `PTP_TIMER`); creating it requires an active tokio runtime.
37//! * The native backends bypass `tokio::time::pause()` — for tests that
38//!   need a paused clock, build with `default-features = false`.
39//! * Sub-millisecond periods are honored on platforms whose timers
40//!   support them (kqueue with `NOTE_NSECONDS`, timerfd, Windows
41//!   high-resolution timers).
42//!
43//! # Cargo features
44//!
45//! * **`interval`** *(default)* — enables [`OsInterval`] and the
46//!   `interval` / `interval_at` constructors.
47//! * **`os-native`** *(default)* — selects the platform-native backend
48//!   for `OsInterval`. Disable to force the portable
49//!   `tokio::time::sleep_until` fallback. Has no effect unless
50//!   `interval` is also enabled.
51//! * **`periodic`** — enables [`PeriodicInterval`], a stripped-down
52//!   ticker driven by a single kernel-side periodic timer (Linux/BSD
53//!   only).
54//!
55//! `interval` and `periodic` are independent: enable either, both, or
56//! (with `default-features = false`) neither.
57
58#![warn(missing_debug_implementations, missing_docs)]
59#![cfg_attr(docsrs, feature(doc_cfg))]
60
61#[cfg(feature = "interval")]
62mod interval;
63#[cfg(feature = "interval")]
64mod sys;
65
66#[cfg(all(
67    feature = "periodic",
68    any(
69        target_os = "linux",
70        target_os = "android",
71        target_os = "macos",
72        target_os = "ios",
73        target_os = "freebsd",
74        target_os = "netbsd",
75        target_os = "openbsd",
76        target_os = "dragonfly",
77    )
78))]
79mod periodic;
80
81#[cfg(feature = "interval")]
82#[cfg_attr(docsrs, doc(cfg(feature = "interval")))]
83pub use interval::{interval, interval_at, MissedTickBehavior, OsInterval};
84
85#[cfg(all(
86    feature = "periodic",
87    any(
88        target_os = "linux",
89        target_os = "android",
90        target_os = "macos",
91        target_os = "ios",
92        target_os = "freebsd",
93        target_os = "netbsd",
94        target_os = "openbsd",
95        target_os = "dragonfly",
96    )
97))]
98#[cfg_attr(docsrs, doc(cfg(feature = "periodic")))]
99pub use periodic::{Expirations, PeriodicInterval};
tokio_osinterval/lib.rs

tokio_osinterval/
lib.rs
