Week 12 - Runtimes: Tokio Internals, Smol, Embassy¶
12.1 Conceptual Core¶
- A runtime is the executor + reactor + I/O driver that actually polls futures. The
Futuretrait is part ofcore; runtimes are external. - Executor = the part that picks which task to poll next.
- Reactor = the part that registers I/O readiness with the OS (epoll/kqueue/IOCP/io_uring).
- Task = a top-level future plus its scheduling metadata. Tasks are
'static.
12.2 Mechanical Detail-Tokio¶
Read the Tokio source tree in this order:
1. tokio/src/runtime/scheduler/multi_thread/ - the work-stealing scheduler. Each worker has a local LIFO/FIFO hybrid queue plus a global injection queue. Steals from peer queues on starvation.
2.tokio/src/runtime/io/driver.rs - wraps mio (which wraps epoll/kqueue/IOCP). I/O readiness wakes the relevant task's Waker.
3. tokio/src/runtime/time/ - hashed wheel timer fortokio::time::sleep.
4.tokio/src/sync/notify.rsandmutex.rs - async-aware synchronization. Note the intrusive linked list of waiters.
12.3 Mechanical Detail-Smol & async-std¶
- Smol's executor (
async-executor) is a simpler, single-file reactor. Read it; you can understand the entire stack in an afternoon. async-stdis now in maintenance; mention only for historical context.embassyfor embedded: an executor that runs on bare-metal Cortex-M without an OS. Uses interrupt-driven wakers.
12.4 Lab-"Roll-Your-Own Mini Executor"¶
Build a single-threaded executor in ~150 lines:
- A VecDeque<Arc<Task>> ready queue.
- Task holds a Mutex<Pin<Box<dyn Future>>> and implements ArcWake (or Wake on stable).
- block_on polls the root future; auxiliary spawn adds tasks.
- Run a small TCP echo server on top using polling (the same crate Smol uses) for I/O.
12.5 Idiomatic & Clippy Drill¶
clippy::redundant_async_block,clippy::manual_async_fn,clippy::should_panic_without_expect. Read the Tokio style guide and adopt its task-naming conventions.
12.6 Production Hardening Slice¶
- For your mini-executor, add a
tracingsubscriber and a panic hook that aborts the process (so a panicked task does not silently disappear). This is the same pattern Tokio'sunhandled_panic = "shutdown_runtime"enables-set it on every Tokio runtime you create.
Month 3 Capstone Deliverable¶
A concurrency-lab/ workspace:
1. spinlock-rs (week 9)-Loom-verified.
2. spsc-ring (week 10)-Loom + TSan + Criterion benches.
3. oneshot-rs (week 11)-runtime-agnostic, Miri-clean.
4. mini-exec (week 12)-under 200 LoC, runs the TCP echo demo.
CI gates: Loom, Miri, TSan (nightly), Criterion regression tracking. Add a one-page architectural ADR (Architectural Decision Record) for each crate explaining the ordering choices. ADRs become source-of-truth artifacts in subsequent months.