futures_util/async_await/
join_mod.rs

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
//! The `join` macro.

macro_rules! document_join_macro {
    ($join:item $try_join:item) => {
        /// Polls multiple futures simultaneously, returning a tuple
        /// of all results once complete.
        ///
        /// While `join!(a, b)` is similar to `(a.await, b.await)`,
        /// `join!` polls both futures concurrently and therefore is more efficient.
        ///
        /// This macro is only usable inside of async functions, closures, and blocks.
        /// It is also gated behind the `async-await` feature of this library, which is
        /// activated by default.
        ///
        /// # Examples
        ///
        /// ```
        /// # futures::executor::block_on(async {
        /// use futures::join;
        ///
        /// let a = async { 1 };
        /// let b = async { 2 };
        /// assert_eq!(join!(a, b), (1, 2));
        ///
        /// // `join!` is variadic, so you can pass any number of futures
        /// let c = async { 3 };
        /// let d = async { 4 };
        /// let e = async { 5 };
        /// assert_eq!(join!(c, d, e), (3, 4, 5));
        /// # });
        /// ```
        $join

        /// Polls multiple futures simultaneously, resolving to a [`Result`] containing
        /// either a tuple of the successful outputs or an error.
        ///
        /// `try_join!` is similar to [`join!`], but completes immediately if any of
        /// the futures return an error.
        ///
        /// This macro is only usable inside of async functions, closures, and blocks.
        /// It is also gated behind the `async-await` feature of this library, which is
        /// activated by default.
        ///
        /// # Examples
        ///
        /// When used on multiple futures that return `Ok`, `try_join!` will return
        /// `Ok` of a tuple of the values:
        ///
        /// ```
        /// # futures::executor::block_on(async {
        /// use futures::try_join;
        ///
        /// let a = async { Ok::<i32, i32>(1) };
        /// let b = async { Ok::<i32, i32>(2) };
        /// assert_eq!(try_join!(a, b), Ok((1, 2)));
        ///
        /// // `try_join!` is variadic, so you can pass any number of futures
        /// let c = async { Ok::<i32, i32>(3) };
        /// let d = async { Ok::<i32, i32>(4) };
        /// let e = async { Ok::<i32, i32>(5) };
        /// assert_eq!(try_join!(c, d, e), Ok((3, 4, 5)));
        /// # });
        /// ```
        ///
        /// If one of the futures resolves to an error, `try_join!` will return
        /// that error:
        ///
        /// ```
        /// # futures::executor::block_on(async {
        /// use futures::try_join;
        ///
        /// let a = async { Ok::<i32, i32>(1) };
        /// let b = async { Err::<u64, i32>(2) };
        ///
        /// assert_eq!(try_join!(a, b), Err(2));
        /// # });
        /// ```
        $try_join
    }
}

#[allow(unreachable_pub)]
#[doc(hidden)]
pub use futures_macro::join_internal;

#[allow(unreachable_pub)]
#[doc(hidden)]
pub use futures_macro::try_join_internal;

document_join_macro! {
    #[macro_export]
    macro_rules! join {
        ($($tokens:tt)*) => {{
            use $crate::__private as __futures_crate;
            $crate::join_internal! {
                $( $tokens )*
            }
        }}
    }

    #[macro_export]
    macro_rules! try_join {
        ($($tokens:tt)*) => {{
            use $crate::__private as __futures_crate;
            $crate::try_join_internal! {
                $( $tokens )*
            }
        }}
    }
}