Struct Uring 

pub struct Uring { /* private fields */ }

Handle to a shared io_uring instance.

This is the main entry point for performing async I/O operations via io_uring. It is cheap to clone (just clones an Arc internally) and safe to share across threads and async tasks.

Example

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

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let uring = Uring::new(UringCfg::default())?;
    let file = File::open("test.txt")?;
     
    let result = uring.read_at(&file, 0, 1024).await?;
    println!("Read {} bytes", result.bytes_read);
    Ok(())
}

Architecture Notes

Internally, Uring spawns two background threads:

1. Submission thread: Receives requests via a channel, batches them, and submits them to the kernel.
2. Completion thread: Polls the completion queue and dispatches results back to waiting async tasks.

This design allows for efficient batching of submissions while maintaining a simple async API.

Implementations

impl Uring

pub fn new(cfg: UringCfg) -> Result<Self>

Create a new io_uring instance with the given configuration.

This spawns two background threads for submission and completion handling. The threads will automatically stop when all Uring handles are dropped.

Errors

Returns an error if the io_uring cannot be created (e.g., kernel too old, resource limits exceeded, or insufficient permissions).

pub async fn read_at( &self, file: &impl AsRawFd, offset: u64, len: u64, ) -> Result<ReadResult>

Read from a file at the specified offset. Returns the buffer and the number of bytes actually read. The number of bytes read may be less than requested if the file is smaller or if EOF is reached.

pub async fn write_at( &self, file: &impl AsRawFd, offset: u64, data: Vec<u8>, ) -> Result<WriteResult>

Write to a file at the specified offset. Returns the original buffer and number of bytes written. For regular files, bytes_written will typically equal data.len(). For pipes, sockets, etc., short writes are possible and normal.

pub async fn sync(&self, file: &impl AsRawFd) -> Result<()>

Synchronize file data and metadata to disk (fsync). This ensures that all data and metadata modifications are flushed to the underlying storage device. Even when using direct I/O, this is necessary to ensure the device itself has flushed any internal caches.

Note on ordering: io_uring does not guarantee ordering between operations. If you need to ensure writes complete before fsync, you should await the write first, then call fsync.

pub async fn datasync(&self, file: &impl AsRawFd) -> Result<()>

Synchronize file data to disk (fdatasync). Like sync, but only flushes data, not metadata (unless the metadata is required to retrieve the data). This can be faster than a full fsync.

pub async fn statx(&self, file: &impl AsRawFd) -> Result<Metadata>

Get file status information (statx). This is the io_uring equivalent of fstat/statx. It returns metadata about the file including size, permissions, timestamps, etc. Requires Linux 5.6+. On older kernels, this will fail with EINVAL.

pub async fn fallocate( &self, file: &impl AsRawFd, offset: u64, len: u64, mode: i32, ) -> Result<()>

Pre-allocate or deallocate space for a file (fallocate). This can be used to pre-allocate space to avoid fragmentation, punch holes in sparse files, or zero-fill regions. See falloc module for mode flags. Requires Linux 5.6+.

pub async fn fadvise( &self, file: &impl AsRawFd, offset: u64, len: u32, advice: i32, ) -> Result<()>

Advise the kernel about expected file access patterns (fadvise). This is a hint to the kernel about how you intend to access a file region. The kernel may use this to optimize readahead, caching, etc. See advice module for advice values. Requires Linux 5.6+.

pub async fn ftruncate(&self, file: &impl AsRawFd, len: u64) -> Result<()>

Truncate a file to a specified length (ftruncate). If the file is larger than the specified length, the extra data is lost. If the file is smaller, it is extended and the extended part reads as zeros. Requires Linux 6.9+. On older kernels, this will fail with EINVAL.

Trait Implementations

impl Clone for Uring

fn clone(&self) -> Uring

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.