1 //! Utilities for tracking time. 2 //! 3 //! This module provides a number of types for executing code after a set period 4 //! of time. 5 //! 6 //! * [`Sleep`] is a future that does no work and completes at a specific [`Instant`] 7 //! in time. 8 //! 9 //! * [`Interval`] is a stream yielding a value at a fixed period. It is 10 //! initialized with a [`Duration`] and repeatedly yields each time the duration 11 //! elapses. 12 //! 13 //! * [`Timeout`]: Wraps a future or stream, setting an upper bound to the amount 14 //! of time it is allowed to execute. If the future or stream does not 15 //! complete in time, then it is canceled and an error is returned. 16 //! 17 //! These types are sufficient for handling a large number of scenarios 18 //! involving time. 19 //! 20 //! These types must be used from within the context of the [`Runtime`](crate::runtime::Runtime). 21 //! 22 //! # Examples 23 //! 24 //! Wait 100ms and print "100 ms have elapsed" 25 //! 26 //! ``` 27 //! use std::time::Duration; 28 //! use tokio::time::sleep; 29 //! 30 //! #[tokio::main] 31 //! async fn main() { 32 //! sleep(Duration::from_millis(100)).await; 33 //! println!("100 ms have elapsed"); 34 //! } 35 //! ``` 36 //! 37 //! Require that an operation takes no more than 1s. 38 //! 39 //! ``` 40 //! use tokio::time::{timeout, Duration}; 41 //! 42 //! async fn long_future() { 43 //! // do work here 44 //! } 45 //! 46 //! # async fn dox() { 47 //! let res = timeout(Duration::from_secs(1), long_future()).await; 48 //! 49 //! if res.is_err() { 50 //! println!("operation timed out"); 51 //! } 52 //! # } 53 //! ``` 54 //! 55 //! A simple example using [`interval`] to execute a task every two seconds. 56 //! 57 //! The difference between [`interval`] and [`sleep`] is that an [`interval`] 58 //! measures the time since the last tick, which means that `.tick().await` may 59 //! wait for a shorter time than the duration specified for the interval 60 //! if some time has passed between calls to `.tick().await`. 61 //! 62 //! If the tick in the example below was replaced with [`sleep`], the task 63 //! would only be executed once every three seconds, and not every two 64 //! seconds. 65 //! 66 //! ``` 67 //! use tokio::time; 68 //! 69 //! async fn task_that_takes_a_second() { 70 //! println!("hello"); 71 //! time::sleep(time::Duration::from_secs(1)).await 72 //! } 73 //! 74 //! #[tokio::main] 75 //! async fn main() { 76 //! let mut interval = time::interval(time::Duration::from_secs(2)); 77 //! for _i in 0..5 { 78 //! interval.tick().await; 79 //! task_that_takes_a_second().await; 80 //! } 81 //! } 82 //! ``` 83 //! 84 //! [`interval`]: crate::time::interval() 85 86 mod clock; 87 pub(crate) use self::clock::Clock; 88 #[cfg(feature = "test-util")] 89 pub use clock::{advance, pause, resume}; 90 91 pub(crate) mod driver; 92 93 #[doc(inline)] 94 pub use driver::sleep::{sleep, sleep_until, Sleep}; 95 96 pub mod error; 97 98 mod instant; 99 pub use self::instant::Instant; 100 101 mod interval; 102 pub use interval::{interval, interval_at, Interval, MissedTickBehavior}; 103 104 mod timeout; 105 #[doc(inline)] 106 pub use timeout::{timeout, timeout_at, Timeout}; 107 108 #[cfg(test)] 109 #[cfg(not(loom))] 110 mod tests; 111 112 // Re-export for convenience 113 #[doc(no_inline)] 114 pub use std::time::Duration; 115