Configuration / Runtime

Runtime

The runtime owns socket I/O for each worker. Select it with the tagged [runtime] table.

Auto

[runtime]
type = "auto"
max_events = 1024
sq_entries = 4096
cq_entries = 8192
buf_ring_size = 16384
buf_size = 8192

On Linux, Thwip probes required io_uring operations and provided-buffer registration. It uses io_uring when supported and logs why it falls back to epoll otherwise. macOS and BSD select kqueue. Use this mode for portable deployments.

Epoll and kqueue

# Linux
[runtime]
type = "epoll"
max_events = 1024

# macOS and BSD
[runtime]
type = "kqueue"
max_events = 1024

max_events is the maximum readiness notifications collected per polling batch. It defaults to 1024 and must exceed zero.

io_uring

[runtime]
type = "io_uring"
sq_entries = 4096
cq_entries = 8192
buf_ring_size = 16384
buf_size = 8192

Key	Default	Meaning and constraint
`sq_entries`	4096	Submission entries; greater than zero.
`cq_entries`	8192	Completion entries; greater than zero.
`buf_ring_size`	16384	Provided buffers; power of two from 1 through 32768.
`buf_size`	8192 bytes	Each receive buffer; greater than zero.

Explicit io_uring is Linux-only and fails startup if required capabilities are missing; it does not silently fall back.

Choosing a mode

auto: portable deployment.
epoll: explicit Linux readiness behavior or older kernels.
kqueue: explicit macOS/BSD behavior.
io_uring: a verified Linux host where completion I/O is required.

An omitted runtime currently means epoll, not auto.