add future::Either type to utils (#305)

actix-utils/src/future/either.rs

@@ -0,0 +1,91 @@
+//! A symmetric either future.
+
+use core::{
+    future::Future,
+    pin::Pin,
+    task::{Context, Poll},
+};
+
+use pin_project_lite::pin_project;
+
+pin_project! {
+    /// Combines two different futures that have the same output type.
+    ///
+    /// Construct variants with [`Either::left`] and [`Either::right`].
+    ///
+    /// # Examples
+    /// ```
+    /// use actix_utils::future::{ready, Ready, Either};
+    ///
+    /// # async fn run() {
+    /// let res = Either::<_, Ready<usize>>::left(ready(42));
+    /// assert_eq!(res.await, 42);
+    ///
+    /// let res = Either::<Ready<usize>, _>::right(ready(43));
+    /// assert_eq!(res.await, 43);
+    /// # }
+    /// ```
+    #[project = EitherProj]
+    #[derive(Debug, Clone)]
+    pub enum Either<L, R> {
+        /// A value of type `L`.
+        #[allow(missing_docs)]
+        Left { #[pin] value: L },
+
+        /// A value of type `R`.
+        #[allow(missing_docs)]
+        Right { #[pin] value: R },
+    }
+}
+
+impl<L, R> Either<L, R> {
+    /// Creates new `Either` using left variant.
+    pub fn left(value: L) -> Either<L, R> {
+        Either::Left { value }
+    }
+
+    /// Creates new `Either` using right variant.
+    pub fn right(value: R) -> Either<L, R> {
+        Either::Right { value }
+    }
+}
+
+impl<T> Either<T, T> {
+    /// Unwraps into inner value when left and right have a common type.
+    pub fn into_inner(self) -> T {
+        match self {
+            Either::Left { value } => value,
+            Either::Right { value } => value,
+        }
+    }
+}
+
+impl<L, R> Future for Either<L, R>
+where
+    L: Future,
+    R: Future<Output = L::Output>,
+{
+    type Output = L::Output;
+
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        match self.project() {
+            EitherProj::Left { value } => value.poll(cx),
+            EitherProj::Right { value } => value.poll(cx),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::future::{ready, Ready};
+
+    #[actix_rt::test]
+    async fn test_either() {
+        let res = Either::<_, Ready<usize>>::left(ready(42));
+        assert_eq!(res.await, 42);
+
+        let res = Either::<Ready<usize>, _>::right(ready(43));
+        assert_eq!(res.await, 43);
+    }
+}

actix-utils/src/future/mod.rs

@@ -1,7 +1,9 @@
 //! Asynchronous values.
 
+mod either;
 mod poll_fn;
 mod ready;
 
+pub use self::either::Either;
 pub use self::poll_fn::{poll_fn, PollFn};
 pub use self::ready::{err, ok, ready, Ready};

actix-utils/src/future/poll_fn.rs

@@ -7,7 +7,7 @@ use core::{
     task::{Context, Poll},
 };
 
-/// Create a future driven by the provided function that receives a task context.
+/// Creates a future driven by the provided function that receives a task context.
 pub fn poll_fn<F, T>(f: F) -> PollFn<F>
 where
     F: FnMut(&mut Context<'_>) -> Poll<T>,

actix-utils/src/future/ready.rs

@@ -69,7 +69,7 @@ pub fn ready<T>(val: T) -> Ready<T> {
     Ready { val: Some(val) }
 }
 
-/// Create a future that is immediately ready with a success value.
+/// Creates a future that is immediately ready with a success value.
 ///
 /// # Examples
 /// ```no_run
@@ -84,7 +84,7 @@ pub fn ok<T, E>(val: T) -> Ready<Result<T, E>> {
     Ready { val: Some(Ok(val)) }
 }
 
-/// Create a future that is immediately ready with an error value.
+/// Creates a future that is immediately ready with an error value.
 ///
 /// # Examples
 /// ```no_run