buffer

package
v0.1.0-alpha.5 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 8 Imported by: 0

README

Buffer

A fixed-size, thread-safe, generic buffer. You choose what a write does when the buffer is full: drop the oldest item, drop the new item, or wait for space. Counters for writes, reads and drops are always kept, and can also be published as Prometheus metrics.

import "github.com/c360studio/semengine/pkg/buffer"

Quick start

NewCircularBuffer takes a capacity and options, and returns the buffer and an error. The error is non-nil only when metrics registration fails; the buffer is then a true nil. A capacity below 1 becomes 1.

buf, err := buffer.NewCircularBuffer[int](1000)
if err != nil {
    return err
}
defer buf.Close()

if err := buf.Write(42); err != nil {
    return err
}

item, ok := buf.Read() // ok is false when the buffer is empty
batch := buf.ReadBatch(10)

Write returns an error only after Close: an errs.ErrorInvalid error wrapping errs.ErrAlreadyStopped.

Overflow policies

Pick one with WithOverflowPolicy. The default is DropOldest.

Policy A write to a full buffer Use it when
DropOldest removes the oldest item, stores the new one the newest data matters most, such as telemetry
DropNewest discards the new item and returns nil the items already queued must stay, such as an audit log
Block waits until a read frees space or the buffer closes no item may be lost
buf, err := buffer.NewCircularBuffer[string](100,
    buffer.WithOverflowPolicy[string](buffer.Block),
)

Each item a drop policy discards counts as one overflow and one drop in the statistics. Clear empties the buffer without counting drops, but it does call the drop callback for each item it removes.

Bounding a blocked write

Under Block, Write waits with no limit. WriteWithTimeout and WriteWithContext are methods of Buffer[T], so you call them on the value NewCircularBuffer returns. If the buffer is still full when the timeout passes or the context ends, they write nothing and return context.DeadlineExceeded or ctx.Err(). Under the other two policies they behave as Write.

err := buf.WriteWithTimeout(item, 5*time.Second)

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err = buf.WriteWithContext(ctx, item)

Two edges:

  • A timeout of zero or less, and a context that has already ended, refuse under Block even when there is space. Keep the timeout positive.
  • WriteWithContext refuses a nil context with an errs.ErrorInvalid error under every policy.

A runnable version is ExampleNewCircularBuffer_writeWithTimeout in example_test.go.

Options

Option Effect
WithOverflowPolicy[T](policy) what a write to a full buffer does; default DropOldest
WithMetrics[T](registry, prefix) also publish the counters on a *metric.MetricsRegistry; a nil registry or empty prefix records no metrics
WithDropCallback[T](fn) call fn with each dropped item

The drop callback runs on the goroutine that dropped the item, after the buffer's lock is released, so it may call any buffer method.

Metrics
import "github.com/c360studio/semengine/metric"

registry := metric.NewMetricsRegistry()

buf, err := buffer.NewCircularBuffer[[]byte](5000,
    buffer.WithOverflowPolicy[[]byte](buffer.DropOldest),
    buffer.WithMetrics[[]byte](registry, "network_buffer"),
)
Metric Type Counts
semengine_buffer_writes_total counter items written
semengine_buffer_reads_total counter items read
semengine_buffer_peeks_total counter peeks
semengine_buffer_overflows_total counter writes that found the buffer full under a drop policy
semengine_buffer_drops_total counter items dropped
semengine_buffer_size gauge items in the buffer now
semengine_buffer_utilization gauge size divided by capacity, 0 to 1

Every series carries the label component=<prefix>. Two buffers given the same prefix share one set of series, so give each buffer its own prefix.

Buffer interface

type Buffer[T any] interface {
    Write(item T) error
    Read() (T, bool)
    ReadBatch(maxN int) []T
    Peek() (T, bool)
    Size() int
    Capacity() int
    IsFull() bool
    IsEmpty() bool
    Clear()
    Stats() *Statistics // never nil
    Close() error
    WriteWithTimeout(item T, timeout time.Duration) error
    WriteWithContext(ctx context.Context, item T) error
}

A type that implements Buffer[T] without embedding it must have both bounded-write methods. A wrapper that embeds Buffer[T] gets them from the embedded value.

Statistics

buf.Stats() returns counters that are always on, whether or not metrics are enabled:

stats := buf.Stats()

stats.Writes()         // items accepted; a write DropNewest rejects is not one
stats.Reads()          // total reads
stats.Peeks()          // total peeks
stats.Drops()          // total items dropped
stats.Overflows()      // total overflow events
stats.CurrentSize()    // items now
stats.MaxSize()        // highest size seen
stats.Throughput()     // writes per second since start
stats.ReadThroughput() // reads per second since start
stats.DropRate()       // drops divided by accepted writes, no upper bound
stats.OverflowRate()   // overflows divided by accepted writes, no upper bound
stats.Utilization(cap) // size divided by cap
stats.Summary()        // all of the above as a StatsSummary, for JSON

Thread safety

Any number of goroutines may write and read at once. Under Block, Close wakes every waiting writer, and each returns an errs.ErrorInvalid error wrapping errs.ErrAlreadyStopped.

Moving from SemStreams

See MIGRATION.md.

Documentation

Overview

Package buffer provides generic, thread-safe buffer implementations with various overflow policies.

This package offers flexible buffer types:

  • CircularBuffer: Fixed-size buffer with configurable overflow policies
  • Support for DropOldest, DropNewest, and Block overflow policies
  • Statistics always enabled for observability
  • Optional Prometheus metrics integration via functional options

All buffer implementations are thread-safe and always collect statistics for observability. Prometheus metrics can be optionally enabled via WithMetrics() functional option.

Package buffer provides a generic, thread-safe, fixed-size buffer with a choice of what happens when it is full.

Import it as github.com/c360studio/semengine/pkg/buffer. NewCircularBuffer builds a Buffer[T] from a capacity and options:

  • WithOverflowPolicy picks DropOldest (the default), DropNewest or Block when the buffer is full.
  • WithMetrics also publishes the counters on a metric.MetricsRegistry as semengine_buffer_* series.
  • WithDropCallback is told about every item the buffer drops.

Under Block, Write waits without limit for space. WriteWithTimeout and WriteWithContext, both methods of Buffer[T], bound that wait. Statistics are always collected: Buffer.Stats never returns nil.

All buffer implementations are safe for concurrent use.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Buffer

type Buffer[T any] interface {
	// Write adds an item to the buffer. Returns an error if the operation fails.
	// Behavior depends on the overflow policy when buffer is full.
	Write(item T) error

	// Read retrieves and removes one item from the buffer.
	// Returns the item and true if successful, zero value and false if buffer is empty.
	Read() (T, bool)

	// ReadBatch retrieves and removes up to maxN items from the buffer.
	// Returns a slice containing the retrieved items (may be shorter than maxN).
	ReadBatch(maxN int) []T

	// Peek retrieves one item without removing it from the buffer.
	// Returns the item and true if successful, zero value and false if buffer is empty.
	Peek() (T, bool)

	// Size returns the current number of items in the buffer.
	Size() int

	// Capacity returns the maximum number of items the buffer can hold.
	Capacity() int

	// IsFull returns true if the buffer is at maximum capacity.
	IsFull() bool

	// IsEmpty returns true if the buffer contains no items.
	IsEmpty() bool

	// Clear removes all items from the buffer.
	Clear()

	// Stats returns buffer statistics (always available for observability).
	Stats() *Statistics

	// Close shuts down the buffer and releases any resources.
	Close() error

	// WriteWithTimeout writes item, waiting at most timeout for space under the Block policy.
	// Once timeout has passed with the buffer still full it returns context.DeadlineExceeded
	// and writes nothing; a timeout of zero or less refuses at once, even when there is space.
	// Under the other policies it behaves as Write.
	WriteWithTimeout(item T, timeout time.Duration) error

	// WriteWithContext writes item, waiting for space under the Block policy until ctx ends,
	// when it returns ctx.Err() and writes nothing; an already-ended ctx refuses at once, even
	// when there is space. Under the other policies it behaves as Write. A nil ctx is refused
	// with an ErrorInvalid error under every policy.
	WriteWithContext(ctx context.Context, item T) error
}

Buffer represents a generic buffer interface that all buffer implementations must satisfy. The buffer is parameterized by item type T for type safety.

func NewCircularBuffer

func NewCircularBuffer[T any](capacity int, options ...Option[T]) (Buffer[T], error)

NewCircularBuffer creates a new circular buffer with the specified capacity and options. Stats are ALWAYS collected for observability. Metrics are optional via WithMetrics(). Returns an error if metrics registration fails when metrics are requested. Capacity is required - all other configuration is via functional options. A capacity below 1 becomes 1. On error the returned Buffer is nil.

Example (WriteWithTimeout)

A write under the Block policy waits for space. WriteWithTimeout limits that wait and, when the buffer stays full, returns context.DeadlineExceeded without writing the item.

package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/c360studio/semengine/pkg/buffer"
)

func main() {
	buf, err := buffer.NewCircularBuffer(1, buffer.WithOverflowPolicy[string](buffer.Block))
	if err != nil {
		fmt.Println("create:", err)
		return
	}
	defer buf.Close()

	if err := buf.Write("first"); err != nil {
		fmt.Println("write:", err)
		return
	}

	// The buffer holds one item and nothing reads it, so this write times out.
	err = buf.WriteWithTimeout("second", 10*time.Millisecond)
	fmt.Println(errors.Is(err, context.DeadlineExceeded), buf.Size())

}
Output:
true 1

type DropCallback

type DropCallback[T any] func(item T)

DropCallback is called when an item is dropped due to overflow policy or Clear. It receives the item that was dropped. It runs on the goroutine that dropped the item, after the buffer's lock is released, so it may call any buffer method.

type Option

type Option[T any] func(*bufferOptions[T])

Option configures buffer behavior using the functional options pattern. This provides a clean, extensible API for configuring buffers.

func WithDropCallback

func WithDropCallback[T any](callback DropCallback[T]) Option[T]

WithDropCallback sets a callback function that is called when items are dropped. The callback receives the item that was dropped. It runs after the buffer's lock is released, on the goroutine that dropped the item, so it may call any buffer method.

func WithMetrics

func WithMetrics[T any](registry *metric.MetricsRegistry, prefix string) Option[T]

WithMetrics enables Prometheus metrics export for buffer statistics. A nil registry or an empty prefix records no metrics: the option is then ignored, and statistics are still collected.

func WithOverflowPolicy

func WithOverflowPolicy[T any](policy OverflowPolicy) Option[T]

WithOverflowPolicy sets the overflow behavior for the buffer. Defaults to DropOldest if not specified.

type OverflowPolicy

type OverflowPolicy int

OverflowPolicy defines how the buffer behaves when it reaches capacity.

const (
	// DropOldest removes the oldest item to make room for new items.
	DropOldest OverflowPolicy = iota

	// DropNewest drops new items when the buffer is full.
	DropNewest

	// Block causes Write operations to block until space is available.
	Block
)

func (OverflowPolicy) String

func (p OverflowPolicy) String() string

String returns a human-readable representation of the overflow policy.

type Statistics

type Statistics struct {
	// contains filtered or unexported fields
}

Statistics tracks buffer performance metrics.

func NewStatistics

func NewStatistics() *Statistics

NewStatistics creates a new statistics tracker.

func (*Statistics) CurrentSize

func (s *Statistics) CurrentSize() int64

CurrentSize returns the current number of items in the buffer.

func (*Statistics) Drop

func (s *Statistics) Drop()

Drop records an item drop due to overflow policy.

func (*Statistics) DropRate

func (s *Statistics) DropRate() float64

DropRate returns Drops divided by Writes, or 0 before the first accepted write. It is a ratio to accepted writes with no upper bound: under DropNewest a rejected write adds a drop but no write, so a full buffer of capacity 1 given four writes reports 3.

func (*Statistics) Drops

func (s *Statistics) Drops() int64

Drops returns the total number of dropped items.

func (*Statistics) MaxSize

func (s *Statistics) MaxSize() int64

MaxSize returns the maximum number of items the buffer has held.

func (*Statistics) Overflow

func (s *Statistics) Overflow()

Overflow records a buffer overflow event.

func (*Statistics) OverflowRate

func (s *Statistics) OverflowRate() float64

OverflowRate returns Overflows divided by Writes, or 0 before the first accepted write. Like DropRate it is a ratio to accepted writes with no upper bound, and exceeds 1 under DropNewest.

func (*Statistics) Overflows

func (s *Statistics) Overflows() int64

Overflows returns the total number of overflow events.

func (*Statistics) Peek

func (s *Statistics) Peek()

Peek records a buffer peek operation.

func (*Statistics) Peeks

func (s *Statistics) Peeks() int64

Peeks returns the total number of peek operations.

func (*Statistics) Read

func (s *Statistics) Read()

Read records a buffer read operation.

func (*Statistics) ReadThroughput

func (s *Statistics) ReadThroughput() float64

ReadThroughput returns the average number of reads per second.

func (*Statistics) Reads

func (s *Statistics) Reads() int64

Reads returns the total number of read operations.

func (*Statistics) Reset

func (s *Statistics) Reset()

Reset resets all statistics to zero.

func (*Statistics) Summary

func (s *Statistics) Summary() StatsSummary

Summary returns a snapshot of all statistics.

func (*Statistics) Throughput

func (s *Statistics) Throughput() float64

Throughput returns the average number of writes per second.

func (*Statistics) UpdateSize

func (s *Statistics) UpdateSize(size int64)

UpdateSize updates the current buffer size.

func (*Statistics) Uptime

func (s *Statistics) Uptime() time.Duration

Uptime returns how long the buffer has been running.

func (*Statistics) Utilization

func (s *Statistics) Utilization(capacity int64) float64

Utilization returns the current buffer utilization as a percentage (0.0 to 1.0).

func (*Statistics) Write

func (s *Statistics) Write()

Write records a buffer write operation.

func (*Statistics) Writes

func (s *Statistics) Writes() int64

Writes returns the number of items the buffer accepted. A write DropNewest rejects is not counted; a write that evicts the oldest item under DropOldest is.

type StatsSummary

type StatsSummary struct {
	Writes         int64         `json:"writes"`
	Reads          int64         `json:"reads"`
	Peeks          int64         `json:"peeks"`
	Overflows      int64         `json:"overflows"`
	Drops          int64         `json:"drops"`
	CurrentSize    int64         `json:"current_size"`
	MaxSize        int64         `json:"max_size"`
	Throughput     float64       `json:"throughput"`
	ReadThroughput float64       `json:"read_throughput"`
	DropRate       float64       `json:"drop_rate"`
	OverflowRate   float64       `json:"overflow_rate"`
	Uptime         time.Duration `json:"uptime"`
}

StatsSummary returns a snapshot of all statistics.

Jump to

Keyboard shortcuts

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