Crate io_uring_epoll

io-uring-epoll

When your io_uring meets your epoll 🥰

Save system calls by setting file handle readiness checks especially in busy eventloops that have a lot of on/off readiness activity via io_uring interface.

Please note that epoll is different to reqular poll and is only available on Linux kernel.

Epoll itself has been in the Linux kernel around 20 years but io_uring has recently added the EpollCtl OpCode support in order to bypass the need of systerm calls to control it.

This is not a portable implementation given Windows I/O rings or MacOS doesn’t provide anything related with their relevant epoll implementations if any.

Add

cargo add io-uring-epoll

Example

use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::os::fd::AsRawFd;
use io_uring_epoll::{HandledFd, EpollHandler};

// The 10 denotes power of two capacity to io_uring::IoUring
let mut handler = EpollHandler::new(10).expect("Unable to create EPoll Handler");

// This works with any impl that provides std::os::fd::AsRawFd impl
// In POSIX/UNIX-like it's just i32 file number or "fileno"
let listen = std::net::TcpListener::bind(SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 0)).unwrap();

// Add the listen handle into EpollHandler
let mut handle_fd = HandledFd::new(listen.as_raw_fd());
let set_mask = handle_fd.set_in(true);
handler.add_fd(&handle_fd);

// Prepare a commit all changes into io_uring::SubmissionQueue
let handle_status = handler.prepare_submit().unwrap();

// async version is with submit()
handler.submit_and_wait(1).unwrap();

// Get the underlying io_uring::cqeueu::CompletionQueue
let mut c_queue = handler.io_uring().completion();

// Note: This may not have finished so may need to wait for it
if c_queue.is_empty() == false {
    let cqes: Vec<io_uring::cqueue::Entry> = c_queue.take_while(|i| {
        dbg!(i);
        false
    }).collect();
}

License

Licensed under either of:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs

EpollHandler

Manage the io_uring Submission and Completion Queues related to EpollCtrl opcode in io_uring. See io_epoll(7): https://man7.org/linux/man-pages/man7/epoll.7.html

FdCommitResults

Represents Submission queue results as described in [EpollHandler::commit()]

HandledFd

Create [HandledFd::new(RawFd)] and then add it to EpollHandler::add_fd()

Enums

EpollHandlerError

Errors from the handler