1 #![allow(non_snake_case)]
2
3 use crate::future::{TryMaybeDone, try_maybe_done};
4 use core::fmt;
5 use core::pin::Pin;
6 use futures_core::future::{Future, TryFuture};
7 use futures_core::task::{Context, Poll};
8 use pin_project_lite::pin_project;
9
10 macro_rules! generate {
11 ($(
12 $(#[$doc:meta])*
13 ($Join:ident, <Fut1, $($Fut:ident),*>),
14 )*) => ($(
15 pin_project! {
16 $(#[$doc])*
17 #[must_use = "futures do nothing unless you `.await` or poll them"]
18 pub struct $Join<Fut1: TryFuture, $($Fut: TryFuture),*> {
19 #[pin] Fut1: TryMaybeDone<Fut1>,
20 $(#[pin] $Fut: TryMaybeDone<$Fut>,)*
21 }
22 }
23
24 impl<Fut1, $($Fut),*> fmt::Debug for $Join<Fut1, $($Fut),*>
25 where
26 Fut1: TryFuture + fmt::Debug,
27 Fut1::Ok: fmt::Debug,
28 Fut1::Error: fmt::Debug,
29 $(
30 $Fut: TryFuture + fmt::Debug,
31 $Fut::Ok: fmt::Debug,
32 $Fut::Error: fmt::Debug,
33 )*
34 {
35 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
36 f.debug_struct(stringify!($Join))
37 .field("Fut1", &self.Fut1)
38 $(.field(stringify!($Fut), &self.$Fut))*
39 .finish()
40 }
41 }
42
43 impl<Fut1, $($Fut),*> $Join<Fut1, $($Fut),*>
44 where
45 Fut1: TryFuture,
46 $(
47 $Fut: TryFuture<Error=Fut1::Error>
48 ),*
49 {
50 fn new(Fut1: Fut1, $($Fut: $Fut),*) -> Self {
51 Self {
52 Fut1: try_maybe_done(Fut1),
53 $($Fut: try_maybe_done($Fut)),*
54 }
55 }
56 }
57
58 impl<Fut1, $($Fut),*> Future for $Join<Fut1, $($Fut),*>
59 where
60 Fut1: TryFuture,
61 $(
62 $Fut: TryFuture<Error=Fut1::Error>
63 ),*
64 {
65 type Output = Result<(Fut1::Ok, $($Fut::Ok),*), Fut1::Error>;
66
67 fn poll(
68 self: Pin<&mut Self>, cx: &mut Context<'_>
69 ) -> Poll<Self::Output> {
70 let mut all_done = true;
71 let mut futures = self.project();
72 all_done &= futures.Fut1.as_mut().poll(cx)?.is_ready();
73 $(
74 all_done &= futures.$Fut.as_mut().poll(cx)?.is_ready();
75 )*
76
77 if all_done {
78 Poll::Ready(Ok((
79 futures.Fut1.take_output().unwrap(),
80 $(
81 futures.$Fut.take_output().unwrap()
82 ),*
83 )))
84 } else {
85 Poll::Pending
86 }
87 }
88 }
89 )*)
90 }
91
92 generate! {
93 /// Future for the [`try_join`](try_join()) function.
94 (TryJoin, <Fut1, Fut2>),
95
96 /// Future for the [`try_join3`] function.
97 (TryJoin3, <Fut1, Fut2, Fut3>),
98
99 /// Future for the [`try_join4`] function.
100 (TryJoin4, <Fut1, Fut2, Fut3, Fut4>),
101
102 /// Future for the [`try_join5`] function.
103 (TryJoin5, <Fut1, Fut2, Fut3, Fut4, Fut5>),
104 }
105
106 /// Joins the result of two futures, waiting for them both to complete or
107 /// for one to produce an error.
108 ///
109 /// This function will return a new future which awaits both futures to
110 /// complete. If successful, the returned future will finish with a tuple of
111 /// both results. If unsuccesful, it will complete with the first error
112 /// encountered.
113 ///
114 /// Note that this function consumes the passed futures and returns a
115 /// wrapped version of it.
116 ///
117 /// # Examples
118 ///
119 /// When used on multiple futures that return [`Ok`], `try_join` will return
120 /// [`Ok`] of a tuple of the values:
121 ///
122 /// ```
123 /// # futures::executor::block_on(async {
124 /// use futures::future;
125 ///
126 /// let a = future::ready(Ok::<i32, i32>(1));
127 /// let b = future::ready(Ok::<i32, i32>(2));
128 /// let pair = future::try_join(a, b);
129 ///
130 /// assert_eq!(pair.await, Ok((1, 2)));
131 /// # });
132 /// ```
133 ///
134 /// If one of the futures resolves to an error, `try_join` will return
135 /// that error:
136 ///
137 /// ```
138 /// # futures::executor::block_on(async {
139 /// use futures::future;
140 ///
141 /// let a = future::ready(Ok::<i32, i32>(1));
142 /// let b = future::ready(Err::<i32, i32>(2));
143 /// let pair = future::try_join(a, b);
144 ///
145 /// assert_eq!(pair.await, Err(2));
146 /// # });
147 /// ```
try_join<Fut1, Fut2>(future1: Fut1, future2: Fut2) -> TryJoin<Fut1, Fut2> where Fut1: TryFuture, Fut2: TryFuture<Error = Fut1::Error>,148 pub fn try_join<Fut1, Fut2>(future1: Fut1, future2: Fut2) -> TryJoin<Fut1, Fut2>
149 where
150 Fut1: TryFuture,
151 Fut2: TryFuture<Error = Fut1::Error>,
152 {
153 TryJoin::new(future1, future2)
154 }
155
156 /// Same as [`try_join`](try_join()), but with more futures.
157 ///
158 /// # Examples
159 ///
160 /// ```
161 /// # futures::executor::block_on(async {
162 /// use futures::future;
163 ///
164 /// let a = future::ready(Ok::<i32, i32>(1));
165 /// let b = future::ready(Ok::<i32, i32>(2));
166 /// let c = future::ready(Ok::<i32, i32>(3));
167 /// let tuple = future::try_join3(a, b, c);
168 ///
169 /// assert_eq!(tuple.await, Ok((1, 2, 3)));
170 /// # });
171 /// ```
try_join3<Fut1, Fut2, Fut3>( future1: Fut1, future2: Fut2, future3: Fut3, ) -> TryJoin3<Fut1, Fut2, Fut3> where Fut1: TryFuture, Fut2: TryFuture<Error = Fut1::Error>, Fut3: TryFuture<Error = Fut1::Error>,172 pub fn try_join3<Fut1, Fut2, Fut3>(
173 future1: Fut1,
174 future2: Fut2,
175 future3: Fut3,
176 ) -> TryJoin3<Fut1, Fut2, Fut3>
177 where
178 Fut1: TryFuture,
179 Fut2: TryFuture<Error = Fut1::Error>,
180 Fut3: TryFuture<Error = Fut1::Error>,
181 {
182 TryJoin3::new(future1, future2, future3)
183 }
184
185 /// Same as [`try_join`](try_join()), but with more futures.
186 ///
187 /// # Examples
188 ///
189 /// ```
190 /// # futures::executor::block_on(async {
191 /// use futures::future;
192 ///
193 /// let a = future::ready(Ok::<i32, i32>(1));
194 /// let b = future::ready(Ok::<i32, i32>(2));
195 /// let c = future::ready(Ok::<i32, i32>(3));
196 /// let d = future::ready(Ok::<i32, i32>(4));
197 /// let tuple = future::try_join4(a, b, c, d);
198 ///
199 /// assert_eq!(tuple.await, Ok((1, 2, 3, 4)));
200 /// # });
201 /// ```
try_join4<Fut1, Fut2, Fut3, Fut4>( future1: Fut1, future2: Fut2, future3: Fut3, future4: Fut4, ) -> TryJoin4<Fut1, Fut2, Fut3, Fut4> where Fut1: TryFuture, Fut2: TryFuture<Error = Fut1::Error>, Fut3: TryFuture<Error = Fut1::Error>, Fut4: TryFuture<Error = Fut1::Error>,202 pub fn try_join4<Fut1, Fut2, Fut3, Fut4>(
203 future1: Fut1,
204 future2: Fut2,
205 future3: Fut3,
206 future4: Fut4,
207 ) -> TryJoin4<Fut1, Fut2, Fut3, Fut4>
208 where
209 Fut1: TryFuture,
210 Fut2: TryFuture<Error = Fut1::Error>,
211 Fut3: TryFuture<Error = Fut1::Error>,
212 Fut4: TryFuture<Error = Fut1::Error>,
213 {
214 TryJoin4::new(future1, future2, future3, future4)
215 }
216
217 /// Same as [`try_join`](try_join()), but with more futures.
218 ///
219 /// # Examples
220 ///
221 /// ```
222 /// # futures::executor::block_on(async {
223 /// use futures::future;
224 ///
225 /// let a = future::ready(Ok::<i32, i32>(1));
226 /// let b = future::ready(Ok::<i32, i32>(2));
227 /// let c = future::ready(Ok::<i32, i32>(3));
228 /// let d = future::ready(Ok::<i32, i32>(4));
229 /// let e = future::ready(Ok::<i32, i32>(5));
230 /// let tuple = future::try_join5(a, b, c, d, e);
231 ///
232 /// assert_eq!(tuple.await, Ok((1, 2, 3, 4, 5)));
233 /// # });
234 /// ```
try_join5<Fut1, Fut2, Fut3, Fut4, Fut5>( future1: Fut1, future2: Fut2, future3: Fut3, future4: Fut4, future5: Fut5, ) -> TryJoin5<Fut1, Fut2, Fut3, Fut4, Fut5> where Fut1: TryFuture, Fut2: TryFuture<Error = Fut1::Error>, Fut3: TryFuture<Error = Fut1::Error>, Fut4: TryFuture<Error = Fut1::Error>, Fut5: TryFuture<Error = Fut1::Error>,235 pub fn try_join5<Fut1, Fut2, Fut3, Fut4, Fut5>(
236 future1: Fut1,
237 future2: Fut2,
238 future3: Fut3,
239 future4: Fut4,
240 future5: Fut5,
241 ) -> TryJoin5<Fut1, Fut2, Fut3, Fut4, Fut5>
242 where
243 Fut1: TryFuture,
244 Fut2: TryFuture<Error = Fut1::Error>,
245 Fut3: TryFuture<Error = Fut1::Error>,
246 Fut4: TryFuture<Error = Fut1::Error>,
247 Fut5: TryFuture<Error = Fut1::Error>,
248 {
249 TryJoin5::new(future1, future2, future3, future4, future5)
250 }
251