1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! One-shot Timer

use core::{task, time};
use core::marker::Unpin;
use core::future::Future;

///One-shot timer that expires once
///
///Trait itself describes `Future` that resolves after `timeout`
///
///Most common platforms are supplied via alias [Timer](type.Timer.html)
///
///## Common implementations:
///
///- Windows uses thread pooled timer
///- Apple systems uses dispatch source API
///- Posix compatible `timer_create`, available on major Posix-compliant systems. Depends on availability of `siginfo_t::si_value` method.
///- Wasm uses Web API `SetTimeout`
///- Dummy timer is used  when no implementation is available. Panics when used.
///
///## Feature `tokio_on`
///
///- Linux uses `timerfd_create`, replaces Posix tiemr when enabled.
///- Other unix systems uses `kqueue`, replaces Apple timer when enabled.
///
///```rust, no_run
/// use async_timer::oneshot::{Oneshot, Timer};
///
/// use std::time;
///
/// async fn do_stuff() {
///     let work = Timer::new(time::Duration::from_secs(2));
///
///     let before = time::SystemTime::now();
///     work.await;
///     let after = time::SystemTime::now();
///     let diff = after.duration_since(before).unwrap();
///
///     assert_eq!(diff.as_secs(), 2);
/// }
///
///```
pub trait Oneshot: Send + Sync + Unpin + Future<Output=()> {
    ///Creates new instance without actually starting timer.
    ///
    ///Timer should start only on first `Future::poll`
    fn new(timeout: time::Duration) -> Self;

    ///Returns whether timer is ongoing.
    ///
    ///Note that if it returns `false` it doesn't mean that `is_expired` will return `true`
    ///as initially timer is not armed.
    fn is_ticking(&self) -> bool;

    ///Returns whether timer has expired.
    fn is_expired(&self) -> bool;

    ///Cancels ongoing timer, if it is not expired yet.
    fn cancel(&mut self);

    ///Restarts timer with new timeout value.
    ///
    ///If timer is already running, then over-write old value and replaces waker.
    fn restart(&mut self, timeout: time::Duration, waker: &task::Waker);
}

mod state;

#[cfg(target_arch = "wasm32")]
pub mod web;
#[cfg(windows)]
pub mod win;
#[cfg(all(unix, not(any(target_os = "macos", target_os = "ios"))))]
pub mod posix;
#[cfg(any(target_os = "macos", target_os = "ios"))]
pub mod apple;
#[cfg(all(feature = "tokio_on", any(target_os = "linux", target_os = "android")))]
pub mod timer_fd;
#[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")))]
pub mod kqueue;
pub mod dummy;
mod extra;

pub use extra::NeverTimer;

#[cfg(all(feature = "tokio_on", any(target_os = "linux", target_os = "android")))]
pub use timer_fd::TimerFd;

#[cfg(target_arch = "wasm32")]
///Alias to Web based Timer.
pub type Timer = web::WebTimer;

#[cfg(windows)]
///Alias to Windows Timer
pub type Timer = win::WinTimer;

#[cfg(all(not(feature = "tokio_on"), not(any(target_os = "macos", target_os = "ios")), unix))]
///Alias to Posix Timer
pub type Timer = posix::PosixTimer;
#[cfg(all(feature = "tokio_on", any(target_os = "linux", target_os = "android")))]
///Alias to Linux `timerfd` Timer
pub type Timer = timer_fd::TimerFd;

#[cfg(all(not(feature = "tokio_on"), any(target_os = "macos", target_os = "ios")))]
///Alias to Apple Timer
pub type Timer = apple::AppleTimer;
#[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")))]
///Alias to `kqueue` based Timer
pub type Timer = kqueue::KqueueTimer;

#[cfg(not(any(
windows, target_arch = "wasm32", unix,
all(feature = "tokio_on", any(target_os = "bitrig", target_os = "ios", target_os = "macos"))
)))]
///Dummy Timer
pub type Timer = dummy::DummyTimer;