ring

package
v0.30.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package ring — range 0.1.3.* (ADR 0005 kernel/collections/ring block).

Package ring — declares the sentinels returned by this package's constructor and TryWrite / TryRead operations. Each var's name equals its errs.Define Reason in SCREAMING_SNAKE form.

Package ring provides a lock-free single-producer / single-consumer (SPSC) ring buffer built on sync/atomic. The SPSC constraint gives the maximum throughput for any hot-path producer that serialises enqueues — metrics batch writers, streaming codec pipelines, event-bus accumulators, or any other fixed-capacity non-blocking FIFO use case. Domain-neutral by design per the internal/kernel/ package rule (stdlib-only AND generic).

SPSC means EXACTLY ONE goroutine calls TryWrite at a time AND EXACTLY ONE goroutine calls TryRead at a time. Concurrent producers or concurrent consumers are NOT safe on a Queue — those callers serialise upstream, or take the MPSC sibling: NewMulti returns a MultiQueue, the same four methods under the wider contract of any number of TryWrite callers and exactly one TryRead caller (Vyukov's bounded queue, a sequence number per cell, a power-of-two capacity).

The SPSC ring keeps its consumer's cursor and its producer's each on a cache line of their own, with a cached copy of the other side's (read again only when the ring looks full or empty), and masks a cursor into a power-of-two storage instead of dividing (#1034).

Index

Constants

View Source
const CodeRingCapZero errs.Code = 0x00_01_03_03 // 0.1.3.3

CodeRingCapZero identifies a New call made with a non-positive capacity.

View Source
const CodeRingEmpty errs.Code = 0x00_01_03_02 // 0.1.3.2

CodeRingEmpty identifies a TryRead call on an empty ring buffer.

View Source
const CodeRingFull errs.Code = 0x00_01_03_01 // 0.1.3.1

CodeRingFull identifies a TryWrite call on a saturated ring buffer.

Variables

View Source
var (
	// Full is returned by TryWrite when the ring has no slot available; the
	// caller decides whether to drop, block, or retry depending on its
	// upstream policy (e.g. async sink's DropOldest / DropNewest).
	Full = errs.Static(CodeRingFull, "RING_FULL",
		"Ring buffer is at capacity",
		"internal/kernel/collections/ring.TryWrite called on a full ring",
		0,
		0)

	// Empty is returned by TryRead when no item is available; the caller
	// decides whether to spin, sleep, or block on a wake signal.
	Empty = errs.Static(CodeRingEmpty, "RING_EMPTY",
		"Ring buffer is empty",
		"internal/kernel/collections/ring.TryRead called on an empty ring",
		0,
		0)

	// CapZero is returned by New when the requested capacity is non-positive.
	CapZero = errs.Static(CodeRingCapZero, "RING_CAP_ZERO",
		"Ring buffer capacity must be positive",
		"internal/kernel/collections/ring.New called with cap <= 0",
		0,
		0)
)

Functions

func Drain added in v0.27.0

func Drain[T any](q Queue[T]) iter.Seq[T]

Drain yields the items q holds, oldest first, reading each with TryRead until q reports Empty: the consumer's loop over the ring, as an iterator.

It is the consumer's side, so it is bound by the same rule as TryRead: only the one consumer goroutine ranges over it. An item the producer writes while the loop runs is yielded too; a loop that breaks early leaves the rest in q. Nothing is allocated.

Types

type MultiQueue added in v0.28.0

type MultiQueue[T any] interface {
	// TryWrite enqueues item without blocking; returns Full when saturated.
	// Any number of goroutines may call it at once.
	TryWrite(item T) (err error)
	// TryRead dequeues the next item without blocking; returns Empty when no
	// item is available, including while the writer that claimed the next
	// slot has not finished storing into it. One goroutine only.
	TryRead() (item T, err error)
	// Capacity returns the number of usable slots in the ring.
	Capacity() (n int)
	// Len returns a snapshot count of items currently held, a claimed slot
	// still being written included.
	Len() (n int)
}

MultiQueue is the lock-free MPSC ring contract: any number of goroutines call TryWrite at once; exactly one calls TryRead. Capacity is fixed at construction time, a power of two.

func NewMulti added in v0.28.0

func NewMulti[T any](capacity int) (q MultiQueue[T], err error)

NewMulti constructs a MultiQueue holding the power of two at least capacity, which Capacity then reports: CapZero when capacity is not positive.

IFACE-PLUGIN: callers receive a MultiQueue[T] handle; the concrete struct is unexported. Its four methods are Queue's, so a MultiQueue is also a Queue — Drain reads it — but its contract is the wider one.

It is not a drop-in for a Queue behind a mutex. Measured (BENCH.md), one producer hands a record over in ~25 ns where the mutex takes ~85, but four producers saturating the ring take ~417 ns a record where the mutex takes ~235: every writer's claim contends on one cursor while the mutex parks its losers. And no writer may read: behind a mutex, a writer that finds the ring full can evict the oldest record and store its own in one critical section, so the newest record is always admitted; here that eviction can only be the reader's, and the writer waits for it or loses its own record. Those two are why the SDK's async log sink keeps its Queue behind a mutex, with its drop-oldest policy as it is (ADR 0216, #805).

type Queue

type Queue[T any] interface {
	// TryWrite enqueues item without blocking; returns Full when saturated.
	TryWrite(item T) (err error)
	// TryRead dequeues the next item without blocking; returns Empty when no
	// item is available.
	TryRead() (item T, err error)
	// Capacity returns the number of usable slots in the ring.
	Capacity() (n int)
	// Len returns a snapshot count of items currently held.
	Len() (n int)
}

Queue is the lock-free SPSC ring contract. Producer threads call TryWrite; consumer threads call TryRead. Capacity is fixed at construction time.

func New

func New[T any](capacity int) (q Queue[T], err error)

New constructs a Queue with the supplied logical capacity.

IFACE-PLUGIN: callers receive a Queue[T] handle so the kernel can swap the backing implementation (single-buffer today, sharded SPMC tomorrow) without breaking call-site code; the concrete struct is unexported.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL