Phase 2 of 4 · Study weeks 5-8
Async, cancellation and the server
This phase makes the second checkpoint possible: a server that frames requests, bounds its work and survives a cancelled future.
Topics every week
- Week 58 h
asyncandawait- Futures and what drives them
- Tokio tasks and the runtime
- Blocking work and
spawn_blocking
Hand inA TCP echo that handles 10,000 connections and a proof that blocking stalls it
- Week 68 h
- Framing and protocol design
- Backpressure with bounded channels
- Limits: connections, body size and timeouts
Hand inA framed protocol with the limits and a test for each
- Week 78 h
- Cancellation safety
select!and its hazards- Shutdown and
CancellationToken - Holding locks across
await
Hand inA write path that stays consistent when its future is dropped
- Week 88 h
- Tracing with
tracing - Error handling at the edge
- Testing with a fake clock and fake network
- Graceful shutdown
Hand inCheckpoint 2, with the cancellation test and the drain test
- Tracing with
Practice projects
- Practice 1, the blocked runtime (Week 5): run a blocking call inside an async task. Done when: a trace shows other tasks stalled, and moving the call to
spawn_blockingremoves the stall. - Practice 2, the slow client (Week 6): open 300 connections that send one byte a second. Done when: the limit and the idle timeout keep the server responsive and a test proves the 257th connection is refused.
- Practice 3, the dropped future (Week 7): drop a write future between two steps. Done when: the log is consistent after the drop, and a test shows what happens without the fix.
- Optional, a deterministic network test: run the server against a simulated network. Done when: a dropped packet and a delayed reply each have a test.
GitHub repos to study
Existence and last commit were checked on 22 Nov 2026 by shallow clone. Every repository below had a commit in the last 12 months.
| Repo | What to read | Week |
|---|---|---|
| tokio-rs/tokio | The scheduler, select! and the cancellation docs | 5 |
| tokio-rs/axum | How a service is built from small pieces and layers | 6 |
| tokio-rs/tracing | Spans, events and how context follows a task | 8 |
Milestone checkpoint
Build Checkpoint 2. Write the slow-client script and the cancellation test first and watch them fail. Add the limits, the cancellation-safe write and the shutdown path. Hand in the limit tests, the cancellation test, ADR-3 (the protocol and its limits) and ADR-4 (the shutdown and cancellation rules).
Check yourself
Answer each question in your head first, then open it to check.
What does an
async fnreturn, and when does it run?A future. Nothing runs until something polls it, usually the runtime after you.awaitor spawn it.Why does blocking inside an async task hurt other tasks?
A worker thread is stuck and cannot poll the other tasks assigned to it. Move blocking work tospawn_blockingor a separate thread.What does cancellation safety mean for a future?
Dropping the future at anyawaitleaves state consistent. A write that did half its work when dropped is not cancellation safe.Why is holding a
std::sync::Mutexacrossawaita problem?The guard stays held while the task waits, so other tasks block on it, and astdguard is notSend, so the future may not compile. Use a scoped lock or an async lock.Why use bounded channels?
A full channel pushes back on the producer. An unbounded channel moves the overload into memory.