Module future

Asynchronous basic functionality.

Please see the fundamental async and await keywords and the async book for more information on asynchronous programming in Rust.

Examples

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

block_on(async {
    // Await multiple similarly-typed futures.
    let a = future::ready(1);
    let b = future::ready(2);
    let c = future::ready(3);
    assert_eq!([a, b, c].join().await, [1, 2, 3]);
    
    // Await multiple differently-typed futures.
    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));

    // It even works with vectors of futures, providing an alternative
    // to futures-rs' `join_all`.
    let a = future::ready(1);
    let b = future::ready(2);
    let c = future::ready(3);
    assert_eq!(vec![a, b, c].join().await, vec![1, 2, 3]);
})

Concurrency

It’s common for operations to depend on the output of multiple futures. Instead of awaiting each future in sequence it can be more efficient to await them concurrently. Rust provides built-in mechanisms in the library to make this easy and convenient to do.

Infallible Concurrency

When working with futures which don’t return Result types, we provide two built-in concurrency operations:

• future::Merge: wait for all futures in the set to complete
• future::Race: wait for the first future in the set to complete

Because futures can be considered to be an async sequence of one, see the async iterator concurrency section for additional async concurrency operations.

Fallible Concurrency

When working with futures which return Result types, the meaning of the existing operations changes, and additional Result-aware concurrency operations become available:

	Wait for all outputs	Wait for first output
Continue on error	future::Merge	future::RaceOk
Return early on error	future::TryMerge	future::Race

• future::TryMerge: wait for all futures in the set to complete successfully, or return on the first error.
• future::RaceOk: wait for the first successful future in the set to complete, or return an Err if no futures complete successfully.

Modules

• future_group
  A growable group of futures which act as a single unit.

Structs

• FutureGroup
  A growable group of futures which act as a single unit.
• WaitUntil
  Suspends a future until the specified deadline.

Traits

• FutureExt
  An extension trait for the Future trait.
• Join
  Wait for all futures to complete.
• Race
  Wait for the first future to complete.
• RaceOk
  Wait for the first successful future to complete.
• TryJoin
  Wait for all futures to complete successfully, or abort early on error.