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