Crate kvarn_tokio_uring

Source
Expand description

Tokio-uring provides a safe io-uring interface for the Tokio runtime. The library requires Linux kernel 5.10 or later.

§Getting started

Using tokio-uring requires starting a [tokio-uring] runtime. This runtime internally manages the main Tokio runtime and a io-uring driver.

use tokio_uring::fs::File;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tokio_uring::start(async {
        // Open a file
        let file = File::open("hello.txt").await?;

        let buf = vec![0; 4096];
        // Read some data, the buffer is passed by ownership and
        // submitted to the kernel. When the operation completes,
        // we get the buffer back.
        let (res, buf) = file.read_at(buf, 0).await;
        let n = res?;

        // Display the contents
        println!("{:?}", &buf[..n]);

        Ok(())
    })
}

Under the hood, tokio_uring::start starts a [current-thread] Runtime. For concurrency, spawn multiple threads, each with a tokio-uring runtime. The tokio-uring resource types are optimized for single-threaded usage and most are !Sync.

§Submit-based operations

Unlike Tokio proper, io-uring is based on submission based operations. Ownership of resources are passed to the kernel, which then performs the operation. When the operation completes, ownership is passed back to the caller. Because of this difference, the tokio-uring APIs diverge.

For example, in the above example, reading from a File requires passing ownership of the buffer.

§Closing resources

With io-uring, closing a resource (e.g. a file) is an asynchronous operation. Because Rust does not support asynchronous drop yet, resource types provide an explicit close() function. If the close() function is not called, the resource will still be closed on drop, but the operation will happen in the background. There is no guarantee as to when the implicit close-on-drop operation happens, so it is recommended to explicitly call close().

Modules§

buf
Utilities for working with buffers.
fs
Filesystem manipulation operations.
net
TCP/UDP bindings for tokio-uring.

Structs§

Builder
Builder API that can create and start the io_uring runtime with non-default parameters, while abstracting away the underlying io_uring crate.
InFlightOneshot
An in-progress oneshot operation which can be polled for completion.
Runtime
The Runtime Executor
UnsubmittedOneshot
An unsubmitted oneshot operation.
WriteData
WriteTransform

Traits§

OneshotOutputTransform
Transforms the output of a oneshot operation into a more user-friendly format.

Functions§

builder
Constructs a Builder with default settings.
no_op
The simplest possible operation. Just posts a completion event, nothing else.
spawn
Spawns a new asynchronous task, returning a JoinHandle for it.
start
Starts an io_uring enabled Tokio runtime.
uring_builder
Creates and returns an io_uring::Builder that can then be modified through its implementation methods.

Type Aliases§

BufResult
A specialized Result type for io-uring operations with buffers.
UnsubmittedWrite
An unsubmitted write operation.