Crate futures

Abstractions for asynchronous programming.

This crate provides a number of core abstractions for writing asynchronous code:

• Futures are single eventual values produced by asynchronous computations. Some programming languages (e.g. JavaScript) call this concept “promise”.
• Streams represent a series of values produced asynchronously.
• Sinks provide support for asynchronous writing of data.
• Executors are responsible for running asynchronous tasks.

The crate also contains abstractions for asynchronous I/O and cross-task communication.

Underlying all of this is the task system, which is a form of lightweight threading. Large asynchronous computations are built up using futures, streams and sinks, and then spawned as independent tasks that are run to completion, but do not block the thread running them.

The following example describes how the task system context is built and used within macros and keywords such as async and await!.

fn main() {
    let pool = ThreadPool::new().expect("Failed to build pool");
    let (tx, rx) = mpsc::unbounded::<i32>();

    // Create a future by an async block, where async is responsible for an
    // implementation of Future. At this point no executor has been provided
    // to this future, so it will not be running.
    let fut_values = async {
        // Create another async block, again where the Future implementation
        // is generated by async. Since this is inside of a parent async block,
        // it will be provided with the executor of the parent block when the parent
        // block is executed.
        //
        // This executor chaining is done by Future::poll whose second argument
        // is a std::task::Context. This represents our executor, and the Future
        // implemented by this async block can be polled using the parent async
        // block's executor.
        let fut_tx_result = async move {
            (0..100).for_each(|v| {
                tx.unbounded_send(v).expect("Failed to send");
            })
        };

        // Use the provided thread pool to spawn the generated future
        // responsible for transmission
        pool.spawn_ok(fut_tx_result);

        let fut_values = rx
            .map(|v| v * 2)
            .collect();

        // Use the executor provided to this async block to wait for the
        // future to complete.
        fut_values.await
    };

    // Actually execute the above future, which will invoke Future::poll and
    // subsequently chain appropriate Future::poll and methods needing executors
    // to drive all futures. Eventually fut_values will be driven to completion.
    let values: Vec<i32> = executor::block_on(fut_values);

    println!("Values={:?}", values);
}

The majority of examples and code snippets in this crate assume that they are inside an async block as written above.

Modules

• channel
  Asynchronous channels.
• executor
  Built-in executors and related tools.
• io
  Asynchronous I/O.
• lock
  Futures-powered synchronization primitives.
• never
  This module contains the Never type.
• prelude
  A “prelude” for crates using the futures crate.
• task
  Tools for working with tasks.

Macros

• join
  Polls multiple futures simultaneously, returning a tuple of all results once complete.
• pending
  A macro which yields to the event loop once.
• pin_mut
  Pins a value on the stack.
• poll
  A macro which returns the result of polling a future once within the current async context.
• ready
  Extracts the successful type of a Poll<T>.
• select
  Polls multiple futures and streams simultaneously, executing the branch for the future that finishes first. If multiple futures are ready, one will be pseudo-randomly selected at runtime. Futures directly passed to select! must be Unpin and implement FusedFuture.
• select_biased
  Polls multiple futures and streams simultaneously, executing the branch for the future that finishes first. Unlike select!, if multiple futures are ready, one will be selected in order of declaration. Futures directly passed to select_biased! must be Unpin and implement FusedFuture.
• stream_select
  Combines several streams, all producing the same Item type, into one stream. This is similar to select_all but does not require the streams to all be the same type. It also keeps the streams inline, and does not require Box<dyn Stream>s to be allocated. Streams passed to this macro must be Unpin.
• try_join
  Polls multiple futures simultaneously, resolving to a Result containing either a tuple of the successful outputs or an error.

Traits

• AsyncBufRead
  Read bytes asynchronously.
• AsyncBufReadExt
  An extension trait which adds utility methods to AsyncBufRead types.
• AsyncRead
  Read bytes asynchronously.
• AsyncReadExt
  An extension trait which adds utility methods to AsyncRead types.
• AsyncSeek
  Seek bytes asynchronously.
• AsyncSeekExt
  An extension trait which adds utility methods to AsyncSeek types.
• AsyncWrite
  Write bytes asynchronously.
• AsyncWriteExt
  An extension trait which adds utility methods to AsyncWrite types.
• Future
  A future represents an asynchronous computation obtained by use of async.
• FutureExt
  An extension trait for Futures that provides a variety of convenient adapters.
• Sink
  A Sink is a value into which other values can be sent, asynchronously.
• SinkExt
  An extension trait for Sinks that provides a variety of convenient combinator functions.
• Stream
  A stream of values produced asynchronously.
• StreamExt
  An extension trait for Streams that provides a variety of convenient combinator functions.
• TryFuture
  A convenience for futures that return Result values that includes a variety of adapters tailored to such futures.
• TryFutureExt
  Adapters specific to Result-returning futures
• TryStream
  A convenience for streams that return Result values that includes a variety of adapters tailored to such futures.
• TryStreamExt
  Adapters specific to Result-returning streams