pub struct LioUring { /* private fields */ }Expand description
A Linux io_uring instance for high-performance async I/O.
This struct provides access to both submission and completion operations on a single io_uring instance.
Implementations§
Source§impl LioUring
impl LioUring
Sourcepub fn new(capacity: u32) -> Result<Self>
pub fn new(capacity: u32) -> Result<Self>
Create a new io_uring instance with the specified capacity.
The capacity determines the size of the submission queue. The kernel may adjust this value.
§Errors
Returns an error if io_uring initialization fails (e.g., insufficient permissions, kernel doesn’t support io_uring, or out of resources).
Sourcepub fn with_params(params: Params) -> Result<Self>
pub fn with_params(params: Params) -> Result<Self>
Create a new io_uring instance with custom parameters.
§Errors
Returns an error if io_uring initialization fails.
Sourcepub unsafe fn push(&mut self, entry: Entry, user_data: u64) -> Result<()>
pub unsafe fn push(&mut self, entry: Entry, user_data: u64) -> Result<()>
Push an operation to the submission queue.
§Safety
Caller guarantees that the Entry has valid data and that any pointers within the operation point to valid data that will remain valid until the operation completes.
§Errors
Returns an error if the submission queue is full. Call submit() to
drain the queue and try again.
Sourcepub unsafe fn push_with_flags(
&mut self,
entry: Entry,
user_data: u64,
flags: SqeFlags,
) -> Result<()>
pub unsafe fn push_with_flags( &mut self, entry: Entry, user_data: u64, flags: SqeFlags, ) -> Result<()>
Sourcepub fn submit(&mut self) -> Result<usize>
pub fn submit(&mut self) -> Result<usize>
Submit queued operations to the kernel.
When SQPOLL is enabled, this avoids the syscall if the kernel thread is already running. Only enters the kernel if needed to wake the thread.
Returns the number of operations submitted.
§Errors
Returns an error if submission fails.
Sourcepub fn sq_space_left(&self) -> usize
pub fn sq_space_left(&self) -> usize
Get the number of free slots in the submission queue.
Sourcepub fn wait(&mut self) -> Result<Completion>
pub fn wait(&mut self) -> Result<Completion>
Wait for and retrieve the next completion.
This blocks until at least one completion is available.
§Errors
Returns an error if waiting fails.
Sourcepub fn wait_timeout(&mut self, timeout: Duration) -> Result<Option<Completion>>
pub fn wait_timeout(&mut self, timeout: Duration) -> Result<Option<Completion>>
Wait for and retrieve the next completion with a timeout.
Returns Ok(None) if the timeout expires with no completions.
§Errors
Returns an error if waiting fails (other than timeout).
Sourcepub fn try_wait(&mut self) -> Result<Option<Completion>>
pub fn try_wait(&mut self) -> Result<Option<Completion>>
Try to retrieve the next completion without blocking.
Returns None if no completions are available.
§Errors
Returns an error if peeking fails (not including “no data available”).
Sourcepub fn peek(&self) -> Result<Option<Completion>>
pub fn peek(&self) -> Result<Option<Completion>>
Peek at the next completion without removing it from the queue.
Returns None if no completions are available.
Sourcepub unsafe fn register_buffers(&mut self, buffers: &[IoSlice<'_>]) -> Result<()>
pub unsafe fn register_buffers(&mut self, buffers: &[IoSlice<'_>]) -> Result<()>
Register fixed buffers for zero-copy I/O.
Pre-registers buffers with the kernel to enable zero-copy operations.
Registered buffers can be used with ReadFixed and WriteFixed operations.
§Safety
The buffers must remain valid and not be modified or moved until they are unregistered or the io_uring instance is dropped.
§Errors
Returns an error if registration fails (e.g., insufficient resources).
Sourcepub fn unregister_buffers(&mut self) -> Result<()>
pub fn unregister_buffers(&mut self) -> Result<()>
Unregister previously registered buffers.
Sourcepub fn register_files(&mut self, fds: &[i32]) -> Result<()>
pub fn register_files(&mut self, fds: &[i32]) -> Result<()>
Register fixed file descriptors.
Pre-registers file descriptors with the kernel. Registered files can be referenced by index instead of fd, avoiding fd lookup overhead.
§Errors
Returns an error if registration fails.
Sourcepub fn register_files_update(&mut self, offset: u32, fds: &[i32]) -> Result<()>
pub fn register_files_update(&mut self, offset: u32, fds: &[i32]) -> Result<()>
Update registered files at specific indices.
Replace file descriptors at the given indices. Use -1 to remove a file.
Sourcepub fn unregister_files(&mut self) -> Result<()>
pub fn unregister_files(&mut self) -> Result<()>
Unregister all previously registered files.