neondatabase/tokio-epoll-uring

Use io_uring from vanilla tokio.

tokio-epoll-uring enables high-performance use of Linux's io_uring from vanilla tokio.

Warning

This project is currently not intended for use outside of Neon. The plan is to prove the core architectural idea by deploying it to production in Neon's Pageserver. We will share the results with the tokio community to push forward io_uring-enabled tokio.

Documentation

Use cargo doc --no-deps --open.

The Rust docs include sections on the motivation behind this project, the design of the crate, and benchmarks. If you prefer to read them in Markdown in your browser, check out the files in tokio-epoll-uring/src/doc.

Examples

Check out ./tokio-epoll-uring/examples.

Bug Reports, Roadmap, Contributing

As noted at the top of this readme file, this project is not yet intended for use outside of Neon.

• Genuine bug reports are welcome.
• We will not be able to accept feature requests at this time.
• We are unlikely to accept big refactoring PRs.
• We are likely to accept PRs that add support for new io_uring opcodes. Duplicating some code per opcdoe added is preferred over doing a big DRY refactoring.
• Feedback on the architecture is best provided by opening an issue.

Benchmarking

See ./BENCHMARKING.md.

tokio-epoll-uring's Issues

Figure out if we can get rid of `Slot::Undefined`

          ```suggestion
                Slot::Undefined => panic!("slot is in undefined state"),

Though, what good are undefined states for us in our own program.. I think these are the most cumbersome parts to review with these.

_Originally posted by @koivunej in https://github.com/neondatabase/tokio-epoll-uring/pull/11#discussion_r1294287630_
            

panic observed in staging

https://neondb.slack.com/archives/C033RQ5SPDH/p1706720300250229?thread_ts=1706717648.441269&cid=C033RQ5SPDH

false clippy beta `warning: this `MutexGuard` is held across an `await` point`

          The CI failure is due to a new beta clippy lint:

warning: this `MutexGuard` is held across an `await` point
   --> tokio-epoll-uring/src/system/completion.rs:204:33
    |
204 | ...                   let poller_guard = poller.lock().unwrap();
    |                           ^^^^^^^^^^^^
    |
    = help: consider using an async-aware `Mutex` type or ensuring the `MutexGuard` is dropped before calling await
note: these are all the `await` points this lock is held through
   --> tokio-epoll-uring/src/system/completion.rs:215:42
    |
215 | ...                   .await
    |                        ^^^^^
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#await_holding_lock
    = note: `#[warn(clippy::await_holding_lock)]` on by default

warning: `tokio-epoll-uring` (lib) generated 1 warning
    Checking benchmark v0.1.0 (/home/admin/tokio-epoll-uring/benchmark)
    Finished dev [unoptimized + debuginfo] target(s) in 22.39s

It's a false positive, the guard is dropped before the .await point.
The fix would be to rearrange control flow so that the guard is in a scope that is closed before the .await point.

Will turn this into a follow-up issue.

Originally posted by @problame in #18 (comment)

`BoundedBuf.slice()` panics for empty bufs

Currently the Pageserver integration PRs neondatabase/neon#6663 deal with this by checking for empty bufs beforehand, e.g., https://github.com/neondatabase/neon/blob/c92e8a76b07202c365426b62b69e07db7c05668b/pageserver/src/virtual_file.rs#L1099-L1103

It would be nicer if this behaved just like the std slice.

=> talk it through with tokio-uring upstream, afaik they haven't released a version with the BoundedBuf::slice API yet.