async_timer/oneshot/
mod.rs

1//! One-shot Timer
2
3use core::{task, time};
4use core::marker::Unpin;
5use core::future::Future;
6
7///One-shot timer that expires once
8///
9///Trait itself describes `Future` that resolves after `timeout`
10///
11///Most common platforms are supplied via alias [Timer](type.Timer.html)
12///
13///## Common implementations:
14///
15///- Windows uses thread pooled timer
16///- Apple systems uses dispatch source API
17///- Posix compatible `timer_create`, available on major Posix-compliant systems. Depends on availability of `siginfo_t::si_value` method.
18///- Wasm uses Web API `SetTimeout`
19///- Dummy timer is used  when no implementation is available. Panics when used.
20///
21///## Feature `tokio_on`
22///
23///- Linux uses `timerfd_create`, replaces Posix tiemr when enabled.
24///- Other unix systems uses `kqueue`, replaces Apple timer when enabled.
25///
26///```rust, no_run
27/// use async_timer::oneshot::{Oneshot, Timer};
28///
29/// use std::time;
30///
31/// async fn do_stuff() {
32///     let work = Timer::new(time::Duration::from_secs(2));
33///
34///     let before = time::SystemTime::now();
35///     work.await;
36///     let after = time::SystemTime::now();
37///     let diff = after.duration_since(before).unwrap();
38///
39///     assert_eq!(diff.as_secs(), 2);
40/// }
41///
42///```
43pub trait Oneshot: Send + Sync + Unpin + Future<Output=()> {
44    ///Creates new instance without actually starting timer.
45    ///
46    ///Timer should start only on first `Future::poll`
47    fn new(timeout: time::Duration) -> Self;
48
49    ///Returns whether timer is ongoing.
50    ///
51    ///Note that if it returns `false` it doesn't mean that `is_expired` will return `true`
52    ///as initially timer is not armed.
53    fn is_ticking(&self) -> bool;
54
55    ///Returns whether timer has expired.
56    fn is_expired(&self) -> bool;
57
58    ///Cancels ongoing timer, if it is not expired yet.
59    fn cancel(&mut self);
60
61    ///Restarts timer with new timeout value.
62    ///
63    ///If timer is already running, then over-write old value and replaces waker.
64    fn restart(&mut self, timeout: time::Duration, waker: &task::Waker);
65}
66
67mod state;
68
69#[cfg(target_arch = "wasm32")]
70pub mod web;
71#[cfg(windows)]
72pub mod win;
73#[cfg(all(unix, not(any(target_os = "macos", target_os = "ios"))))]
74pub mod posix;
75#[cfg(any(target_os = "macos", target_os = "ios"))]
76pub mod apple;
77#[cfg(all(feature = "tokio_on", any(target_os = "linux", target_os = "android")))]
78pub mod timer_fd;
79#[cfg(all(feature = "tokio_on", any(target_os = "bitrig", target_os = "dragonfly", target_os = "freebsd", target_os = "ios", target_os = "macos", target_os = "netbsd", target_os = "openbsd")))]
80pub mod kqueue;
81pub mod dummy;
82mod extra;
83
84pub use extra::NeverTimer;
85
86#[cfg(all(feature = "tokio_on", any(target_os = "linux", target_os = "android")))]
87pub use timer_fd::TimerFd;
88
89#[cfg(target_arch = "wasm32")]
90///Alias to Web based Timer.
91pub type Timer = web::WebTimer;
92
93#[cfg(windows)]
94///Alias to Windows Timer
95pub type Timer = win::WinTimer;
96
97#[cfg(all(not(feature = "tokio_on"), not(any(target_os = "macos", target_os = "ios")), unix))]
98///Alias to Posix Timer
99pub type Timer = posix::PosixTimer;
100#[cfg(all(feature = "tokio_on", any(target_os = "linux", target_os = "android")))]
101///Alias to Linux `timerfd` Timer
102pub type Timer = timer_fd::TimerFd;
103
104#[cfg(all(not(feature = "tokio_on"), any(target_os = "macos", target_os = "ios")))]
105///Alias to Apple Timer
106pub type Timer = apple::AppleTimer;
107#[cfg(all(feature = "tokio_on", any(target_os = "bitrig", target_os = "dragonfly", target_os = "freebsd", target_os = "ios", target_os = "macos", target_os = "netbsd", target_os = "openbsd")))]
108///Alias to `kqueue` based Timer
109pub type Timer = kqueue::KqueueTimer;
110
111#[cfg(not(any(
112windows, target_arch = "wasm32", unix,
113all(feature = "tokio_on", any(target_os = "bitrig", target_os = "ios", target_os = "macos"))
114)))]
115///Dummy Timer
116pub type Timer = dummy::DummyTimer;
async_timer/oneshot/mod.rs

async_timer/oneshot/
mod.rs
