//! Wait for the first of several futures to complete.
use core::future::Future;
use core::pin::Pin;
use core::task::{Context, Poll};
/// Result for [`select`].
#[derive(Debug, Clone)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Either {
/// First future finished first.
First(A),
/// Second future finished first.
Second(B),
}
impl Either {
/// Did the first future complete first?
pub fn is_first(&self) -> bool {
matches!(self, Either::First(_))
}
/// Did the second future complete first?
pub fn is_second(&self) -> bool {
matches!(self, Either::Second(_))
}
}
/// Wait for one of two futures to complete.
///
/// This function returns a new future which polls all the futures.
/// When one of them completes, it will complete with its result value.
///
/// The other future is dropped.
pub fn select(a: A, b: B) -> Select
where
A: Future,
B: Future,
{
Select { a, b }
}
/// Future for the [`select`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Select {
a: A,
b: B,
}
impl Unpin for Select {}
impl Future for Select
where
A: Future,
B: Future,
{
type Output = Either;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
let this = unsafe { self.get_unchecked_mut() };
let a = unsafe { Pin::new_unchecked(&mut this.a) };
let b = unsafe { Pin::new_unchecked(&mut this.b) };
if let Poll::Ready(x) = a.poll(cx) {
return Poll::Ready(Either::First(x));
}
if let Poll::Ready(x) = b.poll(cx) {
return Poll::Ready(Either::Second(x));
}
Poll::Pending
}
}
// ====================================================================
/// Result for [`select3`].
#[derive(Debug, Clone)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Either3 {
/// First future finished first.
First(A),
/// Second future finished first.
Second(B),
/// Third future finished first.
Third(C),
}
impl Either3 {
/// Did the first future complete first?
pub fn is_first(&self) -> bool {
matches!(self, Either3::First(_))
}
/// Did the second future complete first?
pub fn is_second(&self) -> bool {
matches!(self, Either3::Second(_))
}
/// Did the third future complete first?
pub fn is_third(&self) -> bool {
matches!(self, Either3::Third(_))
}
}
/// Same as [`select`], but with more futures.
pub fn select3(a: A, b: B, c: C) -> Select3
where
A: Future,
B: Future,
C: Future,
{
Select3 { a, b, c }
}
/// Future for the [`select3`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Select3 {
a: A,
b: B,
c: C,
}
impl Future for Select3
where
A: Future,
B: Future,
C: Future,
{
type Output = Either3;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
let this = unsafe { self.get_unchecked_mut() };
let a = unsafe { Pin::new_unchecked(&mut this.a) };
let b = unsafe { Pin::new_unchecked(&mut this.b) };
let c = unsafe { Pin::new_unchecked(&mut this.c) };
if let Poll::Ready(x) = a.poll(cx) {
return Poll::Ready(Either3::First(x));
}
if let Poll::Ready(x) = b.poll(cx) {
return Poll::Ready(Either3::Second(x));
}
if let Poll::Ready(x) = c.poll(cx) {
return Poll::Ready(Either3::Third(x));
}
Poll::Pending
}
}
// ====================================================================
/// Result for [`select4`].
#[derive(Debug, Clone)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Either4 {
/// First future finished first.
First(A),
/// Second future finished first.
Second(B),
/// Third future finished first.
Third(C),
/// Fourth future finished first.
Fourth(D),
}
impl Either4 {
/// Did the first future complete first?
pub fn is_first(&self) -> bool {
matches!(self, Either4::First(_))
}
/// Did the second future complete first?
pub fn is_second(&self) -> bool {
matches!(self, Either4::Second(_))
}
/// Did the third future complete first?
pub fn is_third(&self) -> bool {
matches!(self, Either4::Third(_))
}
/// Did the fourth future complete first?
pub fn is_fourth(&self) -> bool {
matches!(self, Either4::Fourth(_))
}
}
/// Same as [`select`], but with more futures.
pub fn select4(a: A, b: B, c: C, d: D) -> Select4
where
A: Future,
B: Future,
C: Future,
D: Future,
{
Select4 { a, b, c, d }
}
/// Future for the [`select4`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Select4 {
a: A,
b: B,
c: C,
d: D,
}
impl Future for Select4
where
A: Future,
B: Future,
C: Future,
D: Future,
{
type Output = Either4;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
let this = unsafe { self.get_unchecked_mut() };
let a = unsafe { Pin::new_unchecked(&mut this.a) };
let b = unsafe { Pin::new_unchecked(&mut this.b) };
let c = unsafe { Pin::new_unchecked(&mut this.c) };
let d = unsafe { Pin::new_unchecked(&mut this.d) };
if let Poll::Ready(x) = a.poll(cx) {
return Poll::Ready(Either4::First(x));
}
if let Poll::Ready(x) = b.poll(cx) {
return Poll::Ready(Either4::Second(x));
}
if let Poll::Ready(x) = c.poll(cx) {
return Poll::Ready(Either4::Third(x));
}
if let Poll::Ready(x) = d.poll(cx) {
return Poll::Ready(Either4::Fourth(x));
}
Poll::Pending
}
}
// ====================================================================
/// Result for [`select5`].
#[derive(Debug, Clone)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Either5 {
/// First future finished first.
First(A),
/// Second future finished first.
Second(B),
/// Third future finished first.
Third(C),
/// Fourth future finished first.
Fourth(D),
/// Fifth future finished first.
Fifth(E),
}
impl Either5 {
/// Did the first future complete first?
pub fn is_first(&self) -> bool {
matches!(self, Either5::First(_))
}
/// Did the second future complete first?
pub fn is_second(&self) -> bool {
matches!(self, Either5::Second(_))
}
/// Did the third future complete first?
pub fn is_third(&self) -> bool {
matches!(self, Either5::Third(_))
}
/// Did the fourth future complete first?
pub fn is_fourth(&self) -> bool {
matches!(self, Either5::Fourth(_))
}
/// Did the fifth future complete first?
pub fn is_fifth(&self) -> bool {
matches!(self, Either5::Fifth(_))
}
}
/// Same as [`select`], but with more futures.
pub fn select5(a: A, b: B, c: C, d: D, e: E) -> Select5
where
A: Future,
B: Future,
C: Future,
D: Future,
E: Future,
{
Select5 { a, b, c, d, e }
}
/// Future for the [`select5`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Select5 {
a: A,
b: B,
c: C,
d: D,
e: E,
}
impl Future for Select5
where
A: Future,
B: Future,
C: Future,
D: Future,
E: Future,
{
type Output = Either5;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
let this = unsafe { self.get_unchecked_mut() };
let a = unsafe { Pin::new_unchecked(&mut this.a) };
let b = unsafe { Pin::new_unchecked(&mut this.b) };
let c = unsafe { Pin::new_unchecked(&mut this.c) };
let d = unsafe { Pin::new_unchecked(&mut this.d) };
let e = unsafe { Pin::new_unchecked(&mut this.e) };
if let Poll::Ready(x) = a.poll(cx) {
return Poll::Ready(Either5::First(x));
}
if let Poll::Ready(x) = b.poll(cx) {
return Poll::Ready(Either5::Second(x));
}
if let Poll::Ready(x) = c.poll(cx) {
return Poll::Ready(Either5::Third(x));
}
if let Poll::Ready(x) = d.poll(cx) {
return Poll::Ready(Either5::Fourth(x));
}
if let Poll::Ready(x) = e.poll(cx) {
return Poll::Ready(Either5::Fifth(x));
}
Poll::Pending
}
}
// ====================================================================
/// Result for [`select6`].
#[derive(Debug, Clone)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Either6 {
/// First future finished first.
First(A),
/// Second future finished first.
Second(B),
/// Third future finished first.
Third(C),
/// Fourth future finished first.
Fourth(D),
/// Fifth future finished first.
Fifth(E),
/// Sixth future finished first.
Sixth(F),
}
impl Either6 {
/// Did the first future complete first?
pub fn is_first(&self) -> bool {
matches!(self, Either6::First(_))
}
/// Did the second future complete first?
pub fn is_second(&self) -> bool {
matches!(self, Either6::Second(_))
}
/// Did the third future complete first?
pub fn is_third(&self) -> bool {
matches!(self, Either6::Third(_))
}
/// Did the fourth future complete first?
pub fn is_fourth(&self) -> bool {
matches!(self, Either6::Fourth(_))
}
/// Did the fifth future complete first?
pub fn is_fifth(&self) -> bool {
matches!(self, Either6::Fifth(_))
}
/// Did the sixth future complete first?
pub fn is_sixth(&self) -> bool {
matches!(self, Either6::Sixth(_))
}
}
/// Same as [`select`], but with more futures.
pub fn select6(a: A, b: B, c: C, d: D, e: E, f: F) -> Select6
where
A: Future,
B: Future,
C: Future,
D: Future,
E: Future,
F: Future,
{
Select6 { a, b, c, d, e, f }
}
/// Future for the [`select6`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Select6 {
a: A,
b: B,
c: C,
d: D,
e: E,
f: F,
}
impl Future for Select6
where
A: Future,
B: Future,
C: Future,
D: Future,
E: Future,
F: Future,
{
type Output = Either6;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
let this = unsafe { self.get_unchecked_mut() };
let a = unsafe { Pin::new_unchecked(&mut this.a) };
let b = unsafe { Pin::new_unchecked(&mut this.b) };
let c = unsafe { Pin::new_unchecked(&mut this.c) };
let d = unsafe { Pin::new_unchecked(&mut this.d) };
let e = unsafe { Pin::new_unchecked(&mut this.e) };
let f = unsafe { Pin::new_unchecked(&mut this.f) };
if let Poll::Ready(x) = a.poll(cx) {
return Poll::Ready(Either6::First(x));
}
if let Poll::Ready(x) = b.poll(cx) {
return Poll::Ready(Either6::Second(x));
}
if let Poll::Ready(x) = c.poll(cx) {
return Poll::Ready(Either6::Third(x));
}
if let Poll::Ready(x) = d.poll(cx) {
return Poll::Ready(Either6::Fourth(x));
}
if let Poll::Ready(x) = e.poll(cx) {
return Poll::Ready(Either6::Fifth(x));
}
if let Poll::Ready(x) = f.poll(cx) {
return Poll::Ready(Either6::Sixth(x));
}
Poll::Pending
}
}
// ====================================================================
/// Future for the [`select_array`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct SelectArray {
inner: [Fut; N],
}
/// Creates a new future which will select over an array of futures.
///
/// The returned future will wait for any future to be ready. Upon
/// completion the item resolved will be returned, along with the index of the
/// future that was ready.
///
/// If the array is empty, the resulting future will be Pending forever.
pub fn select_array(arr: [Fut; N]) -> SelectArray {
SelectArray { inner: arr }
}
impl Future for SelectArray {
type Output = (Fut::Output, usize);
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
// Safety: Since `self` is pinned, `inner` cannot move. Since `inner` cannot move,
// its elements also cannot move. Therefore it is safe to access `inner` and pin
// references to the contained futures.
let item = unsafe {
self.get_unchecked_mut()
.inner
.iter_mut()
.enumerate()
.find_map(|(i, f)| match Pin::new_unchecked(f).poll(cx) {
Poll::Pending => None,
Poll::Ready(e) => Some((i, e)),
})
};
match item {
Some((idx, res)) => Poll::Ready((res, idx)),
None => Poll::Pending,
}
}
}
// ====================================================================
/// Future for the [`select_slice`] function.
#[derive(Debug)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct SelectSlice<'a, Fut> {
inner: Pin<&'a mut [Fut]>,
}
/// Creates a new future which will select over a slice of futures.
///
/// The returned future will wait for any future to be ready. Upon
/// completion the item resolved will be returned, along with the index of the
/// future that was ready.
///
/// If the slice is empty, the resulting future will be Pending forever.
pub fn select_slice<'a, Fut: Future>(slice: Pin<&'a mut [Fut]>) -> SelectSlice<'a, Fut> {
SelectSlice { inner: slice }
}
impl<'a, Fut: Future> Future for SelectSlice<'a, Fut> {
type Output = (Fut::Output, usize);
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
// Safety: refer to
// https://users.rust-lang.org/t/working-with-pinned-slices-are-there-any-structurally-pinning-vec-like-collection-types/50634/2
#[inline(always)]
fn pin_iter(slice: Pin<&mut [T]>) -> impl Iterator- > {
unsafe { slice.get_unchecked_mut().iter_mut().map(|v| Pin::new_unchecked(v)) }
}
for (i, fut) in pin_iter(self.inner.as_mut()).enumerate() {
if let Poll::Ready(res) = fut.poll(cx) {
return Poll::Ready((res, i));
}
}
Poll::Pending
}
}