Adding upstream version 1.64.0+dfsg1.upstream/1.64.0+dfsg1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

7 files changed, 680 insertions, 0 deletions

diff --git a/vendor/futures-util/src/async_await/join_mod.rs b/vendor/futures-util/src/async_await/join_mod.rs
new file mode 100644
index 000000000..28f3b232e
--- /dev/null
+++ b/vendor/futures-util/src/async_await/join_mod.rs
@@ -0,0 +1,110 @@
+//! The `join` macro.
+
+macro_rules! document_join_macro {
+    ($join:item $try_join:item) => {
+        /// Polls multiple futures simultaneously, returning a tuple
+        /// of all results once complete.
+        ///
+        /// While `join!(a, b)` is similar to `(a.await, b.await)`,
+        /// `join!` polls both futures concurrently and therefore is more efficient.
+        ///
+        /// This macro is only usable inside of async functions, closures, and blocks.
+        /// It is also gated behind the `async-await` feature of this library, which is
+        /// activated by default.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::join;
+        ///
+        /// let a = async { 1 };
+        /// let b = async { 2 };
+        /// assert_eq!(join!(a, b), (1, 2));
+        ///
+        /// // `join!` is variadic, so you can pass any number of futures
+        /// let c = async { 3 };
+        /// let d = async { 4 };
+        /// let e = async { 5 };
+        /// assert_eq!(join!(c, d, e), (3, 4, 5));
+        /// # });
+        /// ```
+        $join
+
+        /// Polls multiple futures simultaneously, resolving to a [`Result`] containing
+        /// either a tuple of the successful outputs or an error.
+        ///
+        /// `try_join!` is similar to [`join!`], but completes immediately if any of
+        /// the futures return an error.
+        ///
+        /// This macro is only usable inside of async functions, closures, and blocks.
+        /// It is also gated behind the `async-await` feature of this library, which is
+        /// activated by default.
+        ///
+        /// # Examples
+        ///
+        /// When used on multiple futures that return `Ok`, `try_join!` will return
+        /// `Ok` of a tuple of the values:
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::try_join;
+        ///
+        /// let a = async { Ok::<i32, i32>(1) };
+        /// let b = async { Ok::<i32, i32>(2) };
+        /// assert_eq!(try_join!(a, b), Ok((1, 2)));
+        ///
+        /// // `try_join!` is variadic, so you can pass any number of futures
+        /// let c = async { Ok::<i32, i32>(3) };
+        /// let d = async { Ok::<i32, i32>(4) };
+        /// let e = async { Ok::<i32, i32>(5) };
+        /// assert_eq!(try_join!(c, d, e), Ok((3, 4, 5)));
+        /// # });
+        /// ```
+        ///
+        /// If one of the futures resolves to an error, `try_join!` will return
+        /// that error:
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::try_join;
+        ///
+        /// let a = async { Ok::<i32, i32>(1) };
+        /// let b = async { Err::<u64, i32>(2) };
+        ///
+        /// assert_eq!(try_join!(a, b), Err(2));
+        /// # });
+        /// ```
+        $try_join
+    }
+}
+
+#[allow(unreachable_pub)]
+#[doc(hidden)]
+pub use futures_macro::join_internal;
+
+#[allow(unreachable_pub)]
+#[doc(hidden)]
+pub use futures_macro::try_join_internal;
+
+document_join_macro! {
+    #[macro_export]
+    macro_rules! join {
+        ($($tokens:tt)*) => {{
+            use $crate::__private as __futures_crate;
+            $crate::join_internal! {
+                $( $tokens )*
+            }
+        }}
+    }
+
+    #[macro_export]
+    macro_rules! try_join {
+        ($($tokens:tt)*) => {{
+            use $crate::__private as __futures_crate;
+            $crate::try_join_internal! {
+                $( $tokens )*
+            }
+        }}
+    }
+}
diff --git a/vendor/futures-util/src/async_await/mod.rs b/vendor/futures-util/src/async_await/mod.rs
new file mode 100644
index 000000000..7276da227
--- /dev/null
+++ b/vendor/futures-util/src/async_await/mod.rs
@@ -0,0 +1,58 @@
+//! Await
+//!
+//! This module contains a number of functions and combinators for working
+//! with `async`/`await` code.
+
+use futures_core::future::{FusedFuture, Future};
+use futures_core::stream::{FusedStream, Stream};
+
+#[macro_use]
+mod poll;
+#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/64762
+pub use self::poll::*;
+
+#[macro_use]
+mod pending;
+#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/64762
+pub use self::pending::*;
+
+// Primary export is a macro
+#[cfg(feature = "async-await-macro")]
+mod join_mod;
+#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/64762
+#[cfg(feature = "async-await-macro")]
+pub use self::join_mod::*;
+
+// Primary export is a macro
+#[cfg(feature = "async-await-macro")]
+mod select_mod;
+#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/64762
+#[cfg(feature = "async-await-macro")]
+pub use self::select_mod::*;
+
+// Primary export is a macro
+#[cfg(feature = "async-await-macro")]
+mod stream_select_mod;
+#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/64762
+#[cfg(feature = "async-await-macro")]
+pub use self::stream_select_mod::*;
+
+#[cfg(feature = "std")]
+#[cfg(feature = "async-await-macro")]
+mod random;
+#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/64762
+#[cfg(feature = "std")]
+#[cfg(feature = "async-await-macro")]
+pub use self::random::*;
+
+#[doc(hidden)]
+#[inline(always)]
+pub fn assert_unpin<T: Unpin>(_: &T) {}
+
+#[doc(hidden)]
+#[inline(always)]
+pub fn assert_fused_future<T: Future + FusedFuture>(_: &T) {}
+
+#[doc(hidden)]
+#[inline(always)]
+pub fn assert_fused_stream<T: Stream + FusedStream>(_: &T) {}
diff --git a/vendor/futures-util/src/async_await/pending.rs b/vendor/futures-util/src/async_await/pending.rs
new file mode 100644
index 000000000..5d7a43181
--- /dev/null
+++ b/vendor/futures-util/src/async_await/pending.rs
@@ -0,0 +1,43 @@
+use core::pin::Pin;
+use futures_core::future::Future;
+use futures_core::task::{Context, Poll};
+
+/// A macro which yields to the event loop once.
+///
+/// This is equivalent to returning [`Poll::Pending`](futures_core::task::Poll)
+/// from a [`Future::poll`](futures_core::future::Future::poll) implementation.
+/// Similarly, when using this macro, it must be ensured that [`wake`](std::task::Waker::wake)
+/// is called somewhere when further progress can be made.
+///
+/// This macro is only usable inside of async functions, closures, and blocks.
+/// It is also gated behind the `async-await` feature of this library, which is
+/// activated by default.
+#[macro_export]
+macro_rules! pending {
+    () => {
+        $crate::__private::async_await::pending_once().await
+    };
+}
+
+#[doc(hidden)]
+pub fn pending_once() -> PendingOnce {
+    PendingOnce { is_ready: false }
+}
+
+#[allow(missing_debug_implementations)]
+#[doc(hidden)]
+pub struct PendingOnce {
+    is_ready: bool,
+}
+
+impl Future for PendingOnce {
+    type Output = ();
+    fn poll(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Self::Output> {
+        if self.is_ready {
+            Poll::Ready(())
+        } else {
+            self.is_ready = true;
+            Poll::Pending
+        }
+    }
+}
diff --git a/vendor/futures-util/src/async_await/poll.rs b/vendor/futures-util/src/async_await/poll.rs
new file mode 100644
index 000000000..b62f45a94
--- /dev/null
+++ b/vendor/futures-util/src/async_await/poll.rs
@@ -0,0 +1,39 @@
+use crate::future::FutureExt;
+use core::pin::Pin;
+use futures_core::future::Future;
+use futures_core::task::{Context, Poll};
+
+/// A macro which returns the result of polling a future once within the
+/// current `async` context.
+///
+/// This macro is only usable inside of `async` functions, closures, and blocks.
+/// It is also gated behind the `async-await` feature of this library, which is
+/// activated by default.
+///
+/// If you need the result of polling a [`Stream`](crate::stream::Stream),
+/// you can use this macro with the [`next`](crate::stream::StreamExt::next) method:
+/// `poll!(stream.next())`.
+#[macro_export]
+macro_rules! poll {
+    ($x:expr $(,)?) => {
+        $crate::__private::async_await::poll($x).await
+    };
+}
+
+#[doc(hidden)]
+pub fn poll<F: Future + Unpin>(future: F) -> PollOnce<F> {
+    PollOnce { future }
+}
+
+#[allow(missing_debug_implementations)]
+#[doc(hidden)]
+pub struct PollOnce<F: Future + Unpin> {
+    future: F,
+}
+
+impl<F: Future + Unpin> Future for PollOnce<F> {
+    type Output = Poll<F::Output>;
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        Poll::Ready(self.future.poll_unpin(cx))
+    }
+}
diff --git a/vendor/futures-util/src/async_await/random.rs b/vendor/futures-util/src/async_await/random.rs
new file mode 100644
index 000000000..4f8c7254b
--- /dev/null
+++ b/vendor/futures-util/src/async_await/random.rs
@@ -0,0 +1,54 @@
+use std::{
+    cell::Cell,
+    collections::hash_map::DefaultHasher,
+    hash::Hasher,
+    num::Wrapping,
+    sync::atomic::{AtomicUsize, Ordering},
+};
+
+// Based on [Fisher–Yates shuffle].
+//
+// [Fisher–Yates shuffle]: https://en.wikipedia.org/wiki/Fisher–Yates_shuffle
+#[doc(hidden)]
+pub fn shuffle<T>(slice: &mut [T]) {
+    for i in (1..slice.len()).rev() {
+        slice.swap(i, gen_index(i + 1));
+    }
+}
+
+/// Return a value from `0..n`.
+fn gen_index(n: usize) -> usize {
+    (random() % n as u64) as usize
+}
+
+/// Pseudorandom number generator based on [xorshift*].
+///
+/// [xorshift*]: https://en.wikipedia.org/wiki/Xorshift#xorshift*
+fn random() -> u64 {
+    thread_local! {
+        static RNG: Cell<Wrapping<u64>> = Cell::new(Wrapping(prng_seed()));
+    }
+
+    fn prng_seed() -> u64 {
+        static COUNTER: AtomicUsize = AtomicUsize::new(0);
+
+        // Any non-zero seed will do
+        let mut seed = 0;
+        while seed == 0 {
+            let mut hasher = DefaultHasher::new();
+            hasher.write_usize(COUNTER.fetch_add(1, Ordering::Relaxed));
+            seed = hasher.finish();
+        }
+        seed
+    }
+
+    RNG.with(|rng| {
+        let mut x = rng.get();
+        debug_assert_ne!(x.0, 0);
+        x ^= x >> 12;
+        x ^= x << 25;
+        x ^= x >> 27;
+        rng.set(x);
+        x.0.wrapping_mul(0x2545_f491_4f6c_dd1d)
+    })
+}
diff --git a/vendor/futures-util/src/async_await/select_mod.rs b/vendor/futures-util/src/async_await/select_mod.rs
new file mode 100644
index 000000000..1d13067d3
--- /dev/null
+++ b/vendor/futures-util/src/async_await/select_mod.rs
@@ -0,0 +1,336 @@
+//! The `select` macro.
+
+macro_rules! document_select_macro {
+    // This branch is required for `futures 0.3.1`, from before select_biased was introduced
+    ($select:item) => {
+        /// Polls multiple futures and streams simultaneously, executing the branch
+        /// for the future that finishes first. If multiple futures are ready,
+        /// one will be pseudo-randomly selected at runtime. Futures directly
+        /// passed to `select!` must be `Unpin` and implement `FusedFuture`.
+        ///
+        /// If an expression which yields a `Future` is passed to `select!`
+        /// (e.g. an `async fn` call) instead of a `Future` by name the `Unpin`
+        /// requirement is relaxed, since the macro will pin the resulting `Future`
+        /// on the stack. However the `Future` returned by the expression must
+        /// still implement `FusedFuture`.
+        ///
+        /// Futures and streams which are not already fused can be fused using the
+        /// `.fuse()` method. Note, though, that fusing a future or stream directly
+        /// in the call to `select!` will not be enough to prevent it from being
+        /// polled after completion if the `select!` call is in a loop, so when
+        /// `select!`ing in a loop, users should take care to `fuse()` outside of
+        /// the loop.
+        ///
+        /// `select!` can be used as an expression and will return the return
+        /// value of the selected branch. For this reason the return type of every
+        /// branch in a `select!` must be the same.
+        ///
+        /// This macro is only usable inside of async functions, closures, and blocks.
+        /// It is also gated behind the `async-await` feature of this library, which is
+        /// activated by default.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future;
+        /// use futures::select;
+        /// let mut a = future::ready(4);
+        /// let mut b = future::pending::<()>();
+        ///
+        /// let res = select! {
+        ///     a_res = a => a_res + 1,
+        ///     _ = b => 0,
+        /// };
+        /// assert_eq!(res, 5);
+        /// # });
+        /// ```
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future;
+        /// use futures::stream::{self, StreamExt};
+        /// use futures::select;
+        /// let mut st = stream::iter(vec![2]).fuse();
+        /// let mut fut = future::pending::<()>();
+        ///
+        /// select! {
+        ///     x = st.next() => assert_eq!(Some(2), x),
+        ///     _ = fut => panic!(),
+        /// };
+        /// # });
+        /// ```
+        ///
+        /// As described earlier, `select` can directly select on expressions
+        /// which return `Future`s - even if those do not implement `Unpin`:
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future::FutureExt;
+        /// use futures::select;
+        ///
+        /// // Calling the following async fn returns a Future which does not
+        /// // implement Unpin
+        /// async fn async_identity_fn(arg: usize) -> usize {
+        ///     arg
+        /// }
+        ///
+        /// let res = select! {
+        ///     a_res = async_identity_fn(62).fuse() => a_res + 1,
+        ///     b_res = async_identity_fn(13).fuse() => b_res,
+        /// };
+        /// assert!(res == 63 || res == 13);
+        /// # });
+        /// ```
+        ///
+        /// If a similar async function is called outside of `select` to produce
+        /// a `Future`, the `Future` must be pinned in order to be able to pass
+        /// it to `select`. This can be achieved via `Box::pin` for pinning a
+        /// `Future` on the heap or the `pin_mut!` macro for pinning a `Future`
+        /// on the stack.
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future::FutureExt;
+        /// use futures::select;
+        /// use futures::pin_mut;
+        ///
+        /// // Calling the following async fn returns a Future which does not
+        /// // implement Unpin
+        /// async fn async_identity_fn(arg: usize) -> usize {
+        ///     arg
+        /// }
+        ///
+        /// let fut_1 = async_identity_fn(1).fuse();
+        /// let fut_2 = async_identity_fn(2).fuse();
+        /// let mut fut_1 = Box::pin(fut_1); // Pins the Future on the heap
+        /// pin_mut!(fut_2); // Pins the Future on the stack
+        ///
+        /// let res = select! {
+        ///     a_res = fut_1 => a_res,
+        ///     b_res = fut_2 => b_res,
+        /// };
+        /// assert!(res == 1 || res == 2);
+        /// # });
+        /// ```
+        ///
+        /// `select` also accepts a `complete` branch and a `default` branch.
+        /// `complete` will run if all futures and streams have already been
+        /// exhausted. `default` will run if no futures or streams are
+        /// immediately ready. `complete` takes priority over `default` in
+        /// the case where all futures have completed.
+        /// A motivating use-case for passing `Future`s by name as well as for
+        /// `complete` blocks is to call `select!` in a loop, which is
+        /// demonstrated in the following example:
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future;
+        /// use futures::select;
+        /// let mut a_fut = future::ready(4);
+        /// let mut b_fut = future::ready(6);
+        /// let mut total = 0;
+        ///
+        /// loop {
+        ///     select! {
+        ///         a = a_fut => total += a,
+        ///         b = b_fut => total += b,
+        ///         complete => break,
+        ///         default => panic!(), // never runs (futures run first, then complete)
+        ///     };
+        /// }
+        /// assert_eq!(total, 10);
+        /// # });
+        /// ```
+        ///
+        /// Note that the futures that have been matched over can still be mutated
+        /// from inside the `select!` block's branches. This can be used to implement
+        /// more complex behavior such as timer resets or writing into the head of
+        /// a stream.
+        $select
+    };
+
+    ($select:item $select_biased:item) => {
+        document_select_macro!($select);
+
+        /// Polls multiple futures and streams simultaneously, executing the branch
+        /// for the future that finishes first. Unlike [`select!`], if multiple futures are ready,
+        /// one will be selected in order of declaration. Futures directly
+        /// passed to `select_biased!` must be `Unpin` and implement `FusedFuture`.
+        ///
+        /// If an expression which yields a `Future` is passed to `select_biased!`
+        /// (e.g. an `async fn` call) instead of a `Future` by name the `Unpin`
+        /// requirement is relaxed, since the macro will pin the resulting `Future`
+        /// on the stack. However the `Future` returned by the expression must
+        /// still implement `FusedFuture`.
+        ///
+        /// Futures and streams which are not already fused can be fused using the
+        /// `.fuse()` method. Note, though, that fusing a future or stream directly
+        /// in the call to `select_biased!` will not be enough to prevent it from being
+        /// polled after completion if the `select_biased!` call is in a loop, so when
+        /// `select_biased!`ing in a loop, users should take care to `fuse()` outside of
+        /// the loop.
+        ///
+        /// `select_biased!` can be used as an expression and will return the return
+        /// value of the selected branch. For this reason the return type of every
+        /// branch in a `select_biased!` must be the same.
+        ///
+        /// This macro is only usable inside of async functions, closures, and blocks.
+        /// It is also gated behind the `async-await` feature of this library, which is
+        /// activated by default.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future;
+        /// use futures::select_biased;
+        /// let mut a = future::ready(4);
+        /// let mut b = future::pending::<()>();
+        ///
+        /// let res = select_biased! {
+        ///     a_res = a => a_res + 1,
+        ///     _ = b => 0,
+        /// };
+        /// assert_eq!(res, 5);
+        /// # });
+        /// ```
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future;
+        /// use futures::stream::{self, StreamExt};
+        /// use futures::select_biased;
+        /// let mut st = stream::iter(vec![2]).fuse();
+        /// let mut fut = future::pending::<()>();
+        ///
+        /// select_biased! {
+        ///     x = st.next() => assert_eq!(Some(2), x),
+        ///     _ = fut => panic!(),
+        /// };
+        /// # });
+        /// ```
+        ///
+        /// As described earlier, `select_biased` can directly select on expressions
+        /// which return `Future`s - even if those do not implement `Unpin`:
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future::FutureExt;
+        /// use futures::select_biased;
+        ///
+        /// // Calling the following async fn returns a Future which does not
+        /// // implement Unpin
+        /// async fn async_identity_fn(arg: usize) -> usize {
+        ///     arg
+        /// }
+        ///
+        /// let res = select_biased! {
+        ///     a_res = async_identity_fn(62).fuse() => a_res + 1,
+        ///     b_res = async_identity_fn(13).fuse() => b_res,
+        /// };
+        /// assert!(res == 63 || res == 12);
+        /// # });
+        /// ```
+        ///
+        /// If a similar async function is called outside of `select_biased` to produce
+        /// a `Future`, the `Future` must be pinned in order to be able to pass
+        /// it to `select_biased`. This can be achieved via `Box::pin` for pinning a
+        /// `Future` on the heap or the `pin_mut!` macro for pinning a `Future`
+        /// on the stack.
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future::FutureExt;
+        /// use futures::select_biased;
+        /// use futures::pin_mut;
+        ///
+        /// // Calling the following async fn returns a Future which does not
+        /// // implement Unpin
+        /// async fn async_identity_fn(arg: usize) -> usize {
+        ///     arg
+        /// }
+        ///
+        /// let fut_1 = async_identity_fn(1).fuse();
+        /// let fut_2 = async_identity_fn(2).fuse();
+        /// let mut fut_1 = Box::pin(fut_1); // Pins the Future on the heap
+        /// pin_mut!(fut_2); // Pins the Future on the stack
+        ///
+        /// let res = select_biased! {
+        ///     a_res = fut_1 => a_res,
+        ///     b_res = fut_2 => b_res,
+        /// };
+        /// assert!(res == 1 || res == 2);
+        /// # });
+        /// ```
+        ///
+        /// `select_biased` also accepts a `complete` branch and a `default` branch.
+        /// `complete` will run if all futures and streams have already been
+        /// exhausted. `default` will run if no futures or streams are
+        /// immediately ready. `complete` takes priority over `default` in
+        /// the case where all futures have completed.
+        /// A motivating use-case for passing `Future`s by name as well as for
+        /// `complete` blocks is to call `select_biased!` in a loop, which is
+        /// demonstrated in the following example:
+        ///
+        /// ```
+        /// # futures::executor::block_on(async {
+        /// use futures::future;
+        /// use futures::select_biased;
+        /// let mut a_fut = future::ready(4);
+        /// let mut b_fut = future::ready(6);
+        /// let mut total = 0;
+        ///
+        /// loop {
+        ///     select_biased! {
+        ///         a = a_fut => total += a,
+        ///         b = b_fut => total += b,
+        ///         complete => break,
+        ///         default => panic!(), // never runs (futures run first, then complete)
+        ///     };
+        /// }
+        /// assert_eq!(total, 10);
+        /// # });
+        /// ```
+        ///
+        /// Note that the futures that have been matched over can still be mutated
+        /// from inside the `select_biased!` block's branches. This can be used to implement
+        /// more complex behavior such as timer resets or writing into the head of
+        /// a stream.
+        ///
+        /// [`select!`]: macro.select.html
+        $select_biased
+    };
+}
+
+#[cfg(feature = "std")]
+#[allow(unreachable_pub)]
+#[doc(hidden)]
+pub use futures_macro::select_internal;
+
+#[allow(unreachable_pub)]
+#[doc(hidden)]
+pub use futures_macro::select_biased_internal;
+
+document_select_macro! {
+    #[cfg(feature = "std")]
+    #[macro_export]
+    macro_rules! select {
+        ($($tokens:tt)*) => {{
+            use $crate::__private as __futures_crate;
+            $crate::select_internal! {
+                $( $tokens )*
+            }
+        }}
+    }
+
+    #[macro_export]
+    macro_rules! select_biased {
+        ($($tokens:tt)*) => {{
+            use $crate::__private as __futures_crate;
+            $crate::select_biased_internal! {
+                $( $tokens )*
+            }
+        }}
+    }
+}
diff --git a/vendor/futures-util/src/async_await/stream_select_mod.rs b/vendor/futures-util/src/async_await/stream_select_mod.rs
new file mode 100644
index 000000000..1c8002fff
--- /dev/null
+++ b/vendor/futures-util/src/async_await/stream_select_mod.rs
@@ -0,0 +1,40 @@
+//! The `stream_select` macro.
+
+#[cfg(feature = "std")]
+#[allow(unreachable_pub)]
+#[doc(hidden)]
+pub use futures_macro::stream_select_internal;
+
+/// Combines several streams, all producing the same `Item` type, into one stream.
+/// This is similar to `select_all` but does not require the streams to all be the same type.
+/// It also keeps the streams inline, and does not require `Box<dyn Stream>`s to be allocated.
+/// Streams passed to this macro must be `Unpin`.
+///
+/// If multiple streams are ready, one will be pseudo randomly selected at runtime.
+///
+/// # Examples
+///
+/// ```
+/// # futures::executor::block_on(async {
+/// use futures::{stream, StreamExt, stream_select};
+/// let endless_ints = |i| stream::iter(vec![i].into_iter().cycle()).fuse();
+///
+/// let mut endless_numbers = stream_select!(endless_ints(1i32), endless_ints(2), endless_ints(3));
+/// match endless_numbers.next().await {
+///     Some(1) => println!("Got a 1"),
+///     Some(2) => println!("Got a 2"),
+///     Some(3) => println!("Got a 3"),
+///     _ => unreachable!(),
+/// }
+/// # });
+/// ```
+#[cfg(feature = "std")]
+#[macro_export]
+macro_rules! stream_select {
+    ($($tokens:tt)*) => {{
+        use $crate::__private as __futures_crate;
+        $crate::stream_select_internal! {
+            $( $tokens )*
+        }
+    }}
+}