Crate uring_file 

Async file I/O via Linux io_uring.

This crate provides a high-level, async-compatible interface to Linux’s io_uring for file operations. It is designed for high-performance scenarios where traditional threaded I/O or epoll-based async I/O is a bottleneck.

Features

• Async/await compatible: Works with tokio and other async runtimes
• Zero-copy where possible: Buffers are passed through, not copied
• Batched submissions: Multiple I/O operations are batched for efficiency
• Thread-safe: Uring handles can be shared across threads and tasks

Quick Start

use uring_file::{UringFile, uring::{Uring, UringCfg}};
use std::fs::File;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Option 1: Use the UringFile trait with the global ring
    let file = File::open("data.bin")?;
    let result = file.ur_read_at(0, 4096).await?;
    println!("Read {} bytes", result.bytes_read);

    // Option 2: Create your own ring for more control
    let uring = Uring::new(UringCfg::default())?;
    let result = uring.read_at(&file, 0, 4096).await?;
    println!("Read {} bytes", result.bytes_read);

    Ok(())
}

Architecture

The crate uses a shared io_uring instance with dedicated threads:

┌─────────────┐     ┌───────────────────┐     ┌─────────────┐
│ Async Tasks │────▶│ Submission Thread │────▶│  io_uring   │
└─────────────┘     └───────────────────┘     └──────┬──────┘
       ▲                                             │
       │            ┌───────────────────┐            │
       └────────────│ Completion Thread │◀───────────┘
                    └───────────────────┘

Kernel Requirements

• Minimum: Linux 5.1 (basic io_uring support)
• Recommended: Linux 5.6+ (for statx, fallocate, fadvise)
• ftruncate: Linux 6.9+

Platform Support

This crate only compiles on Linux. On other platforms, it will fail at compile time.

Modules

fs

High-level filesystem operations using io_uring.

metadata

File metadata types compatible with std::fs::Metadata.

uring

Core io_uring wrapper providing async file operations.

Traits

UringFile

Extension trait for performing io_uring operations on file types.

Functions

default_uring

Get a reference to the global default io_uring instance.