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 //! * [`Delay`][Delay] is a future that does no work and completes at a specific `Instant`
7 //!   in time.
8 //!
9 //! * [`Interval`][Interval] is a stream yielding a value at a fixed period. It
10 //!   is initialized with a `Duration` and repeatedly yields each time the
11 //!   duration elapses.
12 //!
13 //! * [`Timeout`][Timeout]: Wraps a future or stream, setting an upper bound to the
14 //!   amount 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 //! * [`DelayQueue`]: A queue where items are returned once the requested delay
18 //!   has expired.
19 //!
20 //! These types are sufficient for handling a large number of scenarios
21 //! involving time.
22 //!
23 //! These types must be used from within the context of the
24 //! [`Runtime`][runtime] or a timer context must be setup explicitly. See the
25 //! [`tokio-timer`][tokio-timer] crate for more details on how to setup a timer
26 //! context.
27 //!
28 //! # Examples
29 //!
30 //! Wait 100ms and print "Hello World!"
31 //!
32 //! ```
33 //! use tokio::prelude::*;
34 //! use tokio::timer::Delay;
35 //!
36 //! use std::time::{Duration, Instant};
37 //!
38 //! let when = Instant::now() + Duration::from_millis(100);
39 //!
40 //! tokio::run({
41 //!     Delay::new(when)
42 //!         .map_err(|e| panic!("timer failed; err={:?}", e))
43 //!         .and_then(|_| {
44 //!             println!("Hello world!");
45 //!             Ok(())
46 //!         })
47 //! })
48 //! ```
49 //!
50 //! Require that an operation takes no more than 300ms. Note that this uses the
51 //! [`timeout`][ext] function on the [`FutureExt`][ext] trait. This trait is
52 //! included in the prelude.
53 //!
54 //! ```
55 //! # extern crate futures;
56 //! # extern crate tokio;
57 //! use tokio::prelude::*;
58 //!
59 //! use std::time::{Duration, Instant};
60 //!
61 //! fn long_op() -> Box<Future<Item = (), Error = ()> + Send> {
62 //!     // ...
63 //! # Box::new(futures::future::ok(()))
64 //! }
65 //!
66 //! # fn main() {
67 //! tokio::run({
68 //!     long_op()
69 //!         .timeout(Duration::from_millis(300))
70 //!         .map_err(|e| {
71 //!             println!("operation timed out");
72 //!         })
73 //! })
74 //! # }
75 //! ```
76 //!
77 //! [runtime]: ../runtime/struct.Runtime.html
78 //! [tokio-timer]: https://docs.rs/tokio-timer
79 //! [ext]: ../util/trait.FutureExt.html#method.timeout
80 //! [Timeout]: struct.Timeout.html
81 //! [Delay]: struct.Delay.html
82 //! [Interval]: struct.Interval.html
83 //! [`DelayQueue`]: struct.DelayQueue.html
84 
85 pub use tokio_timer::{delay_queue, timeout, Delay, DelayQueue, Error, Interval, Timeout};
86 
87 #[deprecated(since = "0.1.8", note = "use Timeout instead")]
88 #[allow(deprecated)]
89 #[doc(hidden)]
90 pub type Deadline<T> = ::tokio_timer::Deadline<T>;
91 #[deprecated(since = "0.1.8", note = "use Timeout instead")]
92 #[allow(deprecated)]
93 #[doc(hidden)]
94 pub type DeadlineError<T> = ::tokio_timer::DeadlineError<T>;
95