Struct iou::registrar::Registrar

pub struct Registrar<'ring> { /* fields omitted */ }

A Registrar creates ahead-of-time kernel references to files and user buffers.

Preregistration significantly reduces per-IO overhead, so consider registering frequently used files and buffers. For file IO, preregistration lets the kernel skip the atomic acquire and release of a kernel-specific file descriptor. For buffer IO, the kernel can avoid mapping kernel memory for every operation.

Beware that registration is relatively expensive and should be done before any performance sensitive code.

If you want to register a file but don't have an open file descriptor yet, you can register a placeholder descriptor and update it later.

let mut ring = IoUring::new(8)?;
let mut registrar: Registrar = ring.registrar();
let registered_files: Vec<RegisteredFd> = registrar.register_files(fds)?.collect();

Implementations

impl<'ring> Registrar<'ring>

pub fn register_buffers(
    &self,
    buffers: Vec<Box<[u8]>>
) -> Result<impl Iterator<Item = RegisteredBuf>>

pub fn register_buffers_by_ref<'a>(
    &self,
    buffers: &'a [&'a [u8]]
) -> Result<impl Iterator<Item = RegisteredBufRef<'a>> + 'a>

pub fn register_buffers_by_mut<'a>(
    &self,
    buffers: &'a mut [&'a mut [u8]]
) -> Result<impl Iterator<Item = RegisteredBufMut<'a>> + 'a>

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

Unregister all currently registered buffers. An explicit call to this method is often unecessary, because all buffers will be unregistered automatically when the ring is dropped.

pub fn register_files<'a>(
    &mut self,
    files: &'a [RawFd]
) -> Result<impl Iterator<Item = RegisteredFd> + 'a>

Register a set of files with the kernel. Registered files handle kernel fileset indexing behind the scenes and can often be used in place of raw file descriptors.

Errors

Returns an error if

• there is a preexisting set of registered files,
• the files slice was empty,
• the inner io_uring_register_files call failed for another reason

let fileset: Vec<_> = registrar.register_files(&raw_fds)?.collect();
let reg_file = fileset[0];
unsafe { sqe.prep_write_vectored(reg_file, bufs, 0); }

pub fn update_registered_files<'a>(
    &mut self,
    offset: usize,
    files: &'a [RawFd]
) -> Result<impl Iterator<Item = RegisteredFd> + 'a>

Update the currently registered kernel fileset. It is usually more efficient to reserve space for files before submitting events, because IoUring will wait until the submission queue is empty before registering files.

Errors

Returns an error if

• there isn't a registered fileset,
• the files slice was empty,
• offset is out of bounds,
• the files slice was too large,
• the inner io_uring_register_files_update call failed for another reason

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

Unregister all currently registered files. An explicit call to this method is often unecessary, because all files will be unregistered automatically when the ring is dropped.

Errors

Returns an error if

• there isn't a registered fileset,
• the inner io_uring_unregister_files call failed for another reason

You can use this method to replace an existing fileset:

let raw_fds = [0, 1];
let fds: Vec<_> = registrar.register_files(&raw_fds)?.collect();
assert_eq!(fds.len(), 2);

registrar.unregister_files()?;

let other_raw_fds = [0, 1, 2];
let new_fds: Vec<_> = registrar.register_files(&other_raw_fds)?.collect();
assert_eq!(new_fds.len(), 3);

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

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

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

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

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

pub fn probe(&self) -> Result<Probe>

Trait Implementations

impl<'_> Debug for Registrar<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'ring> Send for Registrar<'ring>

impl<'ring> Sync for Registrar<'ring>