Crate futures_concurrency
source ·Expand description
Concurrency extensions for Future
and Stream
(also known as AsyncIterator
).
Companion library for the “Futures Concurrency” blog post series:
- Futures Concurrency I: Introduction
- Futures Concurrency II: A Trait Approach
- Futures Concurrency III:
select!
- Futures Concurrency IV: Join Semantics
The purpose of this library is to serve as a staging ground for what
eventually may become the futures concurrency methods provided by the
stdlib. See the future
and stream
submodules for more.
Operations
This library provides the following operations on arrays, vecs, and tuples:
future::Join
: Wait for all futures to complete.future::TryJoin
: Wait for all futures to complete successfully, or abort early on error.future::Race
: Wait for the first future to complete.future::RaceOk
: Wait for the first successful future to complete.stream::Chain
: Takes multiple streams and creates a new stream over all in sequence.stream::Merge
: Combines multiple streams into a single stream of all their outputs.stream::Zip
: ‘Zips up’ multiple streams into a single stream of pairs.
Examples
Concurrently await multiple heterogenous futures:
use futures_concurrency::prelude::*;
use futures_lite::future::block_on;
use std::future;
block_on(async {
let a = future::ready(1u8);
let b = future::ready("hello");
let c = future::ready(3u16);
assert_eq!((a, b, c).join().await, (1, "hello", 3));
})
Limitations
Because of orphan rules this library can’t implement everything the stdlib can. The missing implementations are:
impl<T> IntoFuture for Vec<T>
impl<T, const N: usize> IntoFuture for [T; N]
impl<T..> IntoFuture for (T..)
impl<T> IntoAsyncIterator for Vec<T>
impl<T, const N: usize> IntoAsyncIterator for [T; N]
impl<T..> IntoAsyncIterator for (T..)
This would enable containers of futures to directly be .await
ed to get
merge
semantics. Or containers of async iterators to be passed directly to
for..await in
loops to be iterated over using merge
semantics. This would
remove the need to think of “merge” as a verb, and would enable treating
sets of futures concurrently.
Modules
- Helper functions and types for fixed-length arrays.
- Asynchronous basic functionality.
- The futures concurrency prelude.
- Composable asynchronous iteration.
- Helper functions and types for contiguous growable array type with heap-allocated contents, written
Vec<T>
.