Deprecated: moved into github.com/kitsunium/sdk/internal (ADR 0171), which no consumer imports; update with: go get github.com/kitsunium/sdk/pkg/v1/<family>@latest for each family you import && go mod tidy
Documentation
¶
Overview ¶
Package ring — range 0.1.3.* (ADR 0005 kernel/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 — those callers should serialise upstream or wrap this primitive with a mutex. The logger async sink takes the mutex- serialisation route (see internal/service/logger/middleware/async); other domains pick whichever coordination fits their topology.
Index ¶
Constants ¶
const CodeRingCapZero errs.Code = 0x00_01_03_03 // 0.1.3.3
CodeRingCapZero identifies a New call made with a non-positive capacity.
const CodeRingEmpty errs.Code = 0x00_01_03_02 // 0.1.3.2
CodeRingEmpty identifies a TryRead call on an empty ring buffer.
const CodeRingFull errs.Code = 0x00_01_03_01 // 0.1.3.1
CodeRingFull identifies a TryWrite call on a saturated ring buffer.
Variables ¶
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.Define(CodeRingFull, "RING_FULL", "Ring buffer is at capacity", "internal/kernel/ring.TryWrite called on a full ring") // 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.Define(CodeRingEmpty, "RING_EMPTY", "Ring buffer is empty", "internal/kernel/ring.TryRead called on an empty ring") // CapZero is returned by New when the requested capacity is non-positive. CapZero = errs.Define(CodeRingCapZero, "RING_CAP_ZERO", "Ring buffer capacity must be positive", "internal/kernel/ring.New called with cap <= 0") )
Functions ¶
This section is empty.
Types ¶
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.
Source Files