Netty 4.2 io_uring Configuration Options Reference

This article provides a comprehensive reference for io_uring-related configuration items introduced in Netty 4.2. It is organized into three configuration layers: system properties (JVM-wide), IoUringIoHandlerConfig (per EventLoop io_uring instance), and ChannelOption (per channel). All settings apply only on Linux with kernel >= 5.14 and CONFIG_IO_URING=y.

0. Prerequisites and Common Issues

Platform: Linux only; io_uring is a Linux kernel capability.

Kernel requirement: Official documentation requires kernel >= 5.14 with CONFIG_IO_URING=y. Features like multishot and bundle depend on newer kernels or distribution backports.

Common startup error: "failed to create io_uring ring fd Cannot allocate memory" usually indicates the user's memlock limit is too low, not actual memory exhaustion.

Configuration precedence: System properties (global, set via -D), IoUringIoHandlerConfig (used when creating the io_uring instance), and ChannelOption (per channel, must be set before channel registration for options like Buffer Ring).

1. System Properties

io.netty.transport.iouring.enforceKernelVersion

Default: true. Enforces kernel version check before allowing io_uring usage. Setting to false forces an attempt even on unsupported kernels, which may cause initialization failures or runtime anomalies.

io.netty.iouring.ringSize

Default: 128. Size of the Submission Queue (SQ), i.e., maximum number of SQEs. Minimum value is 16; powers of two are recommended because the kernel may adjust or reject non-power-of-two sizes. Increase when an EventLoop submits many asynchronous operations per loop (mixed connect/send/receive/file I/O, high concurrency). Larger rings increase initialization and locked-memory overhead.

io.netty.iouring.cqSize

Default: 4096. Size of the Completion Queue (CQ), i.e., maximum number of CQEs. Must be >= ringSize; powers of two recommended. Enlarge when using multishot or when a single system call should harvest more completion events, as a small CQ becomes a bottleneck.

io.netty.iouring.numElementsIoVec

Default: 10240 (10 * IOV_MAX). Maximum elements in the internal IOVEC array, affecting reserved memory size. See the article "How io_uring Sends Packets" for details.

io.netty.iouring.acceptMultiShotEnabled

Default: true. Enables multishot accept (requires kernel support). When supported, a single submitted accept can return multiple new connections, reducing system call and submission overhead. See "io_uring accept multishot or not?".

io.netty.iouring.recvMultiShotEnabled

Default: true. Enables multishot recv (requires kernel support). Reduces repeated submissions and system calls on the receive path.

io.netty.iouring.pollAddMultishotEnabled

Default: true. Enables multishot poll add (requires kernel support). Lowers the cost of re-submitting polling operations.

io.netty.iouring.recvsendBundleEnabled

Default: false. Enables RECV/SEND bundle. Disabled by default due to known kernel bugs/compatibility issues. If enabled, test thoroughly on newer kernels and revert on anomalies. See "What is Buffer Ring in io_uring?".

io.netty.channel.iouring.ipMulticastAll

Default: false. Enables IP_MULTICAST_ALL on io_uring DatagramChannel, altering multicast packet delivery strategy. Keep disabled unless you explicitly need to receive all multicast traffic.

2. IoUringIoHandler Configuration

IoUringIoHandlerConfig

configures the IoUringIoHandler (EventLoop I/O core). These parameters are used only when the io_uring instance is created.

ringSize

Default: 128 (or system property io.netty.iouring.ringSize). SQ size.

cqSize

Default: 4096 (or system property io.netty.iouring.cqSize). Typically 2 * ringSize or 4096. When using multishot, adjust based on concurrency and completion event volume.

singleIssuer

Default: true. Enables IORING_SETUP_SINGLE_ISSUER flag, which usually improves performance but binds the driving IoHandler thread to a single thread (standard EventLoop model). Set to false if you need cross-thread submission or migration.

maxBoundedWorker

Default: 0 (kernel default). Maximum bounded worker threads in the io_uring internal thread pool (IO-WQ). Affects file/blocking operations routed to IO-WQ; minimal impact on pure network I/O.

maxUnboundedWorker

Default: 0 (kernel default). Maximum unbounded worker threads in IO-WQ. Relevant when extending io_uring for file I/O or using FileRegion for sendfile-like operations; monitor to avoid excessive kernel thread creation.

bufferRingConfig

Default: empty. Configures a collection of IoUringBufferRing used with IoUringChannelOption.IO_URING_BUFFER_GROUP_ID. Significantly reduces memory allocation and copy pressure on receive/read/readv paths. Note: Buffer Rings consume additional direct/locked memory; evaluate alongside memlock and direct memory limits.

3. ChannelOption Configuration

IO_URING_BUFFER_GROUP_ID

Applies to SocketChannel / DomainSocketChannel. Specifies the Buffer Ring Group ID for high-performance receives (buffer ring). Must be set before channel registration; changes after registration have no effect. Requires pre-registration of the corresponding buffer ring in IoUringIoHandlerConfig. See "What is Buffer Ring in io_uring?".

IO_URING_WRITE_ZERO_COPY_THRESHOLD

Applies to SocketChannel. Threshold in bytes for zero-copy write ( IORING_OP_SEND_ZC / IORING_OP_SENDMSG_ZC). When write size reaches this threshold, Netty attempts the zero-copy path. Set to -1 to disable. Zero-copy depends on kernel support and system resources; benchmark in target environment.

MAX_DATAGRAM_PAYLOAD_SIZE

Applies to DatagramChannel. Sets maximum datagram payload size for UDP receive buffer strategy and batch receive optimization.

Common Linux Socket Options (also configurable on io_uring channels)

SO_REUSEPORT (Server/Datagram): Allows multiple sockets to bind to the same IP and port; kernel load-balances.

TCP_CORK (Socket): Opposite of TCP_NODELAY; buffers data until conditions met to reduce small packets.

TCP_QUICKACK (Socket): Enables quick ACK (disables Delayed ACK) to lower acknowledgment latency.

TCP_FASTOPEN (Server): Enables TCP Fast Open server support, allowing data during handshake.

TCP_FASTOPEN_CONNECT (Socket client): Enables TCP Fast Open client support.

TCP_DEFER_ACCEPT (Server): Defers accept() return until data arrives or timeout.

TCP_USER_TIMEOUT (Socket): Sets TCP user timeout in milliseconds for precise dead-connection detection.

TCP_NOTSENT_LOWAT (Socket): Controls low-water mark for unsent data queue, reducing send buffer queuing latency.

TCP_KEEPIDLE (Socket): TCP KeepAlive idle time before probes (seconds).

TCP_KEEPINTVL (Socket): TCP KeepAlive probe interval (seconds).

TCP_KEEPCNT (Socket): TCP KeepAlive probe count before declaring connection dead.

IP/Network Layer Options

IP_FREEBIND (Server/Datagram): Allows binding to non-local or unconfigured IP addresses.

IP_TRANSPARENT (Server/Datagram/Socket): Enables transparent proxy support (bind/listen on non-local IPs).

IP_MULTICAST_ALL (Datagram): Modifies multicast group packet delivery strategy.