futures_concurrency/future/
mod.rs

1//! Asynchronous basic functionality.
2//!
3//! Please see the fundamental `async` and `await` keywords and the [async book]
4//! for more information on asynchronous programming in Rust.
5//!
6//! [async book]: https://rust-lang.github.io/async-book/
7//!
8//! # Examples
9//!
10//! ```
11//! use futures_concurrency::prelude::*;
12//! use futures_lite::future::block_on;
13//! use std::future;
14//!
15//! block_on(async {
16//!     // Await multiple similarly-typed futures.
17//!     let a = future::ready(1);
18//!     let b = future::ready(2);
19//!     let c = future::ready(3);
20//!     assert_eq!([a, b, c].join().await, [1, 2, 3]);
21//!    
22//!     // Await multiple differently-typed futures.
23//!     let a = future::ready(1u8);
24//!     let b = future::ready("hello");
25//!     let c = future::ready(3u16);
26//!     assert_eq!((a, b, c).join().await, (1, "hello", 3));
27//!
28//!     // It even works with vectors of futures, providing an alternative
29//!     // to futures-rs' `join_all`.
30//!     let a = future::ready(1);
31//!     let b = future::ready(2);
32//!     let c = future::ready(3);
33//!     assert_eq!(vec![a, b, c].join().await, vec![1, 2, 3]);
34//! })
35//! ```
36//!
37//! # Concurrency
38//!
39//! It's common for operations to depend on the output of multiple futures.
40//! Instead of awaiting each future in sequence it can be more efficient to
41//! await them _concurrently_. Rust provides built-in mechanisms in the library
42//! to make this easy and convenient to do.
43//!
44//! ## Infallible Concurrency
45//!
46//! When working with futures which don't return `Result` types, we
47//! provide two built-in concurrency operations:
48//!
49//! - `future::Merge`: wait for all futures in the set to complete
50//! - `future::Race`: wait for the _first_ future in the set to complete
51//!
52//! Because futures can be considered to be an async sequence of one, see
53//! the [async iterator concurrency][crate::stream#concurrency] section for
54//! additional async concurrency operations.
55//!
56//! ## Fallible Concurrency
57//!
58//! When working with futures which return `Result` types, the meaning of the
59//! existing operations changes, and additional `Result`-aware concurrency
60//! operations become available:
61//!
62//! |                             | __Wait for all outputs__ | __Wait for first output__ |
63//! | ---                         | ---                      | ---                       |
64//! | __Continue on error__       | `future::Merge`          | `future::RaceOk`
65//! | __Return early on error__   | `future::TryMerge`       | `future::Race`
66//!
67//! - `future::TryMerge`: wait for all futures in the set to complete _successfully_, or return on the first error.
68//! - `future::RaceOk`: wait for the first _successful_ future in the set to
69//!    complete, or return an `Err` if *no* futures complete successfully.
70//!
71#[doc(inline)]
72#[cfg(feature = "alloc")]
73pub use future_group::FutureGroup;
74pub use futures_ext::FutureExt;
75pub use join::Join;
76pub use race::Race;
77pub use race_ok::RaceOk;
78pub use try_join::TryJoin;
79pub use wait_until::WaitUntil;
80
81/// A growable group of futures which act as a single unit.
82#[cfg(feature = "alloc")]
83pub mod future_group;
84
85mod futures_ext;
86pub(crate) mod join;
87pub(crate) mod race;
88pub(crate) mod race_ok;
89pub(crate) mod try_join;
90pub(crate) mod wait_until;
futures_concurrency/future/mod.rs

futures_concurrency/future/
mod.rs
