Skip to content

ringbuf: add UnsafeReader for zero-copy reads with deferred commit#1981

Closed
orishuss wants to merge 1 commit into
cilium:mainfrom
orishuss:ringbuf-unsafe-reader
Closed

ringbuf: add UnsafeReader for zero-copy reads with deferred commit#1981
orishuss wants to merge 1 commit into
cilium:mainfrom
orishuss:ringbuf-unsafe-reader

Conversation

@orishuss
Copy link
Copy Markdown
Contributor

@orishuss orishuss commented Apr 12, 2026

Summary

Supersedes #1968. Implements the separate UnsafeReader type as recommended by @ti-mo and @florianl in the review of #1968, rather than adding zero-copy methods directly to Reader.

Changes

  • UnsafeReader — new type for zero-copy ring buffer reads. Returns UnsafeRecord with RawSample pointing directly into the mmap'd ring buffer region. Separate type from Reader so the two APIs can't be mixed accidentally.
  • UnsafeRecord — wraps Record via embedding. Compile-time type safety: you can't pass *UnsafeRecord to Reader.ReadInto or *Record to UnsafeReader.Read.
  • CommitToken — opaque token (unexported consPos field) returned by Read. User can't inspect or forge it.
  • Commit(token) — per-token commit with ordered advancement. Consumer position only advances when all preceding tokens are also committed (e.g. commit B,C then A → advances past C).
  • CommitAll() — batch commit, advances consumer to the latest read position.
  • ReadFunc(func([]byte)) — callback-based read with implicit auto-commit after the callback returns.

Architecture

Addresses @ti-mo and @florianl's feedback from #1968:

  1. Separate typeUnsafeReader is distinct from Reader. No mixing of safe and unsafe APIs on the same type.
  2. Shared internals, no duplication — both embed readerBase which provides Close, SetDeadline, BufferSize, Flush, AvailableBytes, and the poll loop (readWaitLocked).
  3. Clean eventRing interface — only exposes primitives both readers use: readRecordUnsafe, advanceTo, pendingPosition. No readRecord on the ring — that logic lives in safeRing, a small wrapper used only by Reader.
  4. safeRing — wraps eventRing to provide readRecord (readRecordUnsafe + copy + advanceTo). Keeps Reader's API and behavior identical to today.
  5. Callback supportReadFunc receives []byte (not Record-driven), auto-commits after the callback.
  6. Concurrency documented — Read/Commit/CommitAll are goroutine-safe (mutex). RawSample validity after commit is the caller's responsibility.

File layout

File Contents
ring.go eventRing interface, ringbufHeader, ringReader (readRecordUnsafe, advanceTo, pendingPosition)
reader_base.go errors, poller, Record, readerBase + shared methods, initReaderBase
reader.go safeRing, Reader, NewReader, Read, ReadInto
unsafe_reader.go UnsafeRecord, CommitToken, UnsafeReader, NewUnsafeReader, Read, ReadFunc, Commit, CommitAll
unsafe_reader_test.go 10 tests + 2 benchmarks

No changes to ring_other.go, ring_windows.go, reader_test.go, or platform files.

Signed-off-by: Ori Shussman <orishuss@gmail.com>
@orishuss orishuss force-pushed the ringbuf-unsafe-reader branch from 0490c85 to 14483fb Compare April 12, 2026 12:23
@orishuss orishuss changed the title ringbuf unsafe reader ringbuf: add UnsafeReader for zero-copy reads with deferred commit Apr 12, 2026
@orishuss orishuss marked this pull request as ready for review April 12, 2026 12:26
@orishuss orishuss requested a review from florianl as a code owner April 12, 2026 12:26
@ti-mo
Copy link
Copy Markdown
Contributor

ti-mo commented Apr 13, 2026

Closing as duplicate of #1979.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants