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

Modules

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