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. - InFlight
Oneshot - An in-progress oneshot operation which can be polled for completion.
- Runtime
- The Runtime Executor
- Unsubmitted
Oneshot - An unsubmitted oneshot operation.
- Write
Data - Write
Transform
Traits§
- Oneshot
Output Transform - 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 forio-uring
operations with buffers. - Unsubmitted
Write - An unsubmitted write operation.