1 #![doc(html_root_url = "https://docs.rs/tokio-timer/0.2.11")]
2 #![deny(missing_docs, warnings, missing_debug_implementations)]
3
4 //! Utilities for tracking time.
5 //!
6 //! This crate provides a number of utilities for working with periods of time:
7 //!
8 //! * [`Delay`]: A future that completes at a specified instant in time.
9 //!
10 //! * [`Interval`] A stream that yields at fixed time intervals.
11 //!
12 //! * [`Throttle`]: Throttle down a stream by enforcing a fixed delay between items.
13 //!
14 //! * [`Timeout`]: Wraps a future or stream, setting an upper bound to the
15 //! amount of time it is allowed to execute. If the future or stream does not
16 //! complete in time, then it is canceled and an error is returned.
17 //!
18 //! * [`DelayQueue`]: A queue where items are returned once the requested delay
19 //! has expired.
20 //!
21 //! These three types are backed by a [`Timer`] instance. In order for
22 //! [`Delay`], [`Interval`], and [`Timeout`] to function, the associated
23 //! [`Timer`] instance must be running on some thread.
24 //!
25 //! [`Delay`]: struct.Delay.html
26 //! [`DelayQueue`]: struct.DelayQueue.html
27 //! [`Throttle`]: throttle/struct.Throttle.html
28 //! [`Timeout`]: struct.Timeout.html
29 //! [`Interval`]: struct.Interval.html
30 //! [`Timer`]: timer/struct.Timer.html
31
32 extern crate tokio_executor;
33
34 extern crate crossbeam_utils;
35 #[macro_use]
36 extern crate futures;
37 extern crate slab;
38
39 pub mod clock;
40 pub mod delay_queue;
41 pub mod throttle;
42 pub mod timeout;
43 pub mod timer;
44
45 mod atomic;
46 mod deadline;
47 mod delay;
48 mod error;
49 mod interval;
50 mod wheel;
51
52 #[deprecated(since = "0.2.6", note = "use Timeout instead")]
53 #[doc(hidden)]
54 #[allow(deprecated)]
55 pub use self::deadline::{Deadline, DeadlineError};
56 pub use self::delay::Delay;
57 #[doc(inline)]
58 pub use self::delay_queue::DelayQueue;
59 pub use self::error::Error;
60 pub use self::interval::Interval;
61 #[doc(inline)]
62 pub use self::timeout::Timeout;
63 pub use self::timer::{with_default, Timer};
64
65 use std::time::{Duration, Instant};
66
67 /// Create a Future that completes in `duration` from now.
sleep(duration: Duration) -> Delay68 pub fn sleep(duration: Duration) -> Delay {
69 Delay::new(Instant::now() + duration)
70 }
71
72 // ===== Internal utils =====
73
74 enum Round {
75 Up,
76 Down,
77 }
78
79 /// Convert a `Duration` to milliseconds, rounding up and saturating at
80 /// `u64::MAX`.
81 ///
82 /// The saturating is fine because `u64::MAX` milliseconds are still many
83 /// million years.
84 #[inline]
ms(duration: Duration, round: Round) -> u6485 fn ms(duration: Duration, round: Round) -> u64 {
86 const NANOS_PER_MILLI: u32 = 1_000_000;
87 const MILLIS_PER_SEC: u64 = 1_000;
88
89 // Round up.
90 let millis = match round {
91 Round::Up => (duration.subsec_nanos() + NANOS_PER_MILLI - 1) / NANOS_PER_MILLI,
92 Round::Down => duration.subsec_nanos() / NANOS_PER_MILLI,
93 };
94
95 duration
96 .as_secs()
97 .saturating_mul(MILLIS_PER_SEC)
98 .saturating_add(millis as u64)
99 }
100