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 ¶
- type Buffer
- type DropCallback
- type Option
- type OverflowPolicy
- type Statistics
- func (s *Statistics) CurrentSize() int64
- func (s *Statistics) Drop()
- func (s *Statistics) DropRate() float64
- func (s *Statistics) Drops() int64
- func (s *Statistics) MaxSize() int64
- func (s *Statistics) Overflow()
- func (s *Statistics) OverflowRate() float64
- func (s *Statistics) Overflows() int64
- func (s *Statistics) Peek()
- func (s *Statistics) Peeks() int64
- func (s *Statistics) Read()
- func (s *Statistics) ReadThroughput() float64
- func (s *Statistics) Reads() int64
- func (s *Statistics) Reset()
- func (s *Statistics) Summary() StatsSummary
- func (s *Statistics) Throughput() float64
- func (s *Statistics) UpdateSize(size int64)
- func (s *Statistics) Uptime() time.Duration
- func (s *Statistics) Utilization(capacity int64) float64
- func (s *Statistics) Write()
- func (s *Statistics) Writes() int64
- type StatsSummary
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 ¶
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) Peeks ¶
func (s *Statistics) Peeks() int64
Peeks returns the total number of peek operations.
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) 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) 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.