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.

tokio-timer/src/deadline.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use Delay;
 
 use futures::{Future, Poll, Async};
@@ -6,21 +8,16 @@ use std::error;
 use std::fmt;
 use std::time::Instant;
 
-/// Allows a given `Future` to execute until the specified deadline.
-///
-/// If the inner future completes before the deadline is reached, then
-/// `Deadline` completes with that value. Otherwise, `Deadline` completes with a
-/// [`DeadlineError`].
-///
-/// [`DeadlineError`]: struct.DeadlineError.html
-#[must_use = "futures do nothing unless polled"]
+#[deprecated(since = "0.2.6", note = "use Timeout instead")]
+#[doc(hidden)]
 #[derive(Debug)]
 pub struct Deadline<T> {
     future: T,
     delay: Delay,
 }
 
-/// Error returned by `Deadline` future.
+#[deprecated(since = "0.2.6", note = "use Timeout instead")]
+#[doc(hidden)]
 #[derive(Debug)]
 pub struct DeadlineError<T>(Kind<T>);