/ 
Hypersonic-0.11
/ Hypersonic::Event::IOUring

NAME

Hypersonic::Event::IOUring - io_uring event backend for Linux 5.1+

SYNOPSIS

use Hypersonic::Event;

my $backend = Hypersonic::Event->backend('io_uring');
# $backend is 'Hypersonic::Event::IOUring'

DESCRIPTION

Hypersonic::Event::IOUring is the io_uring-based event backend for Hypersonic. It provides the highest performance on modern Linux systems by using submission queues (SQE) and completion queues (CQE) to batch I/O operations and reduce syscall overhead.

io_uring is fundamentally different from epoll/kqueue in that it:

  • Uses a ring buffer shared between kernel and userspace

  • Supports true asynchronous I/O including accept, read, write

  • Can batch multiple operations in a single syscall

  • Supports kernel-side polling for even lower latency

METHODS

name

my $name = Hypersonic::Event::IOUring->name;  # 'io_uring'

Returns the backend name.

available

if (Hypersonic::Event::IOUring->available) { ... }

Returns true if this backend is available. Requires:

  • Linux kernel 5.1 or later

  • liburing library installed (liburing-dev package)

includes

Returns the C #include directives needed for io_uring.

defines

Returns the C #define directives for io_uring configuration, including user data encoding macros.

event_struct

my $struct = Hypersonic::Event::IOUring->event_struct;  # 'io_uring_cqe'

Returns the C struct name used for completion queue entries.

extra_ldflags

my $flags = Hypersonic::Event::IOUring->extra_ldflags;  # '-luring'

Returns linker flags needed for liburing.

gen_create($builder, $listen_fd_var)

Generates C code to initialize the io_uring and submit the first accept.

gen_add($builder, $loop_var, $fd_var)

Generates C code to submit a recv operation for a file descriptor.

gen_del($builder, $loop_var, $fd_var)

Generates C code to close a file descriptor (pending operations will complete with an error).

gen_wait($builder, $loop_var, $events_var, $count_var, $timeout_var)

Generates C code to wait for completions with a timeout.

gen_get_fd($builder, $events_var, $index_var, $fd_var)

Generates C code to extract the operation type and file descriptor from a completion queue entry.

gen_cleanup($builder)

Generates C code to clean up io_uring resources on shutdown.

USER DATA ENCODING

io_uring uses user_data to track operations. This backend encodes the operation type in the high bits and the file descriptor in the low bits:

UD_ACCEPT (0x10000000) - accept operation
UD_READ   (0x20000000) - read/recv operation
UD_WRITE  (0x30000000) - write/send operation
UD_FD_MASK (0x0FFFFFFF) - mask to extract fd

PERFORMANCE

io_uring can achieve 1.5-2x the throughput of epoll for high-concurrency workloads due to:

  • Batched submissions (fewer syscalls)

  • Zero-copy I/O paths

  • Optional kernel-side polling (IORING_SETUP_SQPOLL)

REQUIREMENTS

  • Linux kernel 5.1 or later

  • liburing library: apt install liburing-dev (Debian/Ubuntu) or dnf install liburing-devel (Fedora/RHEL)

AVAILABILITY

Linux 5.1+ with liburing installed.

SEE ALSO

Hypersonic::Event, Hypersonic::Event::Role, Hypersonic::Event::Epoll

AUTHOR

LNATION <email@lnation.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.