# flare.runtime.io_uring_abi

> A module of flare_mlake's API.

``flare.runtime.io_uring_abi`` -- io_uring ABI constants + byte codec.

The kernel ABI constant tables (opcodes, SQE/CQE/setup/enter flags,
poll-event bits, struct sizes + field offsets) and the bounds-checked
byte read/write helpers (``_store_*`` / ``_load_*`` / ``_check_opcode``)
that the SQE/CQE codec in :mod:`flare.runtime.io_uring_sqe` builds on.
Split out of ``io_uring_sqe.mojo`` to keep that module within the
file-size budget; ``io_uring_sqe`` re-exports every name here so
existing ``from flare.runtime.io_uring_sqe import IORING_OP_*`` (and
every other constant / helper) call site keeps resolving unchanged.

References: ``include/uapi/linux/io_uring.h`` (canonical layout).

## Aliases

### `IORING_OP_NOP`

```mojo
comptime IORING_OP_NOP = Int(0)
```

5.1+. No-op; useful for testing the SQ/CQ round-trip.

### `IORING_OP_READV`

```mojo
comptime IORING_OP_READV = Int(1)
```

5.1+. Vectored read.

### `IORING_OP_WRITEV`

```mojo
comptime IORING_OP_WRITEV = Int(2)
```

5.1+. Vectored write — what flare uses to coalesce status + headers + body in a single submission (the writev(2) path on the io_uring backend; subsumes the epoll-fallback ``writev(2)``).

### `IORING_OP_FSYNC`

```mojo
comptime IORING_OP_FSYNC = Int(3)
```

5.1+. fsync(2) async.

### `IORING_OP_READ_FIXED`

```mojo
comptime IORING_OP_READ_FIXED = Int(4)
```

5.1+. Read into a pre-registered buffer (file-serve fast path).

### `IORING_OP_WRITE_FIXED`

```mojo
comptime IORING_OP_WRITE_FIXED = Int(5)
```

5.1+. Write from a pre-registered buffer.

### `IORING_OP_POLL_ADD`

```mojo
comptime IORING_OP_POLL_ADD = Int(6)
```

5.1+. Async poll on an fd.

### `IORING_OP_POLL_REMOVE`

```mojo
comptime IORING_OP_POLL_REMOVE = Int(7)
```

5.1+. Cancel a previous POLL_ADD.

### `IORING_OP_SENDMSG`

```mojo
comptime IORING_OP_SENDMSG = Int(9)
```

5.3+. sendmsg(2) async.

### `IORING_OP_RECVMSG`

```mojo
comptime IORING_OP_RECVMSG = Int(10)
```

5.3+. recvmsg(2) async.

### `IORING_OP_TIMEOUT`

```mojo
comptime IORING_OP_TIMEOUT = Int(11)
```

5.4+. Timeout on a CQE; useful for arming a wakeup.

### `IORING_OP_TIMEOUT_REMOVE`

```mojo
comptime IORING_OP_TIMEOUT_REMOVE = Int(12)
```

5.5+. Cancel a previous TIMEOUT.

### `IORING_OP_ACCEPT`

```mojo
comptime IORING_OP_ACCEPT = Int(13)
```

5.5+. accept4(2) async — the listener-socket fast path.

### `IORING_OP_ASYNC_CANCEL`

```mojo
comptime IORING_OP_ASYNC_CANCEL = Int(14)
```

5.5+. Cancel an in-flight SQE by user_data; the ``Cancel.SHUTDOWN`` plumbing on the io_uring backend uses this to interrupt long-running multishot recvs.

### `IORING_OP_LINK_TIMEOUT`

```mojo
comptime IORING_OP_LINK_TIMEOUT = Int(15)
```

5.5+. Linked timeout.

### `IORING_OP_CONNECT`

```mojo
comptime IORING_OP_CONNECT = Int(16)
```

5.5+. connect(2) async.

### `IORING_OP_CLOSE`

```mojo
comptime IORING_OP_CLOSE = Int(19)
```

5.6+. close(2) async — used to drop the per-connection fd without a syscall round-trip on the response-completion path.

### `IORING_OP_PROVIDE_BUFFERS`

```mojo
comptime IORING_OP_PROVIDE_BUFFERS = Int(31)
```

5.7+. Register a pool of buffers for ``IOSQE_BUFFER_SELECT`` recvs. Slow path -- one SQE per refill. flare ships a faster ring-mapped variant via :data:`IORING_REGISTER_PBUF_RING` (5.19+, 2.7x faster per Linux kernel benchmarks); see ``UringReactor.register_pbuf_ring``.

### `IORING_REGISTER_BUFFERS`

```mojo
comptime IORING_REGISTER_BUFFERS = Int(0)
```

5.1+. Register fixed buffers for IORING_OP_READ_FIXED / WRITE_FIXED. Not used by flare's HTTP path.

### `IORING_REGISTER_PBUF_RING`

```mojo
comptime IORING_REGISTER_PBUF_RING = Int(22)
```

5.19+. Register a kernel-mapped provided-buffer ring for use with ``IOSQE_BUFFER_SELECT``. Replaces the per-CQE ``IORING_OP_PROVIDE_BUFFERS`` SQE refill with a userspace tail-bump on shared memory -- 2.7x faster (27M vs 10M ops/sec kernel-bench, replenish-1 measurement). The ring memory is ``sizeof(struct io_uring_buf) * ring_entries`` (16 bytes each), page-aligned, shared with the kernel.

### `IORING_UNREGISTER_PBUF_RING`

```mojo
comptime IORING_UNREGISTER_PBUF_RING = Int(23)
```

5.19+. Companion to :data:`IORING_REGISTER_PBUF_RING`.

### `IORING_SETUP_IOPOLL`

```mojo
comptime IORING_SETUP_IOPOLL = UInt32(1)
```

5.1+. Block-IO polling instead of interrupt-driven completions. Not for network sockets.

### `IORING_SETUP_SQPOLL`

```mojo
comptime IORING_SETUP_SQPOLL = UInt32(2)
```

5.1+. Kernel polls the SQ; userspace doesn't need to call ``io_uring_enter`` for submission. Trades one always-busy kernel thread per ring for zero-syscall submission. Useful for very high SQE rates (> 1 M/s) but requires CAP_SYS_NICE on some kernels OR registered file descriptors.

### `IORING_SETUP_SQ_AFF`

```mojo
comptime IORING_SETUP_SQ_AFF = UInt32(4)
```

5.1+. Pin the SQPOLL thread to ``sq_thread_cpu``.

### `IORING_SETUP_CQSIZE`

```mojo
comptime IORING_SETUP_CQSIZE = UInt32(8)
```

5.1+. Use ``params.cq_entries`` to override the default ``2 * sq_entries`` CQ size.

### `IORING_SETUP_CLAMP`

```mojo
comptime IORING_SETUP_CLAMP = UInt32(16)
```

5.6+. Clamp ``entries`` / ``cq_entries`` to the kernel max instead of failing with EINVAL.

### `IORING_SETUP_ATTACH_WQ`

```mojo
comptime IORING_SETUP_ATTACH_WQ = UInt32(32)
```

5.6+. Share the io-wq workers with another ring (specified in ``params.wq_fd``).

### `IORING_SETUP_R_DISABLED`

```mojo
comptime IORING_SETUP_R_DISABLED = UInt32(64)
```

5.10+. Start the ring in disabled state; enable later via io_uring_register(IORING_REGISTER_ENABLE_RINGS).

### `IORING_SETUP_SUBMIT_ALL`

```mojo
comptime IORING_SETUP_SUBMIT_ALL = UInt32(128)
```

5.18+. ``io_uring_enter`` continues processing the SQ on a per-SQE error rather than aborting the batch. Eliminates the 'first SQE in batch errored, rest of batch lost' failure mode under SQ pressure.

### `IORING_SETUP_COOP_TASKRUN`

```mojo
comptime IORING_SETUP_COOP_TASKRUN = UInt32(256)
```

5.19+. Don't use IPI-driven task work; instead, run task work cooperatively at io_uring_enter boundaries. Lower CPU overhead for the common case of a single thread per ring (which flare's per-worker UringReactor is). Combined with TASKRUN_FLAG below it tells userspace when to call enter.

### `IORING_SETUP_TASKRUN_FLAG`

```mojo
comptime IORING_SETUP_TASKRUN_FLAG = UInt32(512)
```

5.19+. Sets ``IORING_SQ_TASKRUN`` in ``sq_ring->flags`` when there's pending task work. Userspace can poll the flag to know when to call ``io_uring_enter`` to run pending completions. Pairs with COOP_TASKRUN.

### `IORING_SETUP_SQE128`

```mojo
comptime IORING_SETUP_SQE128 = UInt32(1024)
```

5.19+. Doubles SQE size to 128 bytes. flare's SQE codecs still target 64-byte SQEs; not enabled.

### `IORING_SETUP_CQE32`

```mojo
comptime IORING_SETUP_CQE32 = UInt32(2048)
```

5.19+. Doubles CQE size to 32 bytes. flare's CQE codecs still target 16-byte CQEs; not enabled.

### `IORING_SETUP_SINGLE_ISSUER`

```mojo
comptime IORING_SETUP_SINGLE_ISSUER = UInt32(4096)
```

6.0+. Promise to the kernel that only one thread will submit SQEs to this ring. Lets the kernel skip atomic operations on the SQ submit path. flare's per-worker UringReactor matches this contract (each worker owns its own ring + drives it from one pthread). Required by DEFER_TASKRUN.

### `IORING_SETUP_DEFER_TASKRUN`

```mojo
comptime IORING_SETUP_DEFER_TASKRUN = UInt32(8192)
```

6.1+. The kernel runs task work ONLY when the app calls ``io_uring_enter`` (with the GETEVENTS flag). Batches CQE delivery to enter boundaries; eliminates the IPI-driven mid-syscall task work that interferes with the dispatch loop's CQE-drain rhythm. Highest-impact flag for the bufring throughput throttle when paired with SINGLE_ISSUER.

### `IORING_SETUP_NO_MMAP`

```mojo
comptime IORING_SETUP_NO_MMAP = UInt32(16384)
```

6.5+. Userspace allocates the SQ/CQ rings; kernel mmaps into them. Not used by flare.

### `IORING_SETUP_REGISTERED_FD_ONLY`

```mojo
comptime IORING_SETUP_REGISTERED_FD_ONLY = UInt32(32768)
```

6.5+. Only registered fds can be passed to SQEs. Not used by flare.

### `IORING_OP_REMOVE_BUFFERS`

```mojo
comptime IORING_OP_REMOVE_BUFFERS = Int(32)
```

5.7+. Drop a previously-provided buffer pool.

### `IORING_OP_SEND`

```mojo
comptime IORING_OP_SEND = Int(26)
```

5.6+. send(2) async.

### `IORING_OP_RECV`

```mojo
comptime IORING_OP_RECV = Int(27)
```

5.6+. recv(2) async — the per-connection request-read fast path on the io_uring backend (combined with ``IORING_RECV_MULTISHOT`` from 6.0+ for the steady-state).

### `IORING_OP_READ`

```mojo
comptime IORING_OP_READ = Int(22)
```

5.6+. read(2) / pread(2) async — works on **any fd** (not just sockets). Used for the cross-thread wakeup eventfd: ``IORING_OP_RECV`` returns ``-ENOTSOCK`` on an eventfd, but ``IORING_OP_READ`` does the right thing.

### `IORING_OP_WRITE`

```mojo
comptime IORING_OP_WRITE = Int(23)
```

5.6+. write(2) / pwrite(2) async — companion to ``IORING_OP_READ``.

### `IORING_OP_OPENAT`

```mojo
comptime IORING_OP_OPENAT = Int(18)
```

5.6+. openat(2) async.

### `IOSQE_FIXED_FILE`

```mojo
comptime IOSQE_FIXED_FILE = UInt8(1)
```

5.1+. The ``fd`` field is an index into the registered-files table set up via ``IORING_REGISTER_FILES`` (skips the syscall ``fdtable`` lookup).

### `IOSQE_IO_DRAIN`

```mojo
comptime IOSQE_IO_DRAIN = UInt8(2)
```

5.2+. Drain the SQ before submitting this SQE.

### `IOSQE_IO_LINK`

```mojo
comptime IOSQE_IO_LINK = UInt8(4)
```

5.3+. Link the next SQE to this one — the next SQE is deferred until this one completes successfully. flare uses this to chain ``recv → process → send`` without round-tripping userspace on the keep-alive hot path.

### `IOSQE_IO_HARDLINK`

```mojo
comptime IOSQE_IO_HARDLINK = UInt8(8)
```

5.5+. Like ``IOSQE_IO_LINK`` but the next SQE runs even on this one's failure.

### `IOSQE_ASYNC`

```mojo
comptime IOSQE_ASYNC = UInt8(16)
```

5.6+. Force the operation to be processed by the kernel worker thread pool (vs. inline).

### `IOSQE_BUFFER_SELECT`

```mojo
comptime IOSQE_BUFFER_SELECT = UInt8(32)
```

5.7+. The kernel picks the buffer from a previously-provided buffer pool (used with ``IORING_OP_RECV`` for the steady-state per-connection recv).

### `IOSQE_CQE_SKIP_SUCCESS`

```mojo
comptime IOSQE_CQE_SKIP_SUCCESS = UInt8(64)
```

5.17+. Don't post a CQE on success — used for fire-and- forget ops like ``IORING_OP_CLOSE`` after the response has been flushed.

### `IORING_RECV_MULTISHOT`

```mojo
comptime IORING_RECV_MULTISHOT = UInt32(2)
```

Kernel 6.0+. Set in ``sqe->ioprio`` (NOT ``msg_flags``!) to make an ``IORING_OP_RECV`` rearm itself after each completion. Each CQE includes ``IORING_CQE_F_MORE`` while the multishot is still armed; the kernel disarms on terminal errors (EOF, RST, ENOBUFS, etc) which surface as a CQE without ``F_MORE`` -- userspace re-arms then. The MULTISHOT bit is extracted from the ``recv_flags`` parameter of :func:`prep_recv` / :func:`prep_recv_buffer_select` and routed to ``sqe->ioprio`` automatically; callers don't need to handle the split. Kernel source: ``io_uring/net.c::io_recv_prep`` reads it via ``READ_ONCE(sqe->ioprio)``.

### `IORING_RECVSEND_POLL_FIRST`

```mojo
comptime IORING_RECVSEND_POLL_FIRST = UInt32(1)
```

Kernel 5.19+. Set in ``sqe->ioprio`` to force a poll before the recv/send is attempted. Like MULTISHOT, this bit is extracted from ``recv_flags`` / ``send_flags`` and routed to ``sqe->ioprio`` by flare's prep helpers.

### `IORING_ACCEPT_MULTISHOT`

```mojo
comptime IORING_ACCEPT_MULTISHOT = UInt32(1)
```

5.19+. Set in the SQE ``op_flags`` (accept_flags) on ``IORING_OP_ACCEPT``. Same idea — the listener socket keeps firing accept completions without re-submission.

### `IORING_POLL_ADD_MULTI`

```mojo
comptime IORING_POLL_ADD_MULTI = UInt32(1)
```

5.13+. Set in the SQE ``len`` field on ``IORING_OP_POLL_ADD`` to request a *multishot* poll: the kernel posts a CQE every time the requested poll mask is reached, without requiring userspace to re-arm. ``IORING_CQE_F_MORE`` in the CQE's ``flags`` indicates the multishot is still armed.

This is the io_uring analog of edge-triggered ``epoll_wait``
with ``EPOLLET`` — it lets a single SQE drive an arbitrary
number of readiness notifications, which is the substrate
that the upcoming server-loop dispatch swap (B0 wire-in)
uses to replace the per-poll ``epoll_wait`` syscall on the
io_uring backend.

### `IORING_POLL_UPDATE_EVENTS`

```mojo
comptime IORING_POLL_UPDATE_EVENTS = UInt32(2)
```

5.13+. Set in the SQE ``len`` field on ``IORING_OP_POLL_REMOVE`` to indicate the SQE is a *modify* of an existing poll's event mask, not a remove.

### `IORING_POLL_UPDATE_USER_DATA`

```mojo
comptime IORING_POLL_UPDATE_USER_DATA = UInt32(4)
```

5.13+. Set in the SQE ``len`` field on ``IORING_OP_POLL_REMOVE`` to indicate the SQE is a *modify* of an existing poll's user_data tag.

### `POLLIN`

```mojo
comptime POLLIN = UInt32(1)
```

Data ready to read (analog of ``EPOLLIN``).

### `POLLPRI`

```mojo
comptime POLLPRI = UInt32(2)
```

Urgent data ready (analog of ``EPOLLPRI``).

### `POLLOUT`

```mojo
comptime POLLOUT = UInt32(4)
```

Writable without blocking (analog of ``EPOLLOUT``).

### `POLLERR`

```mojo
comptime POLLERR = UInt32(8)
```

Error condition (analog of ``EPOLLERR``).

### `POLLHUP`

```mojo
comptime POLLHUP = UInt32(16)
```

Peer hung up (analog of ``EPOLLHUP``).

### `POLLRDHUP`

```mojo
comptime POLLRDHUP = UInt32(8192)
```

Peer closed for writing (analog of ``EPOLLRDHUP``). Linux-specific; not in POSIX.

### `IORING_CQE_F_BUFFER`

```mojo
comptime IORING_CQE_F_BUFFER = UInt32(1)
```

The CQE's ``flags`` high 16 bits encode the buffer-id picked by ``IOSQE_BUFFER_SELECT``.

### `IORING_CQE_F_MORE`

```mojo
comptime IORING_CQE_F_MORE = UInt32(2)
```

More CQEs are coming for this SQE (multishot accept / recv). When unset, the multishot has finished and the userspace driver must re-arm if it still wants events.

### `IORING_CQE_F_SOCK_NONEMPTY`

```mojo
comptime IORING_CQE_F_SOCK_NONEMPTY = UInt32(4)
```

5.19+. The socket's recv buffer still has data after the completion drained one chunk; the driver should keep reaping without re-arming poll.

### `IORING_ENTER_GETEVENTS`

```mojo
comptime IORING_ENTER_GETEVENTS = UInt32(1)
```

Wait for completions in ``io_uring_enter``.

### `IORING_ENTER_SQ_WAKEUP`

```mojo
comptime IORING_ENTER_SQ_WAKEUP = UInt32(2)
```

Wake the SQ-poll thread (only relevant with ``IORING_SETUP_SQPOLL``).

### `IORING_ENTER_SQ_WAIT`

```mojo
comptime IORING_ENTER_SQ_WAIT = UInt32(4)
```

Wait for the SQ to drain before returning.

### `IORING_ENTER_EXT_ARG`

```mojo
comptime IORING_ENTER_EXT_ARG = UInt32(8)
```

5.11+. ``io_uring_enter``'s fifth argument points at an ``io_uring_getevents_arg`` (carrying a wait timeout) instead of a signal mask.

### `IO_URING_SQE_BYTES`

```mojo
comptime IO_URING_SQE_BYTES = Int(64)
```

Size of the kernel ``struct io_uring_sqe``. Constant since 5.1; ``IORING_SETUP_SQE128`` (5.19+) doubles it but flare doesn't enable that mode.

### `IO_URING_CQE_BYTES`

```mojo
comptime IO_URING_CQE_BYTES = Int(16)
```

Size of the kernel ``struct io_uring_cqe``. Constant since 5.1; ``IORING_SETUP_CQE32`` (5.19+) doubles it but flare doesn't enable that mode.