# tokio-rs/io-uring architecture

> Architecture diagram of the GitHub repository tokio-rs/io-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/io-uring
- Repository: https://github.com/tokio-rs/io-uring

## Overview

##### Main Components
- Public API & Library Core: Represented by the src/lib.rs along with modules like opcode.rs, register.rs, submit.rs, squeue.rs, and cqueue.rs. This is where the primary interface (e.g., the IoUring struct) is defined.
- System/Kernel Interface: The src/sys directory (with its sub-modules like sys.rs, sys_x86-64.rs, and sys_aarch64.rs) encapsulates the low-level system calls and platform-specific implementations.
- Types and Utilities: Modules such as types.rs and util.rs provide foundational types and helper functions used across the library.
- Examples, Tests, and Benchmarks: The examples directory, along with the io-uring-test and io-uring-bench directories, demonstrate application use, test correctness, and measure performance.
- Build and Configuration: Files such as Cargo.toml, build.rs, and the GitHub workflows in .github ensure the project is properly built, tested, and integrated with CI/CD systems.

##### Relationships and Interactions
- The Public API (e.g., IoUring from src/lib.rs) interacts with lower-level components, particularly by invoking functions from:
- The opcode module to create operation descriptors.
- Submission and completion queue modules (squeue.rs and cqueue.rs) to manage I/O submissions and completions.
- The sys module to wrap the actual system calls exposed by the Linux kernel.
- The OS/Kernel interface (in src/sys) abstracts away differences between architectures (x86-64 vs. aarch64).
- The examples and tests depend on the public API to validate correct behavior and use cases.
- The Cargo build scripts and configuration files ensure that the correct platform-specific code is built and that contributions are continuously integrated.

##### Architectural Patterns & Design Principles
- Abstraction: The library provides high-level abstractions over low-level, platform-specific system calls (using a set of modular Rust files for different responsibilities).
- Modular Separation: Each module (opcodes, submission, completion, system calls) has a clearly defined role. This separation ensures ease of testing (as seen in the io-uring-test directory) and benchmarking (via io-uring-bench).
- Platform Specialization: The use of separate modules for different CPU architectures in src/sys emphasizes clean separation between generic logic and platform-specific implementations.
- Safety & Concurrency: Though not explicitly diagrammed, the design emphasizes Rust’s safety and concurrency features by wrapping unsafe kernel interactions within well-defined interfaces.

##### Relevant Technologies and Frameworks
- Rust and Cargo: The entire project is built in Rust, using Cargo for dependency management and building.
- Linux io_uring: The central technology, interfacing with the kernel’s io_uring API.
- CI/CD with GitHub Actions: The .github/workflows directory indicates automated testing and integration.

- Public API / IoUring (src/lib.rs)
- Opcode Management (opcode.rs)
- Submission & Completion Queues (squeue.rs, cqueue.rs)
- Support Utilities (types.rs, util.rs)
- Examples, Tests, and Benchmarks as auxiliary modules (or separate clusters)
- Environment Layering: Consider a layered approach – a top layer for the public API, a middle layer for internal abstractions, and a bottom layer that interacts directly with the operating system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public API Layer
    subgraph "Public API Layer"
        API["\"Public API / IoUring\""]:::core
    end

    %% Core Modules
    subgraph "Core Modules"
        OPC["\"Opcode Management\""]:::core
        REG["\"Register Module\""]:::core
        SUB["\"Submission Module\""]:::core
        SQ["\"Submission Queue\""]:::core
        CQ["\"Completion Queue\""]:::core
    end

    %% Internal Utilities
    subgraph "Internal Utilities"
        TYPES["\"Types\""]:::utility
        UTIL["\"Utilities\""]:::utility
    end

    %% System/Kernel Interface
    subgraph "System/Kernel Interface"
        SYS["\"System Interface\""]:::sys
        SYS_MAIN["\"Sys Module\""]:::sys
        SYS_X86["\"sys_x86-64\""]:::sys
        SYS_AARCH["\"sys_aarch64\""]:::sys
    end

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        EX1["\"Example: readme\""]:::aux
        EX2["\"Example: tcp_echo\""]:::aux
        TEST["\"Tests\""]:::aux
        BENCH["\"Benchmarks\""]:::aux
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        CTOML["\"Cargo.toml\""]:::build
        BRS["\"build.rs\""]:::build
        GHW["\"GitHub Actions\""]:::build
    end

    %% Relationships
    API -->|"builds_operation" | OPC
    API -->|"registers" | REG
    API -->|"submits" | SUB
    SUB -->|"queues" | SQ
    SQ -->|"calls_sys" | SYS
    SYS -->|"delegates_to" | SYS_MAIN
    SYS -->|"delegates_to" | SYS_X86
    SYS -->|"delegates_to" | SYS_AARCH
    SYS_MAIN -->|"processes_completion" | CQ
    SYS_X86 -->|"processes_completion" | CQ
    SYS_AARCH -->|"processes_completion" | CQ
    CQ -->|"returns_results" | API
    API -->|"utilizes" | TYPES
    API -->|"utilizes" | UTIL

    EX1 -->|"uses" | API
    EX2 -->|"uses" | API
    TEST -->|"tests" | API
    BENCH -->|"benchmarks" | API

    CTOML -->|"builds" | API
    BRS -->|"builds" | API
    GHW -->|"CI/CD_for" | API

    %% Click Events for Public API & Library Core
    click API "https://github.com/tokio-rs/io-uring/blob/master/src/lib.rs"
    click OPC "https://github.com/tokio-rs/io-uring/blob/master/src/opcode.rs"
    click REG "https://github.com/tokio-rs/io-uring/blob/master/src/register.rs"
    click SUB "https://github.com/tokio-rs/io-uring/blob/master/src/submit.rs"
    click SQ "https://github.com/tokio-rs/io-uring/blob/master/src/squeue.rs"
    click CQ "https://github.com/tokio-rs/io-uring/blob/master/src/cqueue.rs"

    %% Click Events for System/Kernel Interface
    click SYS "https://github.com/tokio-rs/io-uring/tree/master/src/sys"
    click SYS_MAIN "https://github.com/tokio-rs/io-uring/blob/master/src/sys/sys.rs"
    click SYS_X86 "https://github.com/tokio-rs/io-uring/blob/master/src/sys/sys_x86-64.rs"
    click SYS_AARCH "https://github.com/tokio-rs/io-uring/blob/master/src/sys/sys_aarch64.rs"

    %% Click Events for Types and Utilities
    click TYPES "https://github.com/tokio-rs/io-uring/blob/master/src/types.rs"
    click UTIL "https://github.com/tokio-rs/io-uring/blob/master/src/util.rs"

    %% Click Events for Examples
    click EX1 "https://github.com/tokio-rs/io-uring/blob/master/examples/readme.rs"
    click EX2 "https://github.com/tokio-rs/io-uring/blob/master/examples/tcp_echo.rs"

    %% Click Events for Tests and Benchmarks
    click TEST "https://github.com/tokio-rs/io-uring/tree/master/io-uring-test/src/tests"
    click BENCH "https://github.com/tokio-rs/io-uring/tree/master/io-uring-bench/src"

    %% Click Events for Build and Configuration
    click CTOML "https://github.com/tokio-rs/io-uring/blob/master/Cargo.toml"
    click BRS "https://github.com/tokio-rs/io-uring/blob/master/build.rs"
    click GHW "https://github.com/tokio-rs/io-uring/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px,color:#1B4F72;
    classDef sys fill:#ABEBC6,stroke:#196F3D,stroke-width:2px,color:#196F3D;
    classDef utility fill:#F9E79F,stroke:#B7950B,stroke-width:2px,color:#B7950B;
    classDef aux fill:#FAD7A0,stroke:#C0392B,stroke-width:2px,color:#C0392B;
    classDef build fill:#D2B4DE,stroke:#6C3483,stroke-width:2px,color:#6C3483;
```
