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:

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 all futures to complete successfully, or abort early on error.
  • 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.

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 .awaited 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.

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));
})

Modules

  • array
    Helper functions and types for fixed-length arrays.
  • future
    Asynchronous basic functionality.
  • prelude
    The futures concurrency prelude.
  • stream
    Composable asynchronous iteration.
  • vec
    A contiguous growable array type with heap-allocated contents, written Vec<T>.