Struct io_uring::URingContext

pub struct URingContext {
    ring_file: File,
    pub submit_ring: Mutex<SubmitQueue>,
    pub complete_ring: CompleteQueueState,
}

Unsafe wrapper for the kernel’s io_uring interface. Allows for queueing multiple I/O operations to the kernel and asynchronously handling the completion of these operations. Use the various add_* functions to configure operations, then call wait to start the operations and get any completed results. Each op is given a u64 user_data argument that is used to identify the result when returned in the iterator provided by wait.

Example polling an FD for readable status.

let f = File::open(Path::new("/dev/zero")).unwrap();
let uring = URingContext::new(16, None).unwrap();
uring
  .add_poll_fd(f.as_raw_fd(), EventType::Read, 454)
.unwrap();
let (user_data, res) = uring.wait().unwrap().next().unwrap();
assert_eq!(user_data, 454 as io_uring::UserData);
assert_eq!(res.unwrap(), 1 as u32);

Fields

ring_file: File

submit_ring: Mutex<SubmitQueue>

complete_ring: CompleteQueueState

Implementations

impl URingContext

pub fn new( num_entries: usize, allowlist: Option<&URingAllowlist> ) -> Result<URingContext>

Creates a URingContext where the underlying uring has a space for num_entries simultaneous operations. If allowlist is given, all operations other than those explicitly permitted by allowlist are prohibited.

pub unsafe fn add_writev_iter<I>( &self, iovecs: I, fd: RawFd, offset: Option<u64>, user_data: UserData ) -> Result<()>

where I: Iterator<Item = iovec>,

Safety

See ‘writev’ but accepts an iterator instead of a vector if there isn’t already a vector in existence.

pub unsafe fn add_writev( &self, iovecs: Pin<Box<[IoBufMut<'static>]>>, fd: RawFd, offset: Option<u64>, user_data: UserData ) -> Result<()>

Asynchronously writes to fd from the addresses given in iovecs.

Safety

add_writev will write to the address given by iovecs. This is only safe if the caller guarantees there are no other references to that memory and that the memory lives until the transaction is complete and that completion has been returned from the wait function. In addition there must not be any mutable references to the data pointed to by iovecs until the operation completes. Ensure that the fd remains open until the op completes as well. The iovecs reference must be kept alive until the op returns.

pub unsafe fn add_readv_iter<I>( &self, iovecs: I, fd: RawFd, offset: Option<u64>, user_data: UserData ) -> Result<()>

where I: Iterator<Item = iovec>,

Safety

See ‘readv’ but accepts an iterator instead of a vector if there isn’t already a vector in existence.

pub unsafe fn add_readv( &self, iovecs: Pin<Box<[IoBufMut<'static>]>>, fd: RawFd, offset: Option<u64>, user_data: UserData ) -> Result<()>

Asynchronously reads from fd to the addresses given in iovecs.

Safety

add_readv will write to the address given by iovecs. This is only safe if the caller guarantees there are no other references to that memory and that the memory lives until the transaction is complete and that completion has been returned from the wait function. In addition there must not be any references to the data pointed to by iovecs until the operation completes. Ensure that the fd remains open until the op completes as well. The iovecs reference must be kept alive until the op returns.

pub fn add_nop(&self, user_data: UserData) -> Result<()>

Add a no-op operation that doesn’t perform any IO. Useful for testing the performance of the io_uring itself and for waking up a thread that’s blocked inside a wait() call.

pub fn add_fsync(&self, fd: RawFd, user_data: UserData) -> Result<()>

Syncs all completed operations, the ordering with in-flight async ops is not defined.

pub fn add_fallocate( &self, fd: RawFd, offset: u64, len: u64, mode: u32, user_data: UserData ) -> Result<()>

See the usage of fallocate, this asynchronously performs the same operations.

pub fn add_poll_fd( &self, fd: RawFd, events: EventType, user_data: UserData ) -> Result<()>

Adds an FD to be polled based on the given flags. The user must keep the FD open until the operation completion is returned from wait. Note that io_uring is always a one shot poll. After the fd is returned, it must be re-added to get future events.

pub fn remove_poll_fd( &self, fd: RawFd, events: EventType, user_data: UserData ) -> Result<()>

Removes an FD that was previously added with add_poll_fd.

pub fn async_cancel(&self, addr: UserData, user_data: UserData) -> Result<()>

Attempt to cancel an already issued request. addr must contain the user_data field of the request that should be cancelled. The cancellation request will complete with one of the following results codes. If found, the res field of the cqe will contain 0. If not found, res will contain -ENOENT. If found and attempted cancelled, the res field will contain -EALREADY. In this case, the request may or may not terminate. In general, requests that are interruptible (like socket IO) will get cancelled, while disk IO requests cannot be cancelled if already started.

fn enter(&self, wait_nr: u64) -> Result<()>

pub fn submit(&self) -> Result<()>

Sends operations added with the add_* functions to the kernel.

pub fn wait(&self) -> Result<impl Iterator<Item = (UserData, Result<u32>)> + '_>

Sends operations added with the add_* functions to the kernel and return an iterator to any completed operations. wait blocks until at least one completion is ready. If called without any new events added, this simply waits for any existing events to complete and returns as soon an one or more is ready.

Trait Implementations

impl AsRawDescriptor for URingContext

fn as_raw_descriptor(&self) -> RawDescriptor

Returns the underlying raw descriptor.

impl AsRawFd for URingContext

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.