futures-rs

To use futures-rs in your project, add the futures crate to your Cargo.toml dependencies. Note that the current version of futures requires Rust 1.71 or later.

[dependencies]
futures = "0.3"

By default, futures-rs includes the standard library (std). If you are working in a bare metal or #[no_std] environment, you must disable default features to use the reduced API surface.

[dependencies]
futures = { version = "0.3", default-features = false }

A LocalPool is a single-threaded task pool used to multiplex multiple tasks onto a single thread. It is ideal for I/O-bound futures that perform minimal work between I/O actions. Because it is single-threaded, it supports spawning non-Send futures using spawn_local_obj via a LocalSpawner handle.

use futures::executor::LocalPool;

let mut pool = LocalPool::new();
// ... spawn tasks ...
pool.run();

The futures crate provides the fundamental building blocks for asynchronous programming in Rust:

• Futures: Single eventual values produced by asynchronous computations (similar to Promises in JavaScript).
• Streams: A series of values produced asynchronously over time.
• Sinks: Support for asynchronous writing of data.
• Executors: Responsible for running asynchronous tasks.
• Asynchronous I/O: Abstractions for reading and writing data asynchronously.
• Cross-task communication: Channels for sending data between tasks.

futures-util provides essential extension traits and combinators for working with asynchronous primitives.

• Futures: Use FutureExt and TryFutureExt to access combinators that transform or manage Futures.
• Streams: Use StreamExt and TryStreamExt to manipulate Streams (sequences of values).
• Sinks: Use SinkExt to manage Sinks (consumers of values).

Note: Most combinators are marked #[must_use], meaning they do nothing unless you .await them or poll them.

Use ThreadPool::new() to create a general-purpose thread pool that multiplexes tasks onto a fixed number of worker threads. The number of threads defaults to the number of available CPU cores. This type is available only when the thread-pool feature is enabled.

Note: ThreadPool is a clonable handle; cloning it creates a new reference to the same pool, not a new pool.

use futures::executor::ThreadPool;

let pool = ThreadPool::new().unwrap();

To quickly access the most commonly used traits and types in the crate, import the prelude. This includes common extension traits like StreamExt, SinkExt, FutureExt, and TryFutureExt.

use futures::prelude::*;

In testing scenarios, you can use new_count_waker to create a Waker that tracks how many times it has been awoken. This function returns a tuple containing the Waker and an AwokenCount handle used to inspect the wake count.

use futures_test::task::new_count_waker;

let (waker, count) = new_count_waker();

assert_eq!(count, 0);

waker.wake_by_ref();
waker.wake();

assert_eq!(count, 2);

The #[futures_test::test] attribute allows you to write asynchronous test functions directly. It automatically wraps the async function in futures_executor::block_on, running the generated future to completion. This is a convenient alternative to manually calling block_on inside a standard #[test] function.

#[futures_test::test]
async fn my_test() {
    let fut = async { true };
    assert!(fut.await);
}

The Abortable<T> wrapper allows you to remotely short-circuit a future or stream. You can control the abortion using an AbortHandle. When aborted, an Abortable future returns Err(Aborted), and an Abortable stream returns None (completes).

# futures::executor::block_on(async {
# use futures::future::{Abortable, AbortHandle, Aborted};

// Usage with futures:
let (abort_handle, abort_registration) = AbortHandle::new_pair();
let future = Abortable::new(async { 2 }, abort_registration);
abort_handle.abort();
assert_eq!(future.await, Err(Aborted));

# use futures::stream::{self, StreamExt};
// Usage with streams:
let (abort_handle, abort_registration) = AbortHandle::new_pair();
let mut stream = Abortable::new(stream::iter(vec![1, 2, 3]), abort_registration);
abort_handle.abort();
assert_eq!(stream.next().await, None);
# });

The PanicSpawner is a testing utility provided by futures-test that implements the Spawn trait but panics whenever a task is attempted to be spawned. This is useful for verifying that your code correctly handles or avoids spawning tasks in specific scenarios.

use futures::task::SpawnExt;
use futures_test::task::PanicSpawner;

let spawn = PanicSpawner::new();
spawn.spawn(async { })?; // This call will panic
# Ok::<(), Box<dyn std::error::Error>>(())