ringslice

README

Ringslice

Ringslice is a type-safe generic ring buffer backed by a Go slice, featuring iter.Seq iteration and zero-allocation performance. It includes lifecycle callbacks designed for production use cases.

For a traditional circular doubly-linked list, see Go's standard container/ring package.

Basic Usage

const maxRingCapacity = 128

ring := ringslice.New[string](maxRingCapacity)

ring.Add("generic")
ring.Add("ring")
ring.Add("buffer")

// prints: "generic", "ring", "buffer"
for v := range ring.All() {
    fmt.Println(v)
}

// prints: "buffer", "ring", "generic"
for v := range ring.AllDesc() {
    fmt.Println(v)
}

Hooks

Ringslice provides callback hooks that let you react to internal lifecycle events.

OnBeforeAdd

Called before the value is added to the ring. The value will be rejected if false is returned. This is particularly useful if you want to exclude values with certain characteristics.

// reject empty strings
ring.OnBeforeAdd(func(value string) bool {
    return len(value) > 0
})

OnRotate

Called each time the write index wraps around the ring. Useful for logging, flushing, or instrumentation.

ring.OnRotate(func(values []string) {
    fmt.Println("lap complete 🏁")
})

OnFlush

Called by Flush() before the buffer is cleared. Useful for draining the buffer, persisting elements, or instrumentation.

ring.OnFlush(func(values []string) {
    for _, v := range values {
        db.Insert(v)
    }
})

Note: Clear() discards all elements without invoking this callback.

Concurrency Model

Ringslice uses a read-write lock to allow multiple concurrent readers while serializing writers. This ensures thread-safety while maintaining high throughput for read-heavy workloads.

Documentation

Overview

Package ringslice provides a generic ring buffer backed by a Go slice, with iter.Seq iteration and callback hooks for production use cases.

Index

• type Ring
  • func New[T any](capacity int) *Ring[T]
  • func (r *Ring[T]) Add(val T)
  • func (r *Ring[T]) All() iter.Seq[T]
  • func (r *Ring[T]) AllDesc() iter.Seq[T]
  • func (r *Ring[T]) Cap() int
  • func (r *Ring[T]) Clear()
  • func (r *Ring[T]) Flush()
  • func (r *Ring[T]) Len() int
  • func (r *Ring[T]) OnBeforeAdd(fn func(T) bool)
  • func (r *Ring[T]) OnFlush(fn func([]T))
  • func (r *Ring[T]) OnRotate(fn func([]T))

Types

type Ring

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

Ring is a fixed-size ring buffer backed by a Go slice. When the buffer is full, new values overwrite the oldest.

func New

func New[T any](capacity int) *Ring[T]

New returns a new Ring with the given capacity.

func (*Ring[T]) Add

func (r *Ring[T]) Add(val T)

Add writes the given value to the ring.

func (*Ring[T]) All

func (r *Ring[T]) All() iter.Seq[T]

All returns an iterator that yields each element in chronological order.

func (*Ring[T]) AllDesc

func (r *Ring[T]) AllDesc() iter.Seq[T]

AllDesc returns an iterator that yields each element in reverse chronological order.

func (*Ring[T]) Cap

func (r *Ring[T]) Cap() int

Cap returns the capacity of the ring.

func (*Ring[T]) Clear

func (r *Ring[T]) Clear()

Clear resets the ring buffer, discarding all elements.

func (*Ring[T]) Flush

func (r *Ring[T]) Flush()

Flush resets the ring buffer, discarding all elements. If an OnFlush callback is registered, it is invoked before the buffer is cleared.

func (*Ring[T]) Len

func (r *Ring[T]) Len() int

Len returns the number of elements in the ring.

func (*Ring[T]) OnBeforeAdd

func (r *Ring[T]) OnBeforeAdd(fn func(T) bool)

OnBeforeAdd registers a callback invoked before a value is added. Returning false from fn prevents the value from being written. fn must not call any methods on the same Ring instance.

func (*Ring[T]) OnFlush

func (r *Ring[T]) OnFlush(fn func([]T))

OnFlush registers a callback invoked by Flush() before the buffer is cleared. fn receives the underlying slice of the ring buffer, thus it must not mutate or retain the slice beyond the duration of the call. fn must not call any methods on the same Ring instance.

func (*Ring[T]) OnRotate

func (r *Ring[T]) OnRotate(fn func([]T))

OnRotate registers a callback invoked when the write index wraps back to zero. fn receives the underlying slice of the ring buffer, thus it must not mutate or retain the slice beyond the duration of the call. fn must not call any methods on the same Ring instance.