# tokio-rs/mio architecture

> Architecture diagram of the GitHub repository tokio-rs/mio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tokio-rs/mio
- Repository: https://github.com/tokio-rs/mio

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        App["Application Code & Examples/Tests"]:::external
    end

    subgraph "Public API Layer"
        Lib["lib.rs"]:::api
        EventMod["event/*"]:::api
        Poll["poll.rs"]:::api
        Token["token.rs"]:::api
        IoSource["io_source.rs"]:::api
        Waker["waker.rs"]:::api
        Net["net/*"]:::api
    end

    subgraph "Core Abstractions"
        Registry["Registry (in Poll)"]:::core
        Selector["Selector Trait"]:::core
    end

    subgraph "Platform Adapters"
        subgraph Shell
            ShellSel["selector.rs"]:::adapter
            ShellTCP["tcp.rs"]:::adapter
            ShellUDP["udp.rs"]:::adapter
            ShellUDS["uds.rs"]:::adapter
            ShellWaker["waker.rs"]:::adapter
        end
        subgraph Unix
            Epoll["epoll.rs"]:::adapter
            Kqueue["kqueue.rs"]:::adapter
            PollImpl["poll.rs"]:::adapter
            Stateless["stateless_io_source.rs"]:::adapter
            Ufd["eventfd.rs"]:::adapter
            KqWaker["kqueue.rs"]:::adapter
            PipeWaker["pipe.rs"]:::adapter
        end
        subgraph Windows
            WinSel["selector.rs"]:::adapter
            IOCP["iocp.rs"]:::adapter
            AFD["afd.rs"]:::adapter
            EventWin["event.rs"]:::adapter
            Handle["handle.rs"]:::adapter
            Iosb["io_status_block.rs"]:::adapter
            NamedPipe["named_pipe.rs"]:::adapter
            WinNet["net.rs"]:::adapter
            WinTCP["tcp.rs"]:::adapter
            WinUDP["udp.rs"]:::adapter
            Overlapped["overlapped.rs"]:::adapter
            WinWaker["waker.rs"]:::adapter
        end
        WASI["mod.rs"]:::adapter
    end

    Kernel["OS Kernel"]:::external

    %% Connections
    App -->|"uses API"| Lib
    Lib --> EventMod
    Lib --> Poll
    Lib --> Token
    Lib --> IoSource
    Lib --> Net
    Lib --> Waker

    Poll --> Registry
    Poll --> Selector
    Registry --> IoSource
    Registry --> Token

    Selector --> ShellSel
    Selector --> Epoll
    Selector --> Kqueue
    Selector --> PollImpl
    Selector --> Stateless
    Selector --> WinSel
    Selector --> IOCP
    Selector --> WASI

    ShellSel --> Kernel
    ShellTCP --> ShellSel
    ShellUDP --> ShellSel
    ShellUDS --> ShellSel
    ShellWaker --> ShellSel

    Epoll --> Kernel
    Kqueue --> Kernel
    PollImpl --> Kernel
    Stateless --> Kernel
    Ufd --> Kernel
    KqWaker --> Kernel
    PipeWaker --> Kernel

    WinSel --> Kernel
    IOCP --> Kernel
    AFD --> Kernel
    EventWin --> Kernel
    Handle --> Kernel
    Iosb --> Kernel
    NamedPipe --> Kernel
    WinNet --> Kernel
    WinTCP --> Kernel
    WinUDP --> Kernel
    Overlapped --> Kernel
    WinWaker --> Kernel

    WASI --> Kernel

    Waker --> Selector
    Selector --> Poll
    Kernel -->|"events"| Selector
    Selector -->|"dispatch events"| Poll
    Poll -->|"returns Events"| App

    %% Click Events
    click Lib "https://github.com/tokio-rs/mio/blob/master/src/lib.rs"
    click EventMod "https://github.com/tokio-rs/mio/tree/master/src/event"
    click Poll "https://github.com/tokio-rs/mio/blob/master/src/poll.rs"
    click Token "https://github.com/tokio-rs/mio/blob/master/src/token.rs"
    click IoSource "https://github.com/tokio-rs/mio/blob/master/src/io_source.rs"
    click Waker "https://github.com/tokio-rs/mio/blob/master/src/waker.rs"
    click Net "https://github.com/tokio-rs/mio/blob/master/src/net/mod.rs"
    click ShellSel "https://github.com/tokio-rs/mio/blob/master/src/sys/shell/selector.rs"
    click ShellTCP "https://github.com/tokio-rs/mio/blob/master/src/sys/shell/tcp.rs"
    click ShellUDP "https://github.com/tokio-rs/mio/blob/master/src/sys/shell/udp.rs"
    click ShellUDS "https://github.com/tokio-rs/mio/blob/master/src/sys/shell/uds.rs"
    click ShellWaker "https://github.com/tokio-rs/mio/blob/master/src/sys/shell/waker.rs"
    click Epoll "https://github.com/tokio-rs/mio/blob/master/src/sys/unix/selector/epoll.rs"
    click Kqueue "https://github.com/tokio-rs/mio/blob/master/src/sys/unix/selector/kqueue.rs"
    click PollImpl "https://github.com/tokio-rs/mio/blob/master/src/sys/unix/selector/poll.rs"
    click Stateless "https://github.com/tokio-rs/mio/blob/master/src/sys/unix/selector/stateless_io_source.rs"
    click Ufd "https://github.com/tokio-rs/mio/blob/master/src/sys/unix/waker/eventfd.rs"
    click KqWaker "https://github.com/tokio-rs/mio/blob/master/src/sys/unix/waker/kqueue.rs"
    click PipeWaker "https://github.com/tokio-rs/mio/blob/master/src/sys/unix/waker/pipe.rs"
    click WinSel "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/selector.rs"
    click IOCP "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/iocp.rs"
    click AFD "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/afd.rs"
    click EventWin "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/event.rs"
    click Handle "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/handle.rs"
    click Iosb "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/io_status_block.rs"
    click NamedPipe "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/named_pipe.rs"
    click WinNet "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/net.rs"
    click WinTCP "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/tcp.rs"
    click WinUDP "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/udp.rs"
    click Overlapped "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/overlapped.rs"
    click WinWaker "https://github.com/tokio-rs/mio/blob/master/src/sys/windows/waker.rs"
    click WASI "https://github.com/tokio-rs/mio/blob/master/src/sys/wasi/mod.rs"

    %% Styles
    classDef api fill:#BBDEFB,stroke:#1E88E5;
    classDef core fill:#C8E6C9,stroke:#388E3C;
    classDef adapter fill:#FFE0B2,stroke:#F57C00;
    classDef external fill:#CFD8DC,stroke:#607D8B;
```
