pub struct IoUringState { /* private fields */ }Expand description
Orchestrator for the io_uring ring.
Lifetime: owns an fd + three mmap’d regions (SQ ring, CQ ring,
SQEs array). Drop closes + unmaps in reverse order.
Thread-safety: Send + Sync is safe because every public method
takes &mut self OR uses atomic operations on the ring pointers
(head/tail are AtomicU32 in the mmap’d memory). The &mut self
receiver on get_sqe + commit_sqe prevents two producers from
racing on the submission queue; CQE reaping via peek_cqe also
takes &mut self for the same reason on the completion side.
Implementations§
Source§impl IoUringState
impl IoUringState
Sourcepub fn new(entries: u32) -> Result<Self, PipelineError>
pub fn new(entries: u32) -> Result<Self, PipelineError>
Create an IoUringState with entries SQEs, SQPOLL enabled,
and a 2-second kernel-thread idle timeout.
§Errors
PipelineError::IoUringSyscallifio_uring_setupreturns < 0. Common reasons: kernel too old (< 5.1), resource limit exceeded, missing CAP_SYS_ADMIN for SQPOLL on older kernels.PipelineError::IoUringSyscallif any of the threemmapcalls fail.
Sourcepub fn enter(
&self,
to_submit: u32,
min_complete: u32,
flags: u32,
) -> Result<i32, PipelineError>
pub fn enter( &self, to_submit: u32, min_complete: u32, flags: u32, ) -> Result<i32, PipelineError>
Enter the ring to submit items or wait for completions.
§Errors
Returns PipelineError::IoUringSyscall if the syscall
fails. Typical causes: EINTR (retry), EBUSY (wait and
retry), ENXIO (kernel-side SQPOLL thread died).
Sourcepub fn uses_sqpoll(&self) -> bool
pub fn uses_sqpoll(&self) -> bool
True when this ring was created with kernel-side SQ polling.
Sourcepub fn sq_needs_wakeup(&self) -> bool
pub fn sq_needs_wakeup(&self) -> bool
True when the SQPOLL thread has slept and must be explicitly woken.
Sourcepub fn wake_sqpoll(&self) -> Result<i32, PipelineError>
pub fn wake_sqpoll(&self) -> Result<i32, PipelineError>
Wake a sleeping SQPOLL thread so already-published SQEs make progress.
Sourcepub fn get_sqe(&mut self) -> Option<&mut io_uring_sqe>
pub fn get_sqe(&mut self) -> Option<&mut io_uring_sqe>
Obtain a mutable reference to the next available SQE.
Sourcepub fn commit_sqe(&mut self)
pub fn commit_sqe(&mut self)
Commit the currently acquired SQE and advance the SQ tail.
Sourcepub fn peek_cqe(&mut self) -> Option<&io_uring_cqe>
pub fn peek_cqe(&mut self) -> Option<&io_uring_cqe>
Read the next available CQE from the completion queue.
Sourcepub fn register_buffers(&self, iovecs: &[Iovec]) -> Result<(), PipelineError>
pub fn register_buffers(&self, iovecs: &[Iovec]) -> Result<(), PipelineError>
Register a set of buffers with the kernel via
IORING_REGISTER_BUFFERS, unlocking IORING_OP_READ_FIXED
zero-validation reads. iovecs must outlive every SQE that
references a buf_index into it; the kernel only reads
iovecs during this registration call itself.
§Errors
Returns PipelineError::IoUringSyscall if
io_uring_register fails - typical causes are EFAULT (bad
pointer), ENOMEM, or EOPNOTSUPP (kernel < 5.1).
Sourcepub fn register_files(&self, fds: &[i32]) -> Result<(), PipelineError>
pub fn register_files(&self, fds: &[i32]) -> Result<(), PipelineError>
Register fixed files via IORING_REGISTER_FILES. After
registration, SQEs that set IOSQE_FIXED_FILE treat fd as
the index into this table, skipping the per-SQE fd refcount
bump.
§Errors
Same as IoUringState::register_buffers.
Sourcepub fn advance_cq(&mut self)
pub fn advance_cq(&mut self)
Advance the CQ head, acknowledging completion.