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//! [`sleep`]: sleep()
86
87mod clock;
88pub(crate) use self::clock::Clock;
89cfg_test_util! {
90 pub use clock::{advance, pause, resume};
91}
92
93pub mod error;
94
95mod instant;
96pub use self::instant::Instant;
97
98mod interval;
99pub use interval::{interval, interval_at, Interval, MissedTickBehavior};
100
101mod sleep;
102pub use sleep::{sleep, sleep_until, Sleep};
103
104mod timeout;
105#[doc(inline)]
106pub use timeout::{timeout, timeout_at, Timeout};
107
108// Re-export for convenience
109#[doc(no_inline)]
110pub use std::time::Duration;
111