Struct Submitter

pub struct Submitter<'a> { /* private fields */ }

Interface for submitting submission queue events in an io_uring instance to the kernel for executing and registering files or buffers with the instance.

io_uring supports both directly performing I/O on buffers and file descriptors and registering them beforehand. Registering is slow, but it makes performing the actual I/O much faster.

Implementations

impl<'a> Submitter<'a>

pub unsafe fn enter<T: Sized>( &self, to_submit: u32, min_complete: u32, flag: u32, arg: Option<&T>, ) -> Result<usize>

Initiate and/or complete asynchronous I/O. This is a low-level wrapper around io_uring_enter - see man io_uring_enter (or its online version for more details.

You will probably want to use a more high-level API such as submit or submit_and_wait.

Safety

This provides a raw interface so developer must ensure that parameters are correct.

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

Submit all queued submission queue events to the kernel.

pub fn submit_and_wait(&self, want: usize) -> Result<usize>

Submit all queued submission queue events to the kernel and wait for at least want completion events to complete.

pub fn submit_with_args( &self, want: usize, args: &SubmitArgs<'_, '_>, ) -> Result<usize>

pub fn squeue_wait(&self) -> Result<usize>

Wait for the submission queue to have free entries.

pub unsafe fn register_buffers(&self, bufs: &[iovec]) -> Result<()>

Register in-memory fixed buffers for I/O with the kernel. You can use these buffers with the ReadFixed and WriteFixed operations.

Safety

Developers must ensure that the iov_base and iov_len values are valid and will be valid until buffers are unregistered or the ring destroyed, otherwise undefined behaviour may occur.

pub fn register_files_sparse(&self, nr: u32) -> Result<()>

Registers an empty file table of nr_files number of file descriptors. The sparse variant is available in kernels 5.19 and later.

Registering a file table is a prerequisite for using any request that uses direct descriptors.

pub fn register_files(&self, fds: &[RawFd]) -> Result<()>

Register files for I/O. You can use the registered files with Fixed.

Each fd may be -1, in which case it is considered “sparse”, and can be filled in later with register_files_update.

Note that this will wait for the ring to idle; it will only return once all active requests are complete. Use register_files_update to avoid this.

pub fn register_files_update(&self, offset: u32, fds: &[RawFd]) -> Result<usize>

This operation replaces existing files in the registered file set with new ones, either turning a sparse entry (one where fd is equal to -1) into a real one, removing an existing entry (new one is set to -1), or replacing an existing entry with a new existing entry. The offset parameter specifies the offset into the list of registered files at which to start updating files.

You can also perform this asynchronously with the FilesUpdate opcode.

pub fn register_eventfd(&self, eventfd: RawFd) -> Result<()>

Register an eventfd created by eventfd with the io_uring instance.

pub fn register_eventfd_async(&self, eventfd: RawFd) -> Result<()>

This works just like register_eventfd, except notifications are only posted for events that complete in an async manner, so requests that complete immediately will not cause a notification.

pub fn register_probe(&self, probe: &mut Probe) -> Result<()>

Fill in the given Probe with information about the opcodes supported by io_uring on the running kernel.

Examples

let io_uring = io_uring::IoUring::new(1)?;
let mut probe = io_uring::Probe::new();
io_uring.submitter().register_probe(&mut probe)?;

if probe.is_supported(io_uring::opcode::Read::CODE) {
    println!("Reading is supported!");
}

pub fn register_personality(&self) -> Result<u16>

Register credentials of the running application with io_uring, and get an id associated with these credentials. This ID can then be passed into submission queue entries to issue the request with this process’ credentials.

By default, if Parameters::is_feature_cur_personality is set then requests will use the credentials of the task that called Submitter::enter, otherwise they will use the credentials of the task that originally registered the io_uring.

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

Unregister all previously registered buffers.

You do not need to explicitly call this before dropping the IoUring, as it will be cleaned up by the kernel automatically.

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

Unregister all previously registered files.

You do not need to explicitly call this before dropping the IoUring, as it will be cleaned up by the kernel automatically.

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

Unregister an eventfd file descriptor to stop notifications.

pub fn unregister_personality(&self, personality: u16) -> Result<()>

Unregister a previously registered personality.

pub fn register_restrictions(&self, res: &mut [Restriction]) -> Result<()>

Permanently install a feature allowlist. Once this has been called, attempting to perform an operation not on the allowlist will fail with -EACCES.

This can only be called once, to prevent untrusted code from removing restrictions.

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

Enable the rings of the io_uring instance if they have been disabled with setup_r_disabled.

pub fn register_iowq_aff(&self, cpu_set: &cpu_set_t) -> Result<()>

Tell io_uring on what CPUs the async workers can run. By default, async workers created by io_uring will inherit the CPU mask of its parent. This is usually all the CPUs in the system, unless the parent is being run with a limited set.

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

Undoes a CPU mask previously set with register_iowq_aff

pub fn register_iowq_max_workers(&self, max: &mut [u32; 2]) -> Result<()>

Get and/or set the limit for number of io_uring worker threads per NUMA node. max[0] holds the limit for bounded workers, which process I/O operations expected to be bound in time, that is I/O on regular files or block devices. While max[1] holds the limit for unbounded workers, which carry out I/O operations that can never complete, for instance I/O on sockets. Passing 0 does not change the current limit. Returns previous limits on success.

pub unsafe fn register_buf_ring( &self, ring_addr: u64, ring_entries: u16, bgid: u16, ) -> Result<()>

Register buffer ring for provided buffers.

Details can be found in the io_uring_register_buf_ring.3 man page.

If the register command is not supported, or the ring_entries value exceeds 32768, the InvalidInput error is returned.

Available since 5.19.

Safety

Developers must ensure that the ring_addr and its length represented by ring_entries are valid and will be valid until the bgid is unregistered or the ring destroyed, otherwise undefined behaviour may occur.

pub fn unregister_buf_ring(&self, bgid: u16) -> Result<()>

Unregister a previously registered buffer ring.

Available since 5.19.

pub fn register_sync_cancel( &self, timeout: Option<Timespec>, builder: CancelBuilder, ) -> Result<()>

Performs a synchronous cancellation request, similar to AsyncCancel, except that it completes synchronously.

Cancellation can target a specific request, or all requests matching some criteria. The CancelBuilder builder supports describing the match criteria for cancellation.

An optional timeout can be provided to specify how long to wait for matched requests to be canceled. If no timeout is provided, the default is to wait indefinitely.

Errors

If no requests are matched, returns:

io::ErrorKind::NotFound: No such file or directory (os error 2)

If a timeout is supplied, and the timeout elapses prior to all requests being canceled, returns:

io::ErrorKind::Uncategorized: Timer expired (os error 62)

Notes

Only requests which have been submitted to the ring will be considered for cancellation. Requests which have been written to the SQ, but not submitted, will not be canceled.

Available since 6.0.