From bede90e01f99a51c73cd2452ca2835fcb3b7aaee Mon Sep 17 00:00:00 2001 From: Rodrigo Rejala Date: Sat, 11 Apr 2026 12:03:08 -0300 Subject: [PATCH] fix(ch02): enhance Future diagram with Reactor and OS --- async-book/src/ch02-the-future-trait.md | 38 ++++++++++++++++--------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/async-book/src/ch02-the-future-trait.md b/async-book/src/ch02-the-future-trait.md index aa5797d..c02c696 100644 --- a/async-book/src/ch02-the-future-trait.md +++ b/async-book/src/ch02-the-future-trait.md @@ -30,22 +30,34 @@ That's it. A `Future` is anything that can be *polled* — asked "are you done y ```mermaid sequenceDiagram participant E as Executor - participant F as Future - participant R as Resource (I/O) + participant F as Future (Task) + participant OS as Operating System
(e.g., epoll/kqueue) + participant R as Reactor (Runtime) - E->>F: poll(cx) - F->>R: Check: is data ready? - R-->>F: Not yet - F->>R: Register waker from cx - F-->>E: Poll::Pending + E->>F: Calls poll(cx) + Note right of F: Future attempts operation + F->>OS: Syscall (e.g., read TCP socket) + OS-->>F: Returns Error: Not Ready + + F->>R: Registers: (Waker) + F-->>E: Returns Poll::Pending + Note left of E: Task is moved out
of run queue - Note over R: ... time passes, data arrives ... + E->>E: (Executor runs other tasks OR sleeps) + R->>OS: epoll_wait() / Polls OS for events - R->>E: waker.wake() — "I'm ready!" - E->>F: poll(cx) — try again - F->>R: Check: is data ready? - R-->>F: Yes! Here's the data - F-->>E: Poll::Ready(data) + Note right of OS: (Sometime Later) New data arrives + OS-->>R: Wakes Reactor: data is NOW READY + + R->>R: Reactor finds Waker + R->>E: Calls Waker::wake() + Note right of E: Task is pushed back
to Executor's run queue + + E->>F: Calls poll(cx) again + Note right of F: Future attempts operation again + F->>OS: Syscall (e.g., read TCP socket) + OS-->>F: Success: Returns Data Buffer + F-->>E: Returns Poll::Ready(Data) ``` Let's break down each piece: