Async & Futures Highlights Summary

Every highlight bullet from the 11 pages in this section, gathered on one page and grouped by the page it came from.

The Rust Async Model

• An async block compiles to a state machine implementing Future, not a running task.
• Futures are lazy: nothing happens until something polls them.
• The standard library defines the Future trait but ships no executor to drive it.
• Pinning exists because await points can create self-referential structs the borrow checker cannot otherwise validate.
• async/await is syntax sugar over the same poll-based model you'd use to hand-write a Future.

Async Basics

• async fn returns a Future that must be driven by a runtime
• Futures are lazy until polled; dropping a future cancels work
• tokio::spawn schedules a task on the Tokio runtime
• tokio::join! runs futures concurrently on one task
• Blocking operations starve Tokio worker threads
• Use spawn_blocking for blocking I/O within async tasks

The Future Trait

• Every async block compiles to a type implementing Future
• Future::poll must not block and returns Poll::Ready or Poll::Pending
• Wakers notify the executor to re-poll a Pending future
• Pinning prevents moving self-referential futures after polling starts
• Never busy loop in poll; register a waker and return Pending
• Do not poll a future after it has returned Poll::Ready

Executors & Runtimes

• Futures are inert until an executor polls them
• Tokio provides executors, I/O reactors, timers, and thread pools
• Use #[tokio::main] to start an async binary
• Manually construct runtimes for non-main entry points
• Avoid nested block_on calls to prevent deadlocks
• Pick one async runtime per process, do not mix them

Pinning & Unpin

• Pin guarantees a value will not move after pinning
• Async futures are often self-referential, storing pointers into their own stack frame
• The pin! macro stack-pins a future without heap allocation
• Box::pin heap-allocates a future for owned storage
• Do not move !Unpin values after pin! or Box::pin
• async/await handles pinning automatically on the stack

async fn in Traits

• Rust 1.75+ supports async fn directly in traits with limitations
• The async-trait crate remains useful for dyn compatibility and older compilers
• Native async traits generate an associated Future return type (RPITIT)
• The async-trait macro boxes futures for dyn compatibility and object safety
• Use #[async_trait] for object-safe service boundaries like dyn UserRepo
• Prefer generics (impl Trait) in hot paths to avoid boxing overhead

Streams

• Stream is the async version of Iterator, driven by .await
• Use streams for paginated APIs, WebSockets, file chunks, and event feeds
• Channel receivers adapt to Stream via ReceiverStream
• StreamExt provides ergonomic methods like map, filter, and buffer_unordered
• Avoid unbounded stream production to prevent memory exhaustion
• Always drive a stream to completion, cancel it, or drop it explicitly

Combining Futures

• Use join! for concurrent, independent async work
• Use select! to get the first completion or cancellation
• timeout wraps any future with a deadline
• join! waits for all branches and returns a tuple of results
• select! resolves when one branch completes, cancelling others
• try_join! short-circuits on the first Err from Result futures

Cancellation & Timeouts

• Cancellation in Rust async is cooperative, stopping at the next await point
• Dropping a future or calling JoinHandle::abort cancels in-flight work
• Use timeout for HTTP client deadlines, graceful shutdown, or request limits
• CancellationToken propagates cancellation across a tree of related tasks
• CPU-bound loops need yield_now().await or cancel checks to enable cancellation
• Cleanup in Drop impls or defer patterns when cancellation must release resources

Blocking in Async

• Blocking syscalls on Tokio worker threads stall all tasks
• Offload blocking work to spawn_blocking, Rayon, or dedicated thread pools
• spawn_blocking runs a closure on a separate blocking thread pool
• Use tokio::fs or spawn_blocking for sync file I/O in async contexts
• Avoid calling std::thread::sleep; use tokio::time::sleep.await instead
• Do not await async work from inside spawn_blocking to prevent deadlocks

Async Best Practices

• Libraries expose async fn, binaries own tokio::main for one runtime per process
• Prefer native async drivers; avoid spawn_blocking as a default
• Never std::thread::sleep or sync I/O on worker threads
• Never hold std::sync::MutexGuard across .await
• Prefer join! for independent awaits on one task
• Await or abort every JoinHandle to prevent leaked background tasks