ringbuf

Documentation

Overview

Package ringbuf implements the SDK's bounded pending buffer. It is a circular FIFO bounded by both an item count and a byte budget. On overflow it evicts the oldest entries ("drop-oldest, newest wins") and reports how many were dropped, so the pipeline can account for them. All operations are safe for concurrent use.

Index

• type Buffer
  • func New[T any](maxItems, maxBytes int, sizeOf Sizer[T]) *Buffer[T]
  • func (b *Buffer[T]) Bytes() int
  • func (b *Buffer[T]) DrainAll() []T
  • func (b *Buffer[T]) Len() int
  • func (b *Buffer[T]) PopBatch(maxItems, maxBytes int) []T
  • func (b *Buffer[T]) Push(item T) (dropped int)
• type Sizer

Types

type Buffer

type Buffer[T any] struct {
	// contains filtered or unexported fields
}

Buffer is a bounded circular FIFO. Construct one with New; the zero value is not usable.

func New

func New[T any](maxItems, maxBytes int, sizeOf Sizer[T]) *Buffer[T]

New returns a buffer bounded by maxItems entries and maxBytes total estimated size. Non-positive bounds fall back to permissive defaults. sizeOf may be nil, in which case every item is counted as one byte.

func (*Buffer[T]) Bytes

func (b *Buffer[T]) Bytes() int

Bytes returns the current estimated size of buffered entries.

func (*Buffer[T]) DrainAll

func (b *Buffer[T]) DrainAll() []T

DrainAll removes and returns every entry, oldest first.

func (*Buffer[T]) Len

func (b *Buffer[T]) Len() int

Len returns the current number of buffered entries.

func (*Buffer[T]) PopBatch

func (b *Buffer[T]) PopBatch(maxItems, maxBytes int) []T

PopBatch removes and returns up to maxItems oldest entries, stopping early if adding the next entry would exceed maxBytes (at least one entry is always returned when the buffer is non-empty). Non-positive limits are ignored.

func (*Buffer[T]) Push

func (b *Buffer[T]) Push(item T) (dropped int)

Push appends item, evicting the oldest entries until the buffer is within both bounds. It always accepts item (the caller never blocks) and returns the number of entries evicted to make room.

type Sizer

type Sizer[T any] func(T) int

Sizer estimates the byte cost of a single item for the byte budget. The returned value is clamped to a minimum of one.