Introduce Timeout and deprecate Deadline. (#558)

This patch introduces `Timeout`. This new type allows setting a timeout
both using a duration and an instant. Given this overlap with
`Deadline`, `Deadline` is deprecated.

In addition to supporting future timeouts, the `Timeout` combinator is
able to provide timeout functionality to streams. It does this by
applying a duration based timeout to each item being yielded.

The main reason for introducing `Timeout` is that a deadline approach
does not work with streams. Since `Timeout` needed to be introduced
anyway, keeping `Deadline` around does not make sense.

src/timer.rs

@@ -10,9 +10,9 @@
 //!   is initialized with a `Duration` and repeatedly yields each time the
 //!   duration elapses.
 //!
-//! * [`Deadline`][Deadline] wraps a future, requiring that it completes before
-//!   a specified `Instant` in time. If the future does not complete in time,
-//!   then it is canceled and an error is returned.
+//! * [`Timeout`][Timeeout]: Wraps a future or stream, setting an upper bound to the
+//!   amount of time it is allowed to execute. If the future or stream does not
+//!   completee in time, then it is canceled and an error is returned.
 //!
 //! * [`DelayQueue`]: A queue where items are returned once the requested delay
 //!   has expired.
@@ -48,7 +48,7 @@
 //! ```
 //!
 //! Require that an operation takes no more than 300ms. Note that this uses the
-//! [`deadline`][ext] function on the [`FutureExt`][ext] trait. This trait is
+//! [`timeout`][ext] function on the [`FutureExt`][ext] trait. This trait is
 //! included in the prelude.
 //!
 //! ```
@@ -64,11 +64,9 @@
 //! }
 //!
 //! # fn main() {
-//! let when = Instant::now()  + Duration::from_millis(300);
-//!
 //! tokio::run({
 //!     long_op()
-//!         .deadline(when)
+//!         .timeout(Duration::from_millis(300))
 //!         .map_err(|e| {
 //!             println!("operation timed out");
 //!         })
@@ -78,18 +76,27 @@
 //!
 //! [runtime]: ../runtime/struct.Runtime.html
 //! [tokio-timer]: https://docs.rs/tokio-timer
-//! [ext]: ../util/trait.FutureExt.html#method.deadline
-//! [Deadline]: struct.Deadline.html
+//! [ext]: ../util/trait.FutureExt.html#method.timeout
+//! [Timeout]: struct.Timeout.html
 //! [Delay]: struct.Delay.html
 //! [Interval]: struct.Interval.html
 //! [`DelayQueue`]: struct.DelayQueue.html
 
 pub use tokio_timer::{
     delay_queue,
-    Deadline,
-    DeadlineError,
     DelayQueue,
     Error,
     Interval,
     Delay,
+    Timeout,
+    timeout,
 };
+
+#[deprecated(since = "0.1.8", note = "use Timeout instead")]
+#[allow(deprecated)]
+#[doc(hidden)]
+pub type Deadline<T> = ::tokio_timer::Deadline<T>;
+#[deprecated(since = "0.1.8", note = "use Timeout instead")]
+#[allow(deprecated)]
+#[doc(hidden)]
+pub type DeadlineError<T> = ::tokio_timer::DeadlineError<T>;

src/util/future.rs

@@ -1,14 +1,16 @@
+#[allow(deprecated)]
 use tokio_timer::Deadline;
+use tokio_timer::Timeout;
 
 use futures::Future;
 
-use std::time::Instant;
+use std::time::{Instant, Duration};
 
 
 /// An extension trait for `Future` that provides a variety of convenient
 /// combinator functions.
 ///
-/// Currently, there only is a [`deadline`] function, but this will increase
+/// Currently, there only is a [`timeout`] function, but this will increase
 /// over time.
 ///
 /// Users are not expected to implement this trait. All types that implement
@@ -17,18 +19,17 @@ use std::time::Instant;
 /// This trait can be imported directly or via the Tokio prelude: `use
 /// tokio::prelude::*`.
 ///
-/// [`deadline`]: #method.deadline
+/// [`timeout`]: #method.timeout
 pub trait FutureExt: Future {
 
-    /// Creates a new future which allows `self` until `deadline`.
+    /// Creates a new future which allows `self` until `timeout`.
     ///
     /// This combinator creates a new future which wraps the receiving future
-    /// with a deadline. The returned future is allowed to execute until it
-    /// completes or `deadline` is reached, whichever happens first.
+    /// with a timeout. The returned future is allowed to execute until it
+    /// completes or `timeout` has elapsed, whichever happens first.
     ///
-    /// If the future completes before `deadline` then the future will resolve
-    /// with that item. Otherwise the future will resolve to an error once
-    /// `deadline` is reached.
+    /// If the future completes before `timeout` then the future will resolve
+    /// with that item. Otherwise the future will resolve to an error.
     ///
     /// # Examples
     ///
@@ -36,7 +37,7 @@ pub trait FutureExt: Future {
     /// # extern crate tokio;
     /// # extern crate futures;
     /// use tokio::prelude::*;
-    /// use std::time::{Duration, Instant};
+    /// use std::time::Duration;
     /// # use futures::future::{self, FutureResult};
     ///
     /// # fn long_future() -> FutureResult<(), ()> {
@@ -45,12 +46,21 @@ pub trait FutureExt: Future {
     /// #
     /// # fn main() {
     /// let future = long_future()
-    ///     .deadline(Instant::now() + Duration::from_secs(1))
+    ///     .timeout(Duration::from_secs(1))
     ///     .map_err(|e| println!("error = {:?}", e));
     ///
     /// tokio::run(future);
     /// # }
     /// ```
+    fn timeout(self, timeout: Duration) -> Timeout<Self>
+    where Self: Sized,
+    {
+        Timeout::new(self, timeout)
+    }
+
+    #[deprecated(since = "0.1.8", note = "use `timeout` instead")]
+    #[allow(deprecated)]
+    #[doc(hidden)]
     fn deadline(self, deadline: Instant) -> Deadline<Self>
     where Self: Sized,
     {