How tokio-rs/mio works
Project Type and Purpose
• Mio is an open-source, low-level Rust library implementing the Reactor pattern for non-blocking I/O.
• It provides a minimal API for registering I/O handles (TCP/UDP/UDS sockets, pipes, etc.), polling for readiness events, and waking an event loop across multiple platforms (Linux, macOS, Windows, WASI).
File Structure and Architectural Layers
• Public API Layer (src/lib.rs, src/event, src/poll, src/net, src/io_source, src/token, src/waker)
• event/: Definitions for Event, Events, Interest
• poll.rs: The Poll struct, interface for registering I/O sources and polling
• net/: High-level socket types (TcpListener, TcpStream, UdpSocket, Uds) built atop IoSource
• waker.rs: Cross-platform user wake-up handle
• Core Abstractions
• IoSource: Trait wrapper around OS handles
• Registry: Internal structure in Poll that maps Token → IoSource with Interest flags
• Platform-Specific Implementation Layer (src/sys)
• sys/unix/selector: epoll, kqueue, poll implementations
• sys/windows: IOCP, wepoll strategy, named pipes, overlapped I/O
• sys/wasi: WASI bindings
• sys/shell: Fallback or “shell” implementations for unsupported platforms
• Examples & Tests
• examples/: Demo code for TCP and UDP servers
• tests/: End-to-end tests for each socket type, registry semantics, waker behavior
Key Architectural Patterns
• Reactor Pattern: Central Poll event loop multiplexes readiness notifications.
• Adapter Layering: Public API delegates to a unified Selector trait with multiple platform adapters.
• Zero-allocation event storage: Events buffer reused between polls.
• Token-based dispatch: Users supply opaque Token identifiers for mapping events to sources.
Components & Interactions (to illustrate
a. Application Code
• Uses Poll::new(), poll.registry().register(), poll.poll(&mut events, …)
b. Poll / Registry
• Maintains a table: Token → IoSource + Interest
• On poll(), calls the underlying Selector adapter
c. Selector Adapters
• Unix: epoll, kqueue, poll, stateless_io_source
• Windows: IOCP, wepoll, NamedPipe, Overlapped
• WASI: wasm-compatible polling
d. OS Kernel
• Supplies readiness events for FDs or handles
e. Waker
• Custom eventfd/pipe/kqueue/IOCP handle to wake the reactor