# tokio-rs/tokio-uring architecture

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

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

## Overview

##### Main Components
- Runtime Environment: At the heart is the “tokio-uring” runtime. It blends the traditional Tokio runtime with an io_uring driver. This component is responsible for starting asynchronous tasks (via tokio_uring::start) and managing event loops.
- I/O Subsystem: This layer is split into several modules:
- IO Module (src/io): Contains operations for reading, writing, connecting, accepting, and even more specialized activities like zero-copy sends (send_zc, sendmsg_zc). It orchestrates the submission of operations to the kernel.
- File System Module (src/fs): Implements filesystem operations such as opening files, creating directories, linking (symlink), and getting file statistics.
- Network Module (src/net): Manages TCP, UDP, and Unix socket operations. Submodules and files under tcp, udp, and unix encapsulate listeners and stream operations.
- Buffer Management: The “buf” component (under src/buf) provides different buffering strategies:
- Bounded & Fixed buffers, including special submodules (like fixed/plumbing, pool, registry). These handle the life cycle of buffers which are passed by ownership into kernel operations and then returned.
- Operational (Op) and Driver Layers:
- Runtime Driver (src/runtime/driver): Drives asynchronous operations and integrates the op scheduler. The “op” modules manage the queuing, dispatching, and completion tracking.
- Runtime Context (src/runtime/context): Maintains context across asynchronous tasks within the runtime.
- Supporting Components: Modules such as “future.rs” (for custom async future implementations) and “io_buf.rs” (for I/O buffer abstractions) support the main components.
- Testing/Examples/Benchmarks: Though not a part of the main system, they are useful for demonstrating usage patterns and performance characteristics but do not affect the core runtime architecture.

##### Relationships and Interactions
- User Application Layer: At the top, user code (as shown in the README examples) calls tokio_uring::start to begin the runtime.
- Runtime Integration: The start function initializes the tokio-uring runtime, which internally sets up the Tokio runtime alongside the io_uring driver.
- I/O Requests: Once running, asynchronous I/O operations (filesystem reads, writes, network connections) pass through the IO, FS, and Network modules. Each of these interacts with the Buffer Management layer to supply or receive buffers.
- Driver and Op Scheduling: These operations are delegated to the runtime driver and its op modules that submit requests to the kernel via io_uring and then asynchronously wait for completion.

##### Architectural Patterns and Design Principles
- Asynchronous & Non-blocking: The design leverages asynchronous Rust programming, using futures and a custom runtime.
- Layered/Microkernel-like Approach: The separation between the runtime layer, I/O module, and buffers emphasizes isolation of concerns.
- Modularity: Each component (buffers, filesystem, network, runtime) is separated into its own folder/module, making the architecture easier to extend or modify.

##### Relevant Technologies and Frameworks
- Rust and Cargo: Standard tooling for building and testing the crate.
- Tokio: The foundation for asynchronous programming, which is extended by tokio-uring.
- io_uring: The underlying Linux kernel mechanism for asynchronous I/O.
- Criterion for benchmarks: Found in the benches directory.
- GitHub workflows: For CI.

## Diagram (Mermaid)

```mermaid
graph TD
    UA["User Application"]:::user

    subgraph "Tokio-uring Runtime"
        TR["Tokio-uring Runtime"]:::runtime
        RC["Runtime Context"]:::runtime
        RD["Runtime Driver"]:::runtime
    end

    subgraph "I/O Operations"
        IO["IO Module"]:::iosys
        FS["Filesystem Module"]:::iosys
        NM["Network Module"]:::iosys
        subgraph "Network Details"
            TCP["TCP Operations"]:::iosys
            UDP["UDP Operations"]:::iosys
            UNIX["Unix Socket Operations"]:::iosys
        end
    end

    subgraph "Buffer Management"
        BM["Buffer Management"]:::buffer
        FB["Fixed/Broadcast Buffers"]:::buffer
    end

    K["Kernel (io_uring)"]:::kernel

    SC["Custom Futures"]:::supporting

    %% Connections
    UA -->|"calls"| TR
    TR -->|"dispatch"| IO
    TR -->|"dispatch"| FS
    TR -->|"dispatch"| NM
    SC -->|"support"| TR
    SC -->|"support"| RC

    IO -->|"usesBuffer"| BM
    FS -->|"usesBuffer"| BM
    NM -->|"usesBuffer"| BM

    IO -->|"submit"| RD
    FS -->|"submit"| RD
    NM -->|"submit"| RD

    NM -->|"contains"| TCP
    NM -->|"contains"| UDP
    NM -->|"contains"| UNIX

    RD -->|"op_submit"| K
    K -->|"completion"| RD
    BM -->|"bufferReturn"| IO
    BM -->|"bufferReturn"| FS
    BM -->|"bufferReturn"| NM

    %% Styles
    classDef runtime fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef iosys fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef buffer fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef kernel fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef supporting fill:#E6A9EC,stroke:#333,stroke-width:2px;
    classDef user fill:#FFE599,stroke:#333,stroke-width:2px;

    %% Click Events
    click TR "https://github.com/tokio-rs/tokio-uring/blob/master/src/lib.rs"
    click RC "https://github.com/tokio-rs/tokio-uring/blob/master/src/runtime/context.rs"
    click RD "https://github.com/tokio-rs/tokio-uring/tree/master/src/runtime/driver"
    click IO "https://github.com/tokio-rs/tokio-uring/tree/master/src/io"
    click FS "https://github.com/tokio-rs/tokio-uring/tree/master/src/fs"
    click TCP "https://github.com/tokio-rs/tokio-uring/tree/master/src/net/tcp"
    click UDP "https://github.com/tokio-rs/tokio-uring/blob/master/src/net/udp.rs"
    click UNIX "https://github.com/tokio-rs/tokio-uring/tree/master/src/net/unix"
    click BM "https://github.com/tokio-rs/tokio-uring/tree/master/src/buf"
    click FB "https://github.com/tokio-rs/tokio-uring/tree/master/src/buf/fixed"
    click SC "https://github.com/tokio-rs/tokio-uring/blob/master/src/future.rs"
```
