How tokio-rs/tokio-uring works
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.