pool

package
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2025 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// if any of the three happens, we likely can't get from L1.
	GrowthFailed    = "growth failed"
	RingBufferError = "error getting items from ring buffer"

	// if any of the three happens, we can try to get from L1.
	GrowthBlocked   = "growth is blocked"
	RefillSucceeded = "refill succeeded"
	NoRefillNeeded  = "no refill needed"
	NoItemsToMove   = "no items to move"
)

Variables

View Source 
var (
	// ErrTooMuchDataToWrite is returned when the data to write is more than the buffer size.
	ErrTooMuchDataToWrite = errors.New("too much data to write")

	// ErrIsFull is returned when the buffer is full and not blocking.
	ErrIsFull = errors.New("ringbuffer is full")

	// ErrIsEmpty is returned when the buffer is empty and not blocking.
	ErrIsEmpty = errors.New("ringbuffer is empty")

	// ErrIsNotEmpty is returned when the buffer is not empty and not blocking.
	ErrIsNotEmpty = errors.New("ringbuffer is not empty")

	// ErrAcquireLock is returned when the lock is not acquired on Try operations.
	ErrAcquireLock = errors.New("unable to acquire lock")

	// ErrWriteOnClosed is returned when write on a closed ringbuffer.
	ErrWriteOnClosed = errors.New("write on closed ringbuffer")

	// ErrReaderClosed is returned when a ReadClosed closed the ringbuffer.
	ErrReaderClosed = errors.New("reader closed")

	// ErrInvalidLength is returned when the length of the buffer is invalid.
	ErrInvalidLength = errors.New("invalid length")

	// ErrNilValue is returned when a nil value is written to the ring buffer.
	ErrNilValue = errors.New("cannot write nil value to ring buffer")
)

Functions

func NewPoolConfigBuilder 

func NewPoolConfigBuilder() *poolConfigBuilder

func ToInternalConfig 

func ToInternalConfig(config PoolConfig) *poolConfig

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 Example 

type Example struct {
	Name string
	Age  int
}

type FastPathParameters 

type FastPathParameters interface {
	GetBufferSize() int
	GetGrowthEventsTrigger() int
	GetShrinkEventsTrigger() int
	GetFillAggressiveness() float64
	GetRefillPercent() float64
	GetGrowth() *growthParameters
	GetShrink() *shrinkParameters
	IsEnableChannelGrowth() bool
}

type GrowthParameters 

type GrowthParameters interface {
	GetExponentialThresholdFactor() float64
	GetGrowthPercent() float64
	GetFixedGrowthFactor() float64
}

type Pool 

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

Only pointers can be stored in the pool, anything else will cause an error. (no panic will be thrown)

func NewPool 

func NewPool[T any](config *poolConfig, allocator func() T, cleaner func(T), poolType reflect.Type) (*Pool[T], error)

func (*Pool[T]) Close 

func (p *Pool[T]) Close() error

func (*Pool[T]) Get 

func (p *Pool[T]) Get() (zero T)

func (*Pool[T]) IdleCheck 

func (p *Pool[T]) IdleCheck(idles *int, shrinkPermissionIdleness *bool)

func (*Pool[T]) IsGrowth 

func (p *Pool[T]) IsGrowth() bool

isGrowth, return true if the pool has grown.

func (*Pool[T]) IsShrunk 

func (p *Pool[T]) IsShrunk() bool

isShrunk returns true if the pool is shrunk.

func (*Pool[T]) PrintPoolStats 

func (p *Pool[T]) PrintPoolStats()

func (*Pool[T]) Put 

func (p *Pool[T]) Put(obj T)

func (*Pool[T]) ShrinkExecution 

func (p *Pool[T]) ShrinkExecution()

func (*Pool[T]) UtilizationCheck 

func (p *Pool[T]) UtilizationCheck(underutilizationRounds *int, shrinkPermissionUtilization *bool)

type PoolConfig 

type PoolConfig interface {
	GetInitialCapacity() int
	GetHardLimit() int
	GetGrowth() *growthParameters
	GetShrink() *shrinkParameters
	GetFastPath() *fastPathParameters
	GetRingBufferConfig() *RingBufferConfig
	IsVerbose() bool
}

type RefillResult 

type RefillResult struct {
	Success       bool
	Reason        string
	ItemsMoved    int
	ItemsFailed   int
	GrowthNeeded  bool
	GrowthBlocked bool
}

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.

func New 

func New[T any](size int) *RingBuffer[T]

New returns a new RingBuffer whose buffer has the given size.

func NewWithConfig 

func NewWithConfig[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]) Close 

func (r *RingBuffer[T]) Close() error

Close closes the ring buffer and cleans up resources. After closing, all subsequent operations will return io.EOF. Any pending items in the buffer will be cleared.

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.

func (*RingBuffer[T]) GetAll 

func (r *RingBuffer[T]) GetAll() (items []T, err error)

GetAll returns all items from the buffer and marks it as closed. This is optimized for performance when you need to drain the buffer and won't use it anymore. The returned slice directly references the buffer's underlying array when possible to avoid copying.

func (*RingBuffer[T]) GetN 

func (r *RingBuffer[T]) GetN(n int) (items []T, err error)

GetN returns up to n items from the buffer. Returns ErrIsEmpty if the buffer is empty. The returned slice will have length between 0 and n.

func (*RingBuffer[T]) GetOne 

func (r *RingBuffer[T]) GetOne() (item T, err error)

GetOne returns a single item from the buffer. Returns ErrIsEmpty if the buffer is empty. Blocks if the buffer is empty and the ring buffer is in blocking mode, only a write will unblock it.

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

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]) Reset 

func (r *RingBuffer[T]) Reset()

Reset resets the buffer to empty state

func (*RingBuffer[T]) WithBlocking 

func (r *RingBuffer[T]) WithBlocking(block bool) *RingBuffer[T]

QithBlocking sets the blocking mode of the ring buffer. If block is true, Read and Write will block when there is no data to read or no space to write. If block is false, Read and Write will return ErrIsEmpty or ErrIsFull immediately. By default, the ring buffer is not blocking. This setting should be called before any Read or Write operation or after a Reset.

func (*RingBuffer[T]) WithReadTimeout 

func (r *RingBuffer[T]) WithReadTimeout(d time.Duration) *RingBuffer[T]

WithReadTimeout will set a blocking read timeout. Reads refers to any call that reads data from the buffer. If no writes occur within the timeout, the ringbuffer will be closed and context.DeadlineExceeded will be returned. A timeout of 0 or less will disable timeouts (default).

func (*RingBuffer[T]) WithTimeout 

func (r *RingBuffer[T]) WithTimeout(d time.Duration) *RingBuffer[T]

WithTimeout will set a blocking read/write timeout. If no reads or writes occur within the timeout, the ringbuffer will be closed and context.DeadlineExceeded will be returned. A timeout of 0 or less will disable timeouts (default).

func (*RingBuffer[T]) WithWriteTimeout 

func (r *RingBuffer[T]) WithWriteTimeout(d time.Duration) *RingBuffer[T]

WithWriteTimeout will set a blocking write timeout. Write refers to any call that writes data into the buffer. If no reads occur within the timeout, the ringbuffer will be closed and context.DeadlineExceeded will be returned. A timeout of 0 or less will disable timeouts (default).

func (*RingBuffer[T]) Write 

func (r *RingBuffer[T]) Write(item T) error

Write writes a single item to the buffer. Blocks if the buffer is full and the ring buffer is in blocking mode, only a read will unblock it.

func (*RingBuffer[T]) WriteMany 

func (r *RingBuffer[T]) WriteMany(items []T) (n int, err error)

WriteMany writes multiple items to the buffer

type RingBufferConfig 

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

func (*RingBufferConfig) GetReadTimeout 

func (c *RingBufferConfig) GetReadTimeout() time.Duration

func (*RingBufferConfig) GetWriteTimeout 

func (c *RingBufferConfig) GetWriteTimeout() time.Duration

func (*RingBufferConfig) IsBlocking 

func (c *RingBufferConfig) IsBlocking() bool

Getter methods for RingBufferConfig

type RingBufferConfigBuilder 

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

func NewRingBufferConfigBuilder 

func NewRingBufferConfigBuilder() *RingBufferConfigBuilder

func (*RingBufferConfigBuilder) Build 

func (b *RingBufferConfigBuilder) Build(size int) (*RingBuffer[any], error)

Build creates a new RingBuffer with the configured settings.

func (*RingBufferConfigBuilder) WithBlocking 

func (b *RingBufferConfigBuilder) WithBlocking(block bool) *RingBufferConfigBuilder

WithBlocking sets whether the RingBuffer should operate in blocking mode. If true, Read and Write operations will block when there is no data to read or no space to write. If false, Read and Write operations will return ErrIsEmpty or ErrIsFull immediately.

func (*RingBufferConfigBuilder) WithReadTimeout 

func (b *RingBufferConfigBuilder) WithReadTimeout(d time.Duration) *RingBufferConfigBuilder

WithReadTimeout sets the timeout for read operations. If no writes occur within this timeout, the RingBuffer will be closed and context.DeadlineExceeded will be returned. A timeout of 0 or less will disable timeouts.

func (*RingBufferConfigBuilder) WithWriteTimeout 

func (b *RingBufferConfigBuilder) WithWriteTimeout(d time.Duration) *RingBufferConfigBuilder

WithWriteTimeout sets the timeout for write operations. If no reads occur within this timeout, the RingBuffer will be closed and context.DeadlineExceeded will be returned. A timeout of 0 or less will disable timeouts.

type RingBufferConfigInterface 

type RingBufferConfigInterface interface {
	IsBlocking() bool
	GetReadTimeout() time.Duration
	GetWriteTimeout() time.Duration
	GetCancelContext() context.Context
}

type ShrinkParameters 

type ShrinkParameters interface {
	GetEnforceCustomConfig() bool
	GetAggressivenessLevel() AggressivenessLevel
	GetCheckInterval() time.Duration
	GetIdleThreshold() time.Duration
	GetMinIdleBeforeShrink() int
	GetShrinkCooldown() time.Duration
	GetMinUtilizationBeforeShrink() float64
	GetStableUnderutilizationRounds() int
	GetShrinkPercent() float64
	GetMaxConsecutiveShrinks() int
	GetMinCapacity() int
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.