1//! Asynchronous values.
2//!
3//! ## Base Futures Concurrency
4//!
5//! Often it's desirable to await multiple futures as if it was a single
6//! future. The `join` family of operations converts multiple futures into a
7//! single future that returns all of their outputs. The `race` family of
8//! operations converts multiple future into a single future that returns the
9//! first output.
10//!
11//! For operating on futures the following functions can be used:
12//!
13//! | Name | Return signature | When does it return? |
14//! | --- | --- | --- |
15//! | [`Future::join`] | `(T1, T2)` | Wait for all to complete
16//! | [`Future::race`] | `T` | Return on first value
17//!
18//! ## Fallible Futures Concurrency
19//!
20//! For operating on futures that return `Result` additional `try_` variants of
21//! the functions mentioned before can be used. These functions are aware of `Result`,
22//! and will behave slightly differently from their base variants.
23//!
24//! In the case of `try_join`, if any of the futures returns `Err` all
25//! futures are dropped and an error is returned. This is referred to as
26//! "short-circuiting".
27//!
28//! In the case of `try_race`, instead of returning the first future that
29//! completes it returns the first future that _successfully_ completes. This
30//! means `try_race` will keep going until any one of the futures returns
31//! `Ok`, or _all_ futures have returned `Err`.
32//!
33//! However sometimes it can be useful to use the base variants of the functions
34//! even on futures that return `Result`. Here is an overview of operations that
35//! work on `Result`, and their respective semantics:
36//!
37//! | Name | Return signature | When does it return? |
38//! | --- | --- | --- |
39//! | [`Future::join`] | `(Result<T, E>, Result<T, E>)` | Wait for all to complete
40//! | [`Future::try_join`] | `Result<(T1, T2), E>` | Return on first `Err`, wait for all to complete
41//! | [`Future::race`] | `Result<T, E>` | Return on first value
42//! | [`Future::try_race`] | `Result<T, E>` | Return on first `Ok`, reject on last Err
43//!
44//! [`Future::join`]: trait.Future.html#method.join
45//! [`Future::try_join`]: trait.Future.html#method.try_join
46//! [`Future::race`]: trait.Future.html#method.race
47//! [`Future::try_race`]: trait.Future.html#method.try_race
48
49cfg_alloc! {
50 pub use future::Future;
51 pub(crate) mod future;
52}
53
54cfg_std! {
55 pub use pending::pending;
56 pub use poll_fn::poll_fn;
57 pub use ready::ready;
58
59 mod pending;
60 mod poll_fn;
61 mod ready;
62}
63
64#[cfg(any(feature = "unstable", feature = "default"))]
65pub use timeout::{timeout, TimeoutError};
66#[cfg(any(feature = "unstable", feature = "default"))]
67mod timeout;
68
69cfg_unstable! {
70 pub use into_future::IntoFuture;
71 pub(crate) use maybe_done::MaybeDone;
72 mod into_future;
73 mod maybe_done;
74}
75