Async Rust Guidebook

Learn asynchronous Rust from observable programs, then follow the machinery only as far as it explains the behavior.

Async Rust combines several ideas that are easier to understand separately:

• a future represents work that may not be complete yet;
• .await allows one task to pause without blocking its executor thread;
• a runtime polls tasks and connects them to timers, networking, and wakeups;
• concurrency lets multiple operations make progress during overlapping time;
• cancellation often happens by dropping a future before it completes.

This book should introduce each idea through a complete program and its observed output before explaining implementation machinery.

consumer program
    → observed order and timing
    → public Future or runtime contract
    → one source-level mechanism
    → cancellation and ownership consequences

The current pages are a chapter skeleton for the next author. The navigation, typography, syntax colors, and responsive page controls are already configured.

Start with how to read the examples →

How to Read the Examples

Every finished chapter should contain:

1. a concrete consumer goal;
2. a complete program visible by default;
3. observed stdout as if the reader ran it;
4. a timeline when ordering materially aids understanding;
5. the public contract (Future, Send, ownership, cancellation safety);
6. one changed input or failure case;
7. only the source needed to explain visible behavior.

Do not require the reader to run code. Programs should remain runnable so the book can verify its claims, but commands belong in contributor documentation, not in the teaching flow.

Provider-source excerpts may eventually be folded. Consumer programs and their output should remain visible.

Distinctions to preserve

• async fn does not start a background thread.
• Calling an async function creates a future; polling drives it.
• .await suspends the current task, not necessarily the operating-system thread.
• Concurrent work is not automatically parallel work.
• spawn changes ownership and lifetime requirements.
• Dropping a future is the ordinary cancellation mechanism, but cancellation safety depends on the operation.
• Blocking work inside an async task can block an executor worker.

Evidence convention

Pin Rust and dependency versions before claiming exact diagnostics or runtime formatting. Timing examples should explain ordering relationships without depending on exact millisecond measurements.

An Async Function Returns a Future

Chapter placeholder: begin with a complete program proving that calling an async function does not run its body until the returned future is polled.

Primary question: what value does an async fn call return, and who drives it?

.await Suspends One Task

Chapter placeholder: show two operations making progress while one awaits a timer, then contrast this with std::thread::sleep inside async code.

Primary question: what pauses at an .await point, and what remains free to run?

Concurrency Is Not Parallelism

Chapter placeholder: compare sequential awaits, join!, and CPU-bound work.

Primary question: when does overlapping waiting help, and when are worker threads or Rayon the appropriate abstraction?

Spawning and Task Ownership

Chapter placeholder: show how tokio::spawn changes Send, 'static, result, and panic boundaries.

Primary question: why can an awaited future borrow locally while a spawned task usually must own its captured data?

Channels and Backpressure

Chapter placeholder: use a bounded channel to show queue capacity, waiting, closure by dropping senders, and receiver ownership.

Primary question: how does the channel API represent flow control and shutdown?

select! and Cancellation

Chapter placeholder: race an operation with cancellation and explain what happens to the losing future.

Primary question: when is dropping partially completed asynchronous work safe?

What the Runtime Provides

Chapter placeholder: separate the language-level Future trait from executor, reactor, timer, networking, and task-spawning services supplied by a runtime.

Primary question: which parts of async Rust belong to the language and standard library, and which come from Tokio or another runtime?

Async I/O Boundaries

Chapter placeholder: contrast buffered whole-body convenience with streaming reads and writes, including partial progress and cancellation.

Primary question: how do async I/O APIs expose work that may complete in pieces?

A Future from Call Site to Poll

Chapter placeholder: follow one small future from an async fn call through .await, Future::poll, Context, Waker, and the executor’s ready queue.

Stop before platform-specific reactor internals unless they explain an observed consumer behavior.