completion 0.2.1

Utilities for writing completion-based asynchronous code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

use core::marker::PhantomData;
use core::pin::Pin;
use core::task::{Context, Poll};

use completion_core::CompletionFuture;
use pin_project_lite::pin_project;

use super::super::{ControlFlow, RaceOkFuture, TryFuture};
use super::base::{Join, JoinTuple};

/// Wait for the first future in a tuple to successfully complete.
///
/// Requires the `std` feature, as [`std::panic::catch_unwind`] is needed when polling the futures
/// to ensure soundness.
///
/// # Examples
///
/// ```
/// use completion::{future, completion_async};
/// use futures_lite::future::yield_now;
///
/// # future::block_on(completion_async! {
/// assert_eq!(
///     future::race_ok((
///         completion_async!(Err(())),
///         completion_async!(Ok::<_, ()>(3)),
///         std::future::pending::<Result<_, ()>>(),
///     ))
///     .await,
///     Ok(3),
/// );
/// # });
/// ```
///
/// If all the futures fail, this will return a tuple of the errors.
///
/// ```
/// use completion::{future, completion_async};
/// use futures_lite::future::yield_now;
///
/// # future::block_on(completion_async! {
/// assert_eq!(
///     future::race_ok((
///         completion_async!(Err::<(), _>(0)),
///         completion_async!(Err(1)),
///         completion_async!(Err(2)),
///     ))
///     .await,
///     Err((0, 1, 2)),
/// );
/// # });
/// ```
///
/// If multiple futures are immediately successfully ready, the earlier one will be chosen. However
/// after this polling will be fair.
///
/// ```
/// use completion::{future, completion_async};
/// use futures_lite::future::yield_now;
///
/// # future::block_on(completion_async! {
/// assert_eq!(
///     future::race_ok((
///         completion_async! {
///             yield_now().await;
///             Ok::<_, ()>(0)
///         },
///         completion_async!(Ok::<_, ()>(1)),
///         completion_async!(Err(2)),
///         completion_async!(Ok::<_, ()>(3)),
///     ))
///     .await,
///     Ok(1),
/// );
/// # });
/// ```
#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
pub fn race_ok<T: RaceOkTuple>(futures: T) -> RaceOk<T> {
    RaceOk {
        inner: Join::new(futures.into_tuple()),
        _correct_debug_bounds: PhantomData,
    }
}

pin_project! {
    /// Future for [`race_ok`].
    #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
    #[derive(Debug)]
    pub struct RaceOk<T: RaceOkTuple> {
        #[pin]
        inner: Join<T::JoinTuple>,
        _correct_debug_bounds: PhantomData<(T::Futures, T::Ok)>,
    }
}

impl<T: RaceOkTuple> CompletionFuture for RaceOk<T> {
    type Output = Result<T::Ok, <T::JoinTuple as JoinTuple>::Output>;

    unsafe fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        self.project().inner.poll(cx).map(|flow| match flow {
            ControlFlow::Continue(errors) => Err(errors),
            ControlFlow::Break(val) => Ok(val),
        })
    }
    unsafe fn poll_cancel(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        self.project().inner.poll_cancel(cx)
    }
}

/// A tuple of futures that can be used in `RaceOk`.
pub trait RaceOkTuple {
    /// The tuple that can be used with `Join`.
    type JoinTuple: JoinTuple<Futures = Self::Futures, Break = Self::Ok>;
    fn into_tuple(self) -> Self::JoinTuple;

    type Futures;
    type Ok;
}

macro_rules! impl_race_tuple {
    ($($param:ident),*) => {
        impl<Ok, $($param,)*> RaceOkTuple for ($($param,)*)
        where
            $($param: TryFuture<Ok = Ok>,)*
        {
            type JoinTuple = ($(RaceOkFuture<$param>,)*);
            fn into_tuple(self) -> Self::JoinTuple {
                let ($($param,)*) = self;
                ($(RaceOkFuture::new($param),)*)
            }

            type Futures = <Self::JoinTuple as JoinTuple>::Futures;
            type Ok = Ok;
        }
    }
}
apply_on_tuples!(impl_race_tuple!);