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