Add feature-gated Never future

Author: cramertj

Cargo.toml

@@ -34,5 +34,6 @@ log = { version = "0.3", default-features = true }
 scoped-tls = { version = "0.1", optional = true }
 
 [features]
+never = []
 use_std = ["scoped-tls"]
 default = ["use_std"]

src/lib.rs

@@ -151,6 +151,7 @@
 
 #![no_std]
 #![deny(missing_docs)]
+#![cfg_attr(feature = "never", feature(never_type, conservative_impl_trait))]
 
 #[macro_use]
 #[cfg(feature = "use_std")]
@@ -179,11 +180,15 @@ mod empty;
 mod failed;
 mod finished;
 mod lazy;
+#[cfg(feature = "never")]
+mod never;
 pub use done::{done, Done};
 pub use empty::{empty, Empty};
 pub use failed::{failed, Failed};
 pub use finished::{finished, Finished};
 pub use lazy::{lazy, Lazy};
+#[cfg(feature = "never")]
+pub use never::{never, Never};
 
 // combinators
 mod and_then;

src/never.rs

@@ -0,0 +1,25 @@
+use {Future, Poll};
+
+/// A future which is never resolved.
+///
+/// This future can be created with the `empty` function.
+pub struct Never {}
+
+/// Creates a future which never resolves, representing a computation that never
+/// finishes.
+///
+/// The returned future will never resolve with a success but is still
+/// susceptible to cancellation. That is, if a callback is scheduled on the
+/// returned future, it is only run once the future is dropped (canceled).
+pub fn never<T, E>() -> impl Future<Item = T, Error = E> + Send + 'static {
+    (Never {}).map(|x| x).map_err(|x| x)
+}
+
+impl Future for Never {
+    type Item = !;
+    type Error = !;
+
+    fn poll(&mut self) -> Poll<!, !> {
+        Poll::NotReady
+    }
+}

tests/all.rs

@@ -1,3 +1,5 @@
+#![cfg_attr(feature = "never", feature(conservative_impl_trait))]
+
 extern crate futures;
 
 use std::sync::mpsc::{channel, TryRecvError};
@@ -80,6 +82,25 @@ fn test_empty() {
     assert_empty(|| empty().then(|a| a));
 }
 
+#[cfg(feature = "never")]
+#[test]
+fn test_never() {
+    fn never() -> impl Future<Item = i32, Error = u32> { futures::never() }
+
+    assert_empty(|| never());
+    assert_empty(|| never().select(never()));
+    assert_empty(|| never().join(never()));
+    assert_empty(|| never().join(f_ok(1)));
+    assert_empty(|| f_ok(1).join(never()));
+    assert_empty(|| never().or_else(move |_| never()));
+    assert_empty(|| never().and_then(move |_| never()));
+    assert_empty(|| f_err(1).or_else(move |_| never()));
+    assert_empty(|| f_ok(1).and_then(move |_| never()));
+    assert_empty(|| never().map(|a| a + 1));
+    assert_empty(|| never().map_err(|a| a + 1));
+    assert_empty(|| never().then(|a| a));
+}
+
 #[test]
 fn test_finished() {
     assert_done(|| finished(1), ok(1));