Skip to content

Async

One line: async turns a function into a value that does nothing until something polls it — std gives you that value and the syntax, and a runtime such as Tokio supplies everything that actually runs it.

The section has two parts. The basics are what the language and std define on their own: the Future trait, what async fn and .await compile to, and the mistakes people make in the first week. Building minidb is a fifteen-chapter course that turns a small in-memory store into a TCP server on Tokio, one production problem at a time — sharing state, cancellation, backpressure, shutdown, durability, framing, and testing all of it.

These pages are stubs — outlines with the questions each finished page has to answer, and no runnable example behind them yet. See Adding a lesson for what that means and how a page graduates.

The basics

Lesson Level What it will teach
What a future is 201 One trait, one method, and nothing happens until somebody calls it
async fn and .await 201 A function that returns a state machine, and the suspension point where its locals are stored
Common async pitfalls 201 The mistakes that compile — each one pointing at the chapter that fixes it

Building minidb

Chapter Level What it will teach
The course outline — What minidb is, and the order the fifteen chapters build it in
1. The Tokio runtime 201 What Tokio adds to the language, and enough Future, poll and Pin to reason about it
2. Tasks 201 tokio::spawn, Send + 'static, join!, JoinSet and spawn_blocking
3. Building the server 201 An accept loop, a line protocol, one task per connection
4. Who owns the state 201 → 301 Arc<Mutex<Store>> against an actor task, measured under contention
5. Cancellation 301 Dropping a future, timeout, select!, CancellationToken, and cancel safety
6. Backpressure 301 Bounded channels, wait-refuse-or-drop, and where a Semaphore permit is taken
7. Shutdown and supervision 301 Draining connections before the store, and what to do when a task dies on its own
8. Testing async code 301 A paused clock, an in-memory socket, and spans asserted as data
9. Durability across restarts 301 A write-ahead log, group commit, and replay on startup
10. AsyncRead and AsyncWrite 301 The poll-level IO contract, ReadBuf, and a byte-counting wrapper
11. Codecs and framing 301 A length-prefixed frame with Decoder, Encoder and Framed
12. Streams, sinks, and pipelining 301 Split halves, several requests in flight, responses kept in order
13. Async functions in traits 301 Pluggable durability, the missing Send bound, and what dyn allows
14. Diagnosing a stuck runtime 301 tokio-console, runtime metrics, and the sync–async bridges that fail quietly
15. Testing against a hostile network 301 turmoil: latency, dropped connections and partitions inside a unit test

How these pages will be checked

The basics fit the library's oldest rule — one .rs file compiled by rustc with no dependencies: Future, Pin, Context and a do-nothing Waker::noop() are all in std, so a future that prints nothing until its first poll can be an ordinary answer-keyed example. Tokio is a crate, so the course chapters take the other route Adding a lesson now describes: a Cargo workspace in the lesson's demo/ folder, with a committed Cargo.lock, run by tools/run_cargo_demos.py against a recorded key — the way Procedural macros is checked. Output that depends on timing or the network (chapters 5, 6 and 15) still has to be made deterministic first, with the paused clock and the simulated network the course itself builds.

Where the rest of it is

Po polsku

Programowanie asynchroniczne w Ruscie ma dwie warstwy i warto je rozdzielić od pierwszego dnia. Język i biblioteka standardowa dają tylko future (w polskich tekstach zwykle bez tłumaczenia; „przyszłość” się nie przyjęła) oraz składnię async/.await — wartość, która sama z siebie nic nie robi. Wszystko, co ją faktycznie wykonuje, czyli planista zadań, obsługa gniazd i zegary, pochodzi ze środowiska uruchomieniowego (runtime), a najpopularniejszym jest crate tokio. Pierwsza część działu dotyczy tej pierwszej warstwy; druga to kurs, w którym mały magazyn danych minidb staje się serwerem TCP na Tokio.

Szukaj po polsku: programowanie asynchroniczne w Ruscie · async await rust · rust tokio tutorial · rust future poll