uring v0.0.0-alpha2 — Pure Go io_uring alpha2 for Linux 6.18+

[hayabusa-cloud]

Introduction

uring is a minimal, pure Go io_uring library for Linux 6.18+. It handles
ring setup and teardown, SQE preparation, CQE decoding, and identity transport
through the kernel's 64-bit user_data field. On top of that it provides
buffer registration, provided buffer rings, multishot operations, zero-copy
send/receive, multicast helpers, and listener-setup primitives.

The design keeps the same boundary established in the initial alpha release:
kernel-facing mechanics and completion facts live at the API surface, while
scheduling, retry, and orchestration stay in higher layers. There is no built-
in event loop, scheduler, or goroutine management. In the dependency graph
uring still sits between the foundation packages (zcall, iox, iofd,
iobuf, sock, spin, dwcas, framer) and the proactor/runtime layers
above.

The hot submit-and-reap paths remain zero-allocation. SQEContext still packs
submission metadata into the 64-bit user_data field that the kernel round-
trips in every CQE. This alpha2 release keeps that model intact while
hardening wrapper correctness, lifecycle documentation, and release readiness.
The result is a stronger alpha baseline for callers building runtimes,
dispatchers, or protocol engines on top of uring.

Usage

Drive completion reaping explicitly and keep retry policy in caller code:

ring, err := uring.New(func(o *uring.Options) {
    o.Entries = uring.EntriesMedium
})
if err != nil {
    return err
}
if err := ring.Start(); err != nil {
    return err
}
defer ring.Stop()

cqes := make([]uring.CQEView, 64)
var backoff iox.Backoff

for {
    n, err := ring.Wait(cqes)
    if errors.Is(err, iox.ErrWouldBlock) {
        backoff.Wait()
        continue
    }
    if err != nil {
        return err
    }
    if n == 0 {
        backoff.Wait()
        continue
    }

    backoff.Reset()
    for i := range n {
        cqe := cqes[i]
        if cqe.Res < 0 {
            return fmt.Errorf("completion failed: op=%d fd=%d res=%d", cqe.Op(), cqe.FD(), cqe.Res)
        }
        fmt.Printf("completed op=%d on fd=%d with res=%d\n", cqe.Op(), cqe.FD(), cqe.Res)
    }
    break
}

Highlights

v0.0.0-alpha2 is a hardening release for the standalone uring package. It
keeps the alpha1 surface area and design boundary, but improves the contract at
the package edge: wrapper APIs now preserve caller-selected SQE flags, direct-
slot/fixed-file paths behave correctly, lifecycle and teardown rules are more
explicit, and the current Linux-facing surface has been revalidated with broad
package tests and cross-build checks.

Architecture Continuity

The same core model from alpha1 remains in place:

• SQEContext is still the submission identity token and continues to round-
  trip operation metadata through user_data.
• Direct, indirect, and extended submission modes still cover the common
  zero-allocation path plus the wider payload cases.
• Multishot, provided-buffer, listener, and zero-copy oriented APIs remain part
  of the package surface.
• Scheduling and retry policy still belong to callers, not to uring itself.

What's Changed

Bug Fixes

• Preserve caller SQE flags across convenience wrappers so direct-slot and
  fixed-file operations keep IOSQE_FIXED_FILE and related caller-selected
  bits intact.
• Correct the wrapper-layer flag merge behavior for connect-style paths, fixing
  a real direct-socket failure mode that could surface as -ENOTSOCK when a
  registered-file slot was misinterpreted as a raw file descriptor.

Features

• Add SQEContext.OrFlags as an additive flag combinator for callers and
  wrapper code that must extend existing SQE flags without clobbering them.

Improvements

• Tighten lifecycle documentation around Start/Stop, Close,
  multishot retirement, and listener setup so caller-owned teardown rules are
  explicit at the package boundary.
• Improve poll-related integration and example coverage so tests follow the
  package's real wait/enter contract instead of timing guesses.
• Keep the hot flag-composition path zero-allocation and inline-friendly while
  fixing wrapper correctness.

Compatibility

• Go: 1.26+
• Platforms: Linux 6.18+

---

This discussion was created from the release uring v0.0.0-alpha2 — Pure Go io_uring alpha2 for Linux 6.18+.