Never error

futures-util/Cargo.toml

@@ -22,6 +22,7 @@ io-compat = ["compat", "tokio-io"]
 bench = []
 nightly = ["futures-core-preview/nightly", "futures-sink-preview/nightly"]
 cfg-target-has-atomic = ["futures-core-preview/cfg-target-has-atomic"]
+never-type = []
 alloc = ["futures-core-preview/alloc", "futures-sink-preview/alloc"]
 
 [dependencies]

futures-util/src/future/mod.rs

@@ -70,6 +70,11 @@ pub use self::inspect::Inspect;
 mod unit_error;
 pub use self::unit_error::UnitError;
 
+#[cfg(feature = "never-type")]
+mod never_error;
+#[cfg(feature = "never-type")]
+pub use self::never_error::NeverError;
+
 // Implementation details
 mod chain;
 pub(crate) use self::chain::Chain;
@@ -530,13 +535,23 @@ pub trait FutureExt: Future {
         Box::pin(self)
     }
 
-    /// Turns a `Future` into a `TryFuture` with `Error = ()`.
+    /// Turns a [`Future<Output = T>`](Future) into a
+    /// [`TryFuture<Ok = T, Error = ()`>](futures_core::future::TryFuture).
     fn unit_error(self) -> UnitError<Self>
         where Self: Sized
     {
         UnitError::new(self)
     }
 
+    #[cfg(feature = "never-type")]
+    /// Turns a [`Future<Output = T>`](Future) into a
+    /// [`TryFuture<Ok = T, Error = !`>](futures_core::future::TryFuture).
+    fn never_error(self) -> NeverError<Self>
+        where Self: Sized
+    {
+        NeverError::new(self)
+    }
+
     /// A convenience for calling `Future::poll` on `Unpin` future types.
     fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>
         where Self: Unpin + Sized

futures-util/src/future/never_error.rs

@@ -0,0 +1,35 @@
+use core::pin::Pin;
+use futures_core::future::{FusedFuture, Future};
+use futures_core::task::{self, Poll};
+use pin_utils::unsafe_pinned;
+
+/// Future for the [`never_error`](super::FutureExt::never_error) combinator.
+#[derive(Debug)]
+#[must_use = "futures do nothing unless polled"]
+pub struct NeverError<Fut> {
+    future: Fut,
+}
+
+impl<Fut> NeverError<Fut> {
+    unsafe_pinned!(future: Fut);
+
+    pub(super) fn new(future: Fut) -> NeverError<Fut> {
+        NeverError { future }
+    }
+}
+
+impl<Fut: Unpin> Unpin for NeverError<Fut> {}
+
+impl<Fut: FusedFuture> FusedFuture for NeverError<Fut> {
+    fn is_terminated(&self) -> bool { self.future.is_terminated() }
+}
+
+impl<Fut, T> Future for NeverError<Fut>
+    where Fut: Future<Output = T>,
+{
+    type Output = Result<T, !>;
+
+    fn poll(self: Pin<&mut Self>, cx: &mut task::Context<'_>) -> Poll<Result<T, !>> {
+        self.future().poll(cx).map(Ok)
+    }
+}

futures-util/src/future/unit_error.rs

@@ -3,9 +3,7 @@ use futures_core::future::{FusedFuture, Future};
 use futures_core::task::{Context, Poll};
 use pin_utils::unsafe_pinned;
 
-/// Future for the `unit_error` combinator, turning a `Future` into a `TryFuture`.
-///
-/// This is created by the `FutureExt::unit_error` method.
+/// Future for the [`unit_error`](super::FutureExt::unit_error) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct UnitError<Fut> {
@@ -15,7 +13,6 @@ pub struct UnitError<Fut> {
 impl<Fut> UnitError<Fut> {
     unsafe_pinned!(future: Fut);
 
-    /// Creates a new UnitError.
     pub(super) fn new(future: Fut) -> UnitError<Fut> {
         UnitError { future }
     }

futures-util/src/lib.rs

@@ -5,6 +5,7 @@
 #![cfg_attr(feature = "alloc", feature(box_into_pin))]
 #![cfg_attr(feature = "std", feature(async_await, await_macro))]
 #![cfg_attr(feature = "cfg-target-has-atomic", feature(cfg_target_has_atomic))]
+#![cfg_attr(feature = "never-type", feature(never_type))]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 #![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)]
@@ -14,6 +15,9 @@
 #[cfg(all(feature = "cfg-target-has-atomic", not(feature = "nightly")))]
 compile_error!("The `cfg-target-has-atomic` feature requires the `nightly` feature as an explicit opt-in to unstable features");
 
+#[cfg(all(feature = "never-type", not(feature = "nightly")))]
+compile_error!("The `never-type` feature requires the `nightly` feature as an explicit opt-in to unstable features");
+
 #[cfg(feature = "alloc")]
 extern crate alloc;
 

futures/Cargo.toml

@@ -42,4 +42,5 @@ default = ["std"]
 compat = ["std", "futures-util-preview/compat"]
 io-compat = ["compat", "futures-util-preview/io-compat"]
 cfg-target-has-atomic = ["futures-core-preview/cfg-target-has-atomic", "futures-util-preview/cfg-target-has-atomic"]
+never-type = ["futures-util-preview/never-type"]
 alloc = ["futures-core-preview/alloc", "futures-sink-preview/alloc", "futures-util-preview/alloc"]

futures/src/lib.rs

@@ -23,6 +23,7 @@
 
 #![feature(futures_api)]
 #![cfg_attr(feature = "cfg-target-has-atomic", feature(cfg_target_has_atomic))]
+#![cfg_attr(feature = "never-type", feature(never_type))]
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -33,6 +34,9 @@
 #[cfg(all(feature = "cfg-target-has-atomic", not(feature = "nightly")))]
 compile_error!("The `cfg-target-has-atomic` feature requires the `nightly` feature as an explicit opt-in to unstable features");
 
+#[cfg(all(feature = "never-type", not(feature = "nightly")))]
+compile_error!("The `never-type` feature requires the `nightly` feature as an explicit opt-in to unstable features");
+
 #[doc(hidden)] pub use futures_util::core_reexport;
 
 #[doc(hidden)] pub use futures_core::future::Future;
@@ -197,7 +201,7 @@ pub mod future {
         OptionFuture,
 
         FutureExt,
-        FlattenStream, Flatten, Fuse, Inspect, IntoStream, Map, Then,
+        FlattenStream, Flatten, Fuse, Inspect, IntoStream, Map, Then, UnitError,
     };
 
     #[cfg(feature = "alloc")]
@@ -230,6 +234,9 @@ pub mod future {
         UnwrapOrElse,
     };
 
+    #[cfg(feature = "never-type")]
+    pub use futures_util::future::NeverError;
+
     #[cfg(feature = "alloc")]
     pub use futures_util::try_future::{
         try_join_all, TryJoinAll,