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`.
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`
59 //! may 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 //! [`sleep`]: crate::time::sleep()
85 //! [`interval`]: crate::time::interval()
86 
87 mod clock;
88 pub(crate) use self::clock::Clock;
89 #[cfg(feature = "test-util")]
90 pub use clock::{advance, pause, resume};
91 
92 pub(crate) mod driver;
93 
94 #[doc(inline)]
95 pub use driver::sleep::{sleep, sleep_until, Sleep};
96 
97 pub mod error;
98 
99 mod instant;
100 pub use self::instant::Instant;
101 
102 mod interval;
103 pub use interval::{interval, interval_at, Interval};
104 
105 mod timeout;
106 #[doc(inline)]
107 pub use timeout::{timeout, timeout_at, Timeout};
108 
109 #[cfg(test)]
110 #[cfg(not(loom))]
111 mod tests;
112 
113 // Re-export for convenience
114 #[doc(no_inline)]
115 pub use std::time::Duration;
116