Crate futures_concurrency

Concurrency extensions for Future.

Examples

use futures_lite::future::block_on;
use std::future::ready;
use futures_concurrency::prelude::*;

fn main() {
    block_on(async {
        // Await multiple similarly-typed futures.
        let fut = [ready(1u8), ready(2u8), ready(3u8)].join();
        let [a, b, c] = fut.await;
        println!("{} {} {}", a, b, c);

        // Await multiple differently-typed futures.
        let fut = (ready(1u8), ready("hello"), ready(3u8)).join();
        let (a, b, c) = fut.await;
        println!("{} {} {}", a, b, c);

        // It even works with vectors of futures, providing an alternative
        // to futures-rs' `join_all`.
        let numbers = std::iter::repeat(12u8).take(6);
        let fut: Vec<_> = numbers.map(ready).collect();
        println!("{:?}", fut.join().await);
    })
}

Progress

The following traits have been implemented.

• Join
• TryJoin
• Race
• TryRace

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?
Join	(T1, T2)	Wait for all to complete
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?
Join	(Result<T, E>, Result<T, E>)	Wait for all to complete
TryJoin	Result<(T1, T2), E>	Return on first Err, wait for all to complete
Race	Result<T, E>	Return on first value
Try_race	Result<T, E>	Return on first Ok, reject on last Err

Modules

array

Implementations for the Array type.

prelude

The futures concurrency prelude.

tuple

Implementations for the tuple type.

vec

Implementations for the Vec type.

Traits

Join

Wait for multiple futures to complete.