init Future::select

Signed-off-by: Yoshua Wuyts <yoshuawuyts@gmail.com>

Author: yoshuawuyts

src/future/future.rs

@@ -129,6 +129,40 @@ extension_trait! {
         {
             DelayFuture::new(self, dur)
         }
+
+        #[doc = r#"
+            Waits for either one of several similarly-typed futures to complete.
+
+            Awaits multiple futures simultaneously, returning all results once complete.
+
+            This function will return a new future which awaits for either one of both
+            futures to complete. If multiple futures are completed at the same time,
+            resolution will occur in the order that they have been passed.
+
+            Note that this macro consumes all futures passed, and once a future is
+            completed, all other futures are dropped.
+
+            This macro is only usable inside of async functions, closures, and blocks.
+
+            # Examples
+
+            ```
+            #![feature(async_await)]
+            # futures::executor::block_on(async {
+            use futures::future;
+
+            let a = future::pending();
+            let b = future::ready(1u8);
+            let c = future::ready(2u8);
+
+            let f = a.select(b).select(c);
+            assert_eq!(f.await, 1u8);
+            # });
+            ```
+        "#]
+        fn select(&mut self) -> () {
+            ()
+        }
     }
 
     impl<F: Future + Unpin + ?Sized> Future for Box<F> {

src/future/mod.rs

@@ -10,10 +10,10 @@
 //!
 //! For operating on futures the following macros can be used:
 //!
-//! | Name             | Return signature | When does it return?     |
-//! | ---              | ---              | ---                      |
-//! | `future::join`   | `(T1, T2)`       | Wait for all to complete
-//! | `future::select` | `T`              | Return on first value
+//! | Name               | Return signature | When does it return?     |
+//! | ---                | ---              | ---                      |
+//! | [`future::join!`]  | `(T1, T2)`       | Wait for all to complete
+//! | [`Future::select`] | `T`              | Return on first value
 //!
 //! ## Fallible Futures Concurrency
 //!
@@ -34,12 +34,17 @@
 //! even on futures that return `Result`. Here is an overview of operations that
 //! work on `Result`, and their respective semantics:
 //!
-//! | Name                 | Return signature               | When does it return? |
-//! | ---                  | ---                            | ---                  |
-//! | `future::join`       | `(Result<T, E>, Result<T, E>)` | Wait for all to complete
-//! | `future::try_join`   | `Result<(T1, T2), E>`          | Return on first `Err`, wait for all to complete
-//! | `future::select`     | `Result<T, E>`                 | Return on first value
-//! | `future::try_select` | `Result<T, E>`                 | Return on first `Ok`, reject on last Err
+//! | Name                   | Return signature               | When does it return? |
+//! | ---                    | ---                            | ---                  |
+//! | [`future::join!`]      | `(Result<T, E>, Result<T, E>)` | Wait for all to complete
+//! | [`future::try_join!`]  | `Result<(T1, T2), E>`          | Return on first `Err`, wait for all to complete
+//! | [`Future::select`]     | `Result<T, E>`                 | Return on first value
+//! | [`Future::try_select`] | `Result<T, E>`                 | Return on first `Ok`, reject on last Err
+//!
+//! [`future::join!`]: macro.join.html
+//! [`future::try_join!`]: macro.try_join.html
+//! [`Future::select`]: trait.Future.html#method.select
+//! [`Future::try_select`]: trait.Future.html#method.try_select
 
 #[doc(inline)]
 pub use async_macros::{join, try_join};
@@ -57,9 +62,6 @@ mod ready;
 mod timeout;
 
 cfg_unstable! {
-    #[doc(inline)]
-    pub use async_macros::{select, try_select};
-
     pub use into_future::IntoFuture;
     mod into_future;
 }