1 | //! The `join` macro. |
2 | |
3 | macro_rules! document_join_macro { |
4 | ($join:item $try_join:item) => { |
5 | /// Polls multiple futures simultaneously, returning a tuple |
6 | /// of all results once complete. |
7 | /// |
8 | /// While `join!(a, b)` is similar to `(a.await, b.await)`, |
9 | /// `join!` polls both futures concurrently and therefore is more efficient. |
10 | /// |
11 | /// This macro is only usable inside of async functions, closures, and blocks. |
12 | /// It is also gated behind the `async-await` feature of this library, which is |
13 | /// activated by default. |
14 | /// |
15 | /// # Examples |
16 | /// |
17 | /// ``` |
18 | /// # futures::executor::block_on(async { |
19 | /// use futures::join; |
20 | /// |
21 | /// let a = async { 1 }; |
22 | /// let b = async { 2 }; |
23 | /// assert_eq!(join!(a, b), (1, 2)); |
24 | /// |
25 | /// // `join!` is variadic, so you can pass any number of futures |
26 | /// let c = async { 3 }; |
27 | /// let d = async { 4 }; |
28 | /// let e = async { 5 }; |
29 | /// assert_eq!(join!(c, d, e), (3, 4, 5)); |
30 | /// # }); |
31 | /// ``` |
32 | $join |
33 | |
34 | /// Polls multiple futures simultaneously, resolving to a [`Result`] containing |
35 | /// either a tuple of the successful outputs or an error. |
36 | /// |
37 | /// `try_join!` is similar to [`join!`], but completes immediately if any of |
38 | /// the futures return an error. |
39 | /// |
40 | /// This macro is only usable inside of async functions, closures, and blocks. |
41 | /// It is also gated behind the `async-await` feature of this library, which is |
42 | /// activated by default. |
43 | /// |
44 | /// # Examples |
45 | /// |
46 | /// When used on multiple futures that return `Ok`, `try_join!` will return |
47 | /// `Ok` of a tuple of the values: |
48 | /// |
49 | /// ``` |
50 | /// # futures::executor::block_on(async { |
51 | /// use futures::try_join; |
52 | /// |
53 | /// let a = async { Ok::<i32, i32>(1) }; |
54 | /// let b = async { Ok::<i32, i32>(2) }; |
55 | /// assert_eq!(try_join!(a, b), Ok((1, 2))); |
56 | /// |
57 | /// // `try_join!` is variadic, so you can pass any number of futures |
58 | /// let c = async { Ok::<i32, i32>(3) }; |
59 | /// let d = async { Ok::<i32, i32>(4) }; |
60 | /// let e = async { Ok::<i32, i32>(5) }; |
61 | /// assert_eq!(try_join!(c, d, e), Ok((3, 4, 5))); |
62 | /// # }); |
63 | /// ``` |
64 | /// |
65 | /// If one of the futures resolves to an error, `try_join!` will return |
66 | /// that error: |
67 | /// |
68 | /// ``` |
69 | /// # futures::executor::block_on(async { |
70 | /// use futures::try_join; |
71 | /// |
72 | /// let a = async { Ok::<i32, i32>(1) }; |
73 | /// let b = async { Err::<u64, i32>(2) }; |
74 | /// |
75 | /// assert_eq!(try_join!(a, b), Err(2)); |
76 | /// # }); |
77 | /// ``` |
78 | $try_join |
79 | } |
80 | } |
81 | |
82 | #[allow (unreachable_pub)] |
83 | #[doc (hidden)] |
84 | pub use futures_macro::join_internal; |
85 | |
86 | #[allow (unreachable_pub)] |
87 | #[doc (hidden)] |
88 | pub use futures_macro::try_join_internal; |
89 | |
90 | document_join_macro! { |
91 | #[macro_export ] |
92 | macro_rules! join { |
93 | ($($tokens:tt)*) => {{ |
94 | use $crate::__private as __futures_crate; |
95 | $crate::join_internal! { |
96 | $( $tokens )* |
97 | } |
98 | }} |
99 | } |
100 | |
101 | #[macro_export ] |
102 | macro_rules! try_join { |
103 | ($($tokens:tt)*) => {{ |
104 | use $crate::__private as __futures_crate; |
105 | $crate::try_join_internal! { |
106 | $( $tokens )* |
107 | } |
108 | }} |
109 | } |
110 | } |
111 | |