Struct rio::Uring

pub struct Uring { /* fields omitted */ }

The top-level io_uring structure.

Methods

impl Uring

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn accept<'a>(
    &'a self,
    tcp_listener: &'a TcpListener
) -> Completion<'a, TcpStream>

Asynchronously accepts a TcpStream from a provided TcpListener.

Warning

This only becomes usable on linux kernels 5.5 and up.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn send<'a, F, B>(
    &'a self,
    stream: &'a F,
    iov: &'a B
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: 'a + AsIoVec, 

Send a buffer to the target socket or file-like destination.

Returns the length that was successfully written.

Warning

This only becomes usable on linux kernels 5.6 and up.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn send_ordered<'a, F, B>(
    &'a self,
    stream: &'a F,
    iov: &'a B,
    ordering: Ordering
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: 'a + AsIoVec, 

Send a buffer to the target socket or file-like destination.

Returns the length that was successfully written.

Accepts an Ordering specification.

Warning

This only becomes usable on linux kernels 5.6 and up.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn recv<'a, F, B>(
    &'a self,
    stream: &'a F,
    iov: &'a B
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: AsIoVec + AsIoVecMut, 

Receive data from the target socket or file-like destination, and place it in the given buffer.

Returns the length that was successfully read.

Warning

This only becomes usable on linux kernels 5.6 and up.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn recv_ordered<'a, F, B>(
    &'a self,
    stream: &'a F,
    iov: &'a B,
    ordering: Ordering
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: AsIoVec + AsIoVecMut, 

Receive data from the target socket or file-like destination, and place it in the given buffer.

Returns the length that was successfully read.

Accepts an Ordering specification.

Warning

This only becomes usable on linux kernels 5.6 and up.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn fsync<'a>(&'a self, file: &'a File) -> Completion<'a, ()>

Flushes all buffered writes, and associated metadata changes.

Warning

You usually don't want to do this without linking to a previous write, because io_uring will execute operations out-of-order. Without setting a Link ordering on the previous operation, or using fsync_ordered with the Drain ordering, causing all previous operations to complete before itself.

Additionally, fsync does not ensure that the file actually exists in its parent directory. So, for new files, you must also fsync the parent directory.

This does nothing for files opened in O_DIRECT mode.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn fsync_ordered<'a>(
    &'a self,
    file: &'a File,
    ordering: Ordering
) -> Completion<'a, ()>

Flushes all buffered writes, and associated metadata changes.

You probably want to either use a Link ordering on a previous write (or chain of separate writes), or use the Drain ordering on this operation.

You may pass in an Ordering to specify two different optional behaviors:

• Ordering::Link causes the next submitted operation to wait until this one finishes. Useful for things like file copy, fsync-after-write, or proxies.
• Ordering::Drain causes all previously submitted operations to complete before this one begins.

Warning

fsync does not ensure that the file actually exists in its parent directory. So, for new files, you must also fsync the parent directory. This does nothing for files opened in O_DIRECT mode.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn fdatasync<'a>(&'a self, file: &'a File) -> Completion<'a, ()>

Flushes all buffered writes, and the specific metadata required to access the data. This will skip syncing metadata like atime.

You probably want to either use a Link ordering on a previous write (or chain of separate writes), or use the Drain ordering on this operation with the fdatasync_ordered method.

Warning

fdatasync does not ensure that the file actually exists in its parent directory. So, for new files, you must also fsync the parent directory. This does nothing for files opened in O_DIRECT mode.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn fdatasync_ordered<'a>(
    &'a self,
    file: &'a File,
    ordering: Ordering
) -> Completion<'a, ()>

Flushes all buffered writes, and the specific metadata required to access the data. This will skip syncing metadata like atime.

You probably want to either use a Link ordering on a previous write (or chain of separate writes), or use the Drain ordering on this operation.

You may pass in an Ordering to specify two different optional behaviors:

• Ordering::Link causes the next submitted operation to wait until this one finishes. Useful for things like file copy, fsync-after-write, or proxies.
• Ordering::Drain causes all previously submitted operations to complete before this one begins.

Warning

fdatasync does not ensure that the file actually exists in its parent directory. So, for new files, you must also fsync the parent directory. This does nothing for files opened in O_DIRECT mode.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn sync_file_range<'a>(
    &'a self,
    file: &'a File,
    offset: u64,
    len: usize
) -> Completion<'a, ()>

Synchronizes the data associated with a range in a file. Does not synchronize any metadata updates, which can cause data loss if you are not writing to a file whose metadata has previously been synchronized.

You probably want to have a prior write linked to this, or set Ordering::Drain by using sync_file_range_ordered instead.

Under the hood, this uses the "pessimistic" set of flags: SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn sync_file_range_ordered<'a>(
    &'a self,
    file: &'a File,
    offset: u64,
    len: usize,
    ordering: Ordering
) -> Completion<'a, ()>

Synchronizes the data associated with a range in a file. Does not synchronize any metadata updates, which can cause data loss if you are not writing to a file whose metadata has previously been synchronized.

You probably want to have a prior write linked to this, or set Ordering::Drain.

Under the hood, this uses the "pessimistic" set of flags: SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn write_at<'a, F, B>(
    &'a self,
    file: &'a F,
    iov: &'a B,
    at: u64
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: 'a + AsIoVec, 

Writes data at the provided buffer using vectored IO. Be sure to check the returned io_uring_cqe's res field to see if a short write happened. This will contain the number of bytes written.

Note that the file argument is generic for anything that supports AsRawFd: sockets, files, etc...

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn write_at_ordered<'a, F, B>(
    &'a self,
    file: &'a F,
    iov: &'a B,
    at: u64,
    ordering: Ordering
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: 'a + AsIoVec, 

Writes data at the provided buffer using vectored IO.

Be sure to check the returned io_uring_cqe's res field to see if a short write happened. This will contain the number of bytes written.

You may pass in an Ordering to specify two different optional behaviors:

• Ordering::Link causes the next submitted operation to wait until this one finishes. Useful for things like file copy, fsync-after-write, or proxies.
• Ordering::Drain causes all previously submitted operations to complete before this one begins.

Note that the file argument is generic for anything that supports AsRawFd: sockets, files, etc...

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn read_at<'a, F, B>(
    &'a self,
    file: &'a F,
    iov: &'a B,
    at: u64
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: AsIoVec + AsIoVecMut, 

Reads data into the provided buffer from the given file-like object, at the given offest, using vectored IO. Be sure to check the returned io_uring_cqe's res field to see if a short read happened. This will contain the number of bytes read.

Note that the file argument is generic for anything that supports AsRawFd: sockets, files, etc...

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn read_at_ordered<'a, F, B>(
    &'a self,
    file: &'a F,
    iov: &'a B,
    at: u64,
    ordering: Ordering
) -> Completion<'a, usize> where
    F: AsRawFd,
    B: AsIoVec + AsIoVecMut, 

Reads data into the provided buffer using vectored IO. Be sure to check the returned io_uring_cqe's res field to see if a short read happened. This will contain the number of bytes read.

You may pass in an Ordering to specify two different optional behaviors:

• Ordering::Link causes the next submitted operation to wait until this one finishes. Useful for things like file copy, fsync-after-write, or proxies.
• Ordering::Drain causes all previously submitted operations to complete before this one begins.

Note that the file argument is generic for anything that supports AsRawFd: sockets, files, etc...

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn nop<'a>(&'a self) -> Completion<'a, ()>

Don't do anything. This is mostly for debugging and tuning.

Important traits for Completion<'a, C>

impl<'a, C: FromCqe> Future for Completion<'a, C> type Output = Result<C>;

pub fn nop_ordered<'a>(&'a self, ordering: Ordering) -> Completion<'a, ()>

Don't do anything. This is mostly for debugging and tuning.

pub fn submit_all(&self)

Block until all items in the submission queue are submitted to the kernel. This can be avoided by using the SQPOLL mode (a privileged operation) on the Config struct.

Note that this is performed automatically and in a more fine-grained way when a Completion is consumed via Completion::wait or awaited in a Future context.

You don't need to call this if you are calling .wait() or .await on the Completion quickly, but if you are doing some other stuff that could take a while first, calling this will ensure that the operation is being executed by the kernel in the mean time.

Trait Implementations

impl Debug for Uring

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

Formats the value using the given formatter.

impl Drop for Uring

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Uring

impl Sync for Uring