The highest tagged major version is
Documentation
¶
Index ¶
- func NewPoolConfigBuilder() *poolConfigBuilder
- type AggressivenessLevel
- type Pool
- func (p *Pool[T]) Close() error
- func (p *Pool[T]) Get() (zero T, err error)
- func (p *Pool[T]) GetBlockedReaders() int
- func (p *Pool[T]) GetPoolStatsSnapshot() *PoolStatsSnapshot
- func (p *Pool[T]) IdleCheck(idles *int, shrinkPermissionIdleness *bool)
- func (p *Pool[T]) IsGrowth() bool
- func (p *Pool[T]) IsShrunk() bool
- func (p *Pool[T]) PrintPoolStats()
- func (p *Pool[T]) Put(obj T) error
- func (p *Pool[T]) RingBufferCapacity() int
- func (p *Pool[T]) RingBufferLength() int
- func (p *Pool[T]) SlowPath() (obj T, err error)
- type PoolConfig
- func (c *PoolConfig) GetFastPath() *fastPathParameters
- func (c *PoolConfig) GetGrowth() *growthParameters
- func (c *PoolConfig) GetHardLimit() int
- func (c *PoolConfig) GetInitialCapacity() int
- func (c *PoolConfig) GetRingBufferConfig() *ringBufferConfig
- func (c *PoolConfig) GetShrink() *shrinkParameters
- func (c *PoolConfig) IsVerbose() bool
- type PoolStatsSnapshot
- type RingBuffer
- func (r *RingBuffer[T]) Capacity() int
- func (r *RingBuffer[T]) ClearBuffer()
- func (r *RingBuffer[T]) Close() error
- func (r *RingBuffer[T]) CopyConfig(source *RingBuffer[T]) *RingBuffer[T]
- func (r *RingBuffer[T]) Free() int
- func (r *RingBuffer[T]) GetBlockedReaders() int
- func (r *RingBuffer[T]) GetBlockedWriters() int
- func (r *RingBuffer[T]) GetN(n int) (items []T, err error)
- func (r *RingBuffer[T]) GetNView(n int) (part1, part2 []T, err error)
- func (r *RingBuffer[T]) GetOne() (item T, err error)
- func (r *RingBuffer[T]) IsEmpty() bool
- func (r *RingBuffer[T]) IsFull() bool
- func (r *RingBuffer[T]) Length() int
- func (r *RingBuffer[T]) PeekN(n int) (items []T, err error)
- func (r *RingBuffer[T]) PeekOne() (item T, err error)
- func (r *RingBuffer[T]) WithBlocking(block bool) *RingBuffer[T]
- func (r *RingBuffer[T]) WithPreReadBlockHook(hook func() bool) *RingBuffer[T]
- func (r *RingBuffer[T]) WithReadTimeout(d time.Duration) *RingBuffer[T]
- func (r *RingBuffer[T]) WithTimeout(d time.Duration) *RingBuffer[T]
- func (r *RingBuffer[T]) WithWriteTimeout(d time.Duration) *RingBuffer[T]
- func (r *RingBuffer[T]) Write(item T) error
- func (r *RingBuffer[T]) WriteMany(items []T) (n int, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewPoolConfigBuilder ¶
func NewPoolConfigBuilder() *poolConfigBuilder
NewPoolConfigBuilder creates a new pool configuration builder with default settings. It initializes all configuration parameters with safe default values and sets up the necessary parameter relationships. Returns a builder ready for customization.
Types ¶
type AggressivenessLevel ¶
type AggressivenessLevel int
const ( AggressivenessDisabled AggressivenessLevel = 0 AggressivenessConservative AggressivenessLevel = 1 AggressivenessBalanced AggressivenessLevel = 2 AggressivenessAggressive AggressivenessLevel = 3 AggressivenessVeryAggressive AggressivenessLevel = 4 AggressivenessExtreme AggressivenessLevel = 5 )
type Pool ¶
type Pool[T any] struct { // contains filtered or unexported fields }
Pool is a generic object pool implementation that provides efficient object reuse. It uses a two-level caching strategy with a fast path (L1 cache) and a main pool. The pool is designed to be thread-safe and supports dynamic resizing based on usage patterns.
Key features: - Two-level caching (L1 cache + main pool) for optimal performance - Dynamic resizing based on usage patterns - Thread-safe operations - Configurable growth and shrink behavior - Optional object cleanup - Detailed statistics tracking
Type parameter T must be a pointer type. Non-pointer types will cause an error.
func NewPool ¶
func NewPool[T any](config *PoolConfig, allocator func() T, cleaner func(T)) (*Pool[T], error)
NewPool creates a new object pool with the given configuration, allocator, cleaner, and pool type. Only pointers can be stored in the pool. The allocator function creates new objects, and the cleaner function resets objects before they are reused.
func (*Pool[T]) Close ¶
Close closes the pool and releases all resources. If there are outstanding objects, it will wait for them to be returned before closing.
func (*Pool[T]) Get ¶
Get returns an object from the pool, either from L1 cache or the ring buffer, preferring L1.
func (*Pool[T]) GetBlockedReaders ¶
GetBlockedReaders returns the number of readers currently blocked waiting for objects
func (*Pool[T]) GetPoolStatsSnapshot ¶
func (p *Pool[T]) GetPoolStatsSnapshot() *PoolStatsSnapshot
GetPoolStatsSnapshot returns a snapshot of the current pool statistics
func (*Pool[T]) IdleCheck ¶
IdleCheck determines if the pool has been idle long enough to consider shrinking. It updates the idle count and shrink permission based on the configured thresholds.
func (*Pool[T]) PrintPoolStats ¶
func (p *Pool[T]) PrintPoolStats()
PrintPoolStats prints the current statistics of the pool to stdout. This includes information about pool capacity, object usage, hit rates, and performance metrics.
func (*Pool[T]) Put ¶
Put returns an object to the pool. The object will be cleaned using the cleaner function before being made available for reuse.
func (*Pool[T]) RingBufferCapacity ¶
func (*Pool[T]) RingBufferLength ¶
type PoolConfig ¶
type PoolConfig struct {
// contains filtered or unexported fields
}
PoolConfig defines the configuration parameters for the pool. It controls various aspects of pool behavior including growth, shrinking, and performance characteristics.
func (*PoolConfig) GetFastPath ¶
func (c *PoolConfig) GetFastPath() *fastPathParameters
func (*PoolConfig) GetGrowth ¶
func (c *PoolConfig) GetGrowth() *growthParameters
func (*PoolConfig) GetHardLimit ¶
func (c *PoolConfig) GetHardLimit() int
func (*PoolConfig) GetInitialCapacity ¶
func (c *PoolConfig) GetInitialCapacity() int
Getter methods for PoolConfig
func (*PoolConfig) GetRingBufferConfig ¶
func (c *PoolConfig) GetRingBufferConfig() *ringBufferConfig
func (*PoolConfig) GetShrink ¶
func (c *PoolConfig) GetShrink() *shrinkParameters
func (*PoolConfig) IsVerbose ¶
func (c *PoolConfig) IsVerbose() bool
type PoolStatsSnapshot ¶
type PoolStatsSnapshot struct {
// Basic Pool Stats
ObjectsInUse uint64
AvailableObjects uint64
CurrentCapacity uint64
RingBufferLength uint64
PeakInUse uint64
TotalGets uint64
TotalGrowthEvents uint64
TotalShrinkEvents uint64
ConsecutiveShrinks int32
// Fast Path Resize Stats
LastResizeAtGrowthNum uint64
CurrentL1Capacity uint64
L1Length uint64
// Fast Get Stats
L1HitCount uint64
L2HitCount uint64
L3MissCount uint64
// Fast Return Stats
FastReturnHit uint64
FastReturnMiss uint64
L2SpillRate float64
// Usage Stats
RequestPerObject float64
Utilization float64
// Time Stats
LastGetTime time.Time
LastShrinkTime time.Time
LastGrowTime time.Time
}
PoolStatsSnapshot represents a snapshot of the pool's statistics at a given moment
func (*PoolStatsSnapshot) Validate ¶
func (s *PoolStatsSnapshot) Validate(reqNum int) error
type RingBuffer ¶
type RingBuffer[T any] struct { // contains filtered or unexported fields }
RingBuffer is a circular buffer that implements io.ReaderWriter interface. It operates like a buffered pipe, where data is written to a RingBuffer and can be read back from another goroutine. It is safe to concurrently read and write RingBuffer.
Key features: - Thread-safe concurrent read/write operations - Configurable blocking/non-blocking behavior - Timeout support for read/write operations - Pre-read hook for custom blocking behavior - Efficient circular buffer implementation
func NewRingBuffer ¶
func NewRingBuffer[T any](size int) *RingBuffer[T]
New returns a new RingBuffer whose buffer has the given size.
func NewRingBufferWithConfig ¶
func NewRingBufferWithConfig[T any](size int, config *ringBufferConfig) (*RingBuffer[T], error)
NewWithConfig creates a new RingBuffer with the given size and configuration. It returns an error if the size is less than or equal to 0.
func (*RingBuffer[T]) Capacity ¶
func (r *RingBuffer[T]) Capacity() int
Capacity returns the size of the underlying buffer
func (*RingBuffer[T]) ClearBuffer ¶
func (r *RingBuffer[T]) ClearBuffer()
ClearBuffer clears all items in the buffer and resets read/write positions. Useful when shrinking the buffer or cleaning up resources.
func (*RingBuffer[T]) Close ¶
func (r *RingBuffer[T]) Close() error
Close closes the ring buffer and cleans up resources. Behavior: - Sets error to io.EOF - Clears all items in the buffer - Signals all waiting readers and writers - All subsequent operations will return io.EOF
func (*RingBuffer[T]) CopyConfig ¶
func (r *RingBuffer[T]) CopyConfig(source *RingBuffer[T]) *RingBuffer[T]
CopyConfig copies the configuration settings from the source buffer to the target buffer. This includes blocking mode, timeouts, and cancellation context.
func (*RingBuffer[T]) Free ¶
func (r *RingBuffer[T]) Free() int
Free returns the number of items that can be written without blocking. This is the available space in the buffer.
func (*RingBuffer[T]) GetBlockedReaders ¶
func (r *RingBuffer[T]) GetBlockedReaders() int
func (*RingBuffer[T]) GetBlockedWriters ¶
func (r *RingBuffer[T]) GetBlockedWriters() int
func (*RingBuffer[T]) GetN ¶
func (r *RingBuffer[T]) GetN(n int) (items []T, err error)
GetN returns up to n items from the buffer. Behavior: - Returns between 0 and n items - Blocks if buffer is empty and in blocking mode - Returns ErrIsEmpty if buffer is empty and not blocking - Handles wrapping around the buffer end
func (*RingBuffer[T]) GetNView ¶
func (r *RingBuffer[T]) GetNView(n int) (part1, part2 []T, err error)
func (*RingBuffer[T]) GetOne ¶
func (r *RingBuffer[T]) GetOne() (item T, err error)
GetOne returns a single item from the buffer. Behavior: - Blocks if buffer is empty and in blocking mode - Returns ErrIsEmpty if buffer is empty and not blocking - Returns context.DeadlineExceeded if timeout occurs - Signals waiting writers when data is read
func (*RingBuffer[T]) IsEmpty ¶
func (r *RingBuffer[T]) IsEmpty() bool
IsEmpty returns true when the ringbuffer is empty.
func (*RingBuffer[T]) IsFull ¶
func (r *RingBuffer[T]) IsFull() bool
IsFull returns true when the ringbuffer is full.
func (*RingBuffer[T]) Length ¶
func (r *RingBuffer[T]) Length() int
Length returns the number of items that can be read. This is the actual number of items in the buffer.
func (*RingBuffer[T]) PeekN ¶
func (r *RingBuffer[T]) PeekN(n int) (items []T, err error)
PeekN returns up to n items without removing them from the buffer
func (*RingBuffer[T]) PeekOne ¶
func (r *RingBuffer[T]) PeekOne() (item T, err error)
PeekOne returns the next item without removing it from the buffer
func (*RingBuffer[T]) WithBlocking ¶
func (r *RingBuffer[T]) WithBlocking(block bool) *RingBuffer[T]
WithBlocking sets the blocking mode of the ring buffer. When blocking is enabled: - Read operations will block when the buffer is empty - Write operations will block when the buffer is full - Condition variables are created for synchronization
func (*RingBuffer[T]) WithPreReadBlockHook ¶
func (r *RingBuffer[T]) WithPreReadBlockHook(hook func() bool) *RingBuffer[T]
WithPreReadBlockHook sets a hook function that will be called before blocking on a read or hitting a deadline. This allows for custom handling of blocking situations, such as trying alternative sources for data.
func (*RingBuffer[T]) WithReadTimeout ¶
func (r *RingBuffer[T]) WithReadTimeout(d time.Duration) *RingBuffer[T]
WithReadTimeout sets the timeout for read operations. Read operations wait for writes to complete, so this sets the write timeout.
func (*RingBuffer[T]) WithTimeout ¶
func (r *RingBuffer[T]) WithTimeout(d time.Duration) *RingBuffer[T]
WithTimeout sets both read and write timeouts for the ring buffer. When a timeout occurs, the operation returns context.DeadlineExceeded. A timeout of 0 or less disables timeouts.
func (*RingBuffer[T]) WithWriteTimeout ¶
func (r *RingBuffer[T]) WithWriteTimeout(d time.Duration) *RingBuffer[T]
WithWriteTimeout sets the timeout for write operations. Write operations wait for reads to complete, so this sets the read timeout.
func (*RingBuffer[T]) Write ¶
func (r *RingBuffer[T]) Write(item T) error
Write writes a single item to the buffer. Behavior: - Blocks if buffer is full and in blocking mode - Returns ErrIsFull if buffer is full and not blocking - Returns context.DeadlineExceeded if timeout occurs - Signals waiting readers when data is written
func (*RingBuffer[T]) WriteMany ¶
func (r *RingBuffer[T]) WriteMany(items []T) (n int, err error)
WriteMany writes multiple items to the buffer. Behavior: - Writes as many items as possible without blocking - Blocks if more space is needed and in blocking mode - Returns number of items written and any error - Handles wrapping around the buffer end
Source Files