forked from mirror/async-std
67 lines
2.7 KiB
Rust
67 lines
2.7 KiB
Rust
//! Asynchronous values.
|
|
//!
|
|
//! ## Base Futures Concurrency
|
|
//!
|
|
//! Often it's desireable to await multiple futures as if it was a single
|
|
//! future. The `join` family of operations converts multiple futures into a
|
|
//! single future that returns all of their outputs. The `race` family of
|
|
//! operations converts multiple future into a single future that returns the
|
|
//! first output.
|
|
//!
|
|
//! For operating on futures the following functions can be used:
|
|
//!
|
|
//! | Name | Return signature | When does it return? |
|
|
//! | --- | --- | --- |
|
|
//! | [`Future::join`] | `(T1, T2)` | Wait for all to complete
|
|
//! | [`Future::race`] | `T` | Return on first value
|
|
//!
|
|
//! ## Fallible Futures Concurrency
|
|
//!
|
|
//! For operating on futures that return `Result` additional `try_` variants of
|
|
//! the functions mentioned before can be used. These functions are aware of `Result`,
|
|
//! and will behave slightly differently from their base variants.
|
|
//!
|
|
//! In the case of `try_join`, if any of the futures returns `Err` all
|
|
//! futures are dropped and an error is returned. This is referred to as
|
|
//! "short-circuiting".
|
|
//!
|
|
//! In the case of `try_race`, instead of returning the first future that
|
|
//! completes it returns the first future that _successfully_ completes. This
|
|
//! means `try_race` will keep going until any one of the futures returns
|
|
//! `Ok`, or _all_ futures have returned `Err`.
|
|
//!
|
|
//! However sometimes it can be useful to use the base variants of the functions
|
|
//! even on futures that return `Result`. Here is an overview of operations that
|
|
//! work on `Result`, and their respective semantics:
|
|
//!
|
|
//! | Name | Return signature | When does it return? |
|
|
//! | --- | --- | --- |
|
|
//! | [`Future::join`] | `(Result<T, E>, Result<T, E>)` | Wait for all to complete
|
|
//! | [`Future::try_join`] | `Result<(T1, T2), E>` | Return on first `Err`, wait for all to complete
|
|
//! | [`Future::race`] | `Result<T, E>` | Return on first value
|
|
//! | [`Future::try_race`] | `Result<T, E>` | Return on first `Ok`, reject on last Err
|
|
//!
|
|
//! [`Future::join`]: trait.Future.html#method.join
|
|
//! [`Future::try_join`]: trait.Future.html#method.try_join
|
|
//! [`Future::race`]: trait.Future.html#method.race
|
|
//! [`Future::try_race`]: trait.Future.html#method.try_race
|
|
|
|
pub use future::Future;
|
|
pub use pending::pending;
|
|
pub use poll_fn::poll_fn;
|
|
pub use ready::ready;
|
|
|
|
pub(crate) mod future;
|
|
mod pending;
|
|
mod poll_fn;
|
|
mod ready;
|
|
|
|
cfg_default! {
|
|
pub use timeout::{timeout, TimeoutError};
|
|
mod timeout;
|
|
}
|
|
|
|
cfg_unstable! {
|
|
pub use into_future::IntoFuture;
|
|
mod into_future;
|
|
}
|