#io #async #non-blocking #futures #io-uring

uringy

A simple single-threaded async runtime for Rust based on io_uring

1 unstable release

Uses new Rust 2021

0.4.0 Jul 26, 2022
0.3.0 Apr 29, 2022
0.2.0 Apr 29, 2022
0.1.2 Nov 16, 2021

#336 in Asynchronous

MIT license

255KB
6K SLoC

Uringy

github crates-io docs-rs license

A simple single-threaded async runtime for Rust based on io_uring.

Async Rust doesn't need to be complicated, so Uringy is designed with simplicity as its main goal. At it's core there is a single-threaded event loop which handles concurrency without the complexity that comes with parallelism. This doesn't mean that you can't take advantage of multiple cores in your environment, runtimes can be run on several threads. Popular runtimes like NodeJS, Go, and Tokio use the epoll API, while Uringy uses the newer io_uring API for better performance.

Note that Uringy is a work in progress and shouldn't be used in production.

Features

Simple API

  • Minimal interface that's well documented and tested
  • Easy to learn with the familiar syntax inspired by Rust's standard library and Tokio
  • Can use non-Send types across your tasks due to the single-threaded design

Performant async IO using io_uring

  • Batch system calls in the submission queue
  • Avoid copying buffers to and from the kernel
  • Avoid using a thread pool for file system IO

Quick to compile

  • Only compile what you need by specifying Cargo features (TODO: link to section)
  • Minimal dependencies and use of macros

Quick Start

Install Rust and create a new cargo project.

Add uringy as a dependency: cargo add uringy

Then replace src/main.rs with:

use uringy::runtime;

fn main() {
    // run async block to completion
    runtime::block_on(async {
        // create another task, will run concurrently with the current async block
        let handle = runtime::spawn(async {
            println!("world");
        });

        println!("hello");
        handle.await;
    });
}

And run your project using: cargo run --release

If you're using macOS or Windows, use a Linux virtual machine or a docker container.

New to async Rust?

You might not need async Rust, using synchronous threads will get you pretty far. Async Rust might make a difference only when you outgrow threads and your program is IO bound.

Once you've decided on using async Rust, you should understand the basics of futures.

Then you should decide which async Runtime you want to use. For a serious project you should use Tokio. But since you're here, run the quick start and then check out the examples.

If you need to implement your own Future types, check out the source code for examples. I highly recommend Rust for Rustaceans to learn the theory.

Supported Rust Versions

The MSRV is 1.58.1 (released in January 2022).

Supported Linux Kernel Versions

The minimum kernel version is 5.18 (released in May 2022).

License

This project is licensed under the MIT license.

Dependencies

~130KB