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.