      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
    117
    118
    119

    //! Utilities for tracking time.
    //!
    //! This module provides a number of types for executing code after a set period
    //! of time.
    //!
    //! * `Sleep` is a future that does no work and completes at a specific `Instant`
    //!   in time.
    //!
    //! * `Interval` is a stream yielding a value at a fixed period. It is
    //!   initialized with a `Duration` and repeatedly yields each time the duration
    //!   elapses.
    //!
    //! * `Timeout`: Wraps a future or stream, setting an upper bound to the amount
    //!   of time it is allowed to execute. If the future or stream does not
    //!   complete in time, then it is canceled and an error is returned.
    //!
    //! These types are sufficient for handling a large number of scenarios
    //! involving time.
    //!
    //! These types must be used from within the context of the `Runtime`.
    //!
    //! # Examples
    //!
    //! Wait 100ms and print "100 ms have elapsed"
    //!
    //! ```
    //! use tokio::time::sleep;
    //!
    //! use std::time::Duration;
    //!
    //!
    //! #[tokio::main]
    //! async fn main() {
    //!     sleep(Duration::from_millis(100)).await;
    //!     println!("100 ms have elapsed");
    //! }
    //! ```
    //!
    //! Require that an operation takes no more than 300ms.
    //!
    //! ```
    //! use tokio::time::{timeout, Duration};
    //!
    //! async fn long_future() {
    //!     // do work here
    //! }
    //!
    //! # async fn dox() {
    //! let res = timeout(Duration::from_secs(1), long_future()).await;
    //!
    //! if res.is_err() {
    //!     println!("operation timed out");
    //! }
    //! # }
    //! ```
    //!
    //! A simple example using [`interval`] to execute a task every two seconds.
    //!
    //! The difference between [`interval`] and [`sleep`] is that an
    //! [`interval`] measures the time since the last tick, which means that
    //! `.tick().await` may wait for a shorter time than the duration specified
    //! for the interval if some time has passed between calls to `.tick().await`.
    //!
    //! If the tick in the example below was replaced with [`sleep`], the task
    //! would only be executed once every three seconds, and not every two
    //! seconds.
    //!
    //! ```
    //! use tokio::time;
    //!
    //! async fn task_that_takes_a_second() {
    //!     println!("hello");
    //!     time::sleep(time::Duration::from_secs(1)).await
    //! }
    //!
    //! #[tokio::main]
    //! async fn main() {
    //!     let interval = time::interval(time::Duration::from_secs(2));
    //!     tokio::pin!(interval);
    //!
    //!     for _i in 0..5 {
    //!         interval.as_mut().tick().await;
    //!         task_that_takes_a_second().await;
    //!     }
    //! }
    //! ```
    //!
    //! [`sleep`]: crate::time::sleep()
    //! [`interval`]: crate::time::interval()

    mod clock;
    pub(crate) use self::clock::Clock;
    #[cfg(feature = "test-util")]
    pub use clock::{advance, pause, resume};

    pub(crate) mod driver;

    #[doc(inline)]
    pub use driver::sleep::{sleep, sleep_until, Sleep};

    pub mod error;

    mod instant;
    pub use self::instant::Instant;

    mod interval;
    pub use interval::{interval, interval_at, Interval};

    mod timeout;
    #[doc(inline)]
    pub use timeout::{timeout, timeout_at, Timeout};

    #[cfg(test)]
    #[cfg(not(loom))]
    mod tests;

    // Re-export for convenience
    #[doc(no_inline)]
    pub use std::time::Duration;