README
¶
boundedpool-go
A high-performance, thread-safe, bounded object pool implementation for Go, designed as a flexible alternative to sync.Pool.
This package provides a generic object pool (Pooler[T]) with an explicit capacity limit, giving you more predictable memory usage compared to the standard library's sync.Pool. It's particularly useful in high-concurrency scenarios where managing object allocation and reuse is critical for performance.
Installation
Use go get -u:
go get -u github.com/colduction/boundedpool-go
Features
- Bounded Capacity: Set a fixed maximum size for the pool. Items added when the pool is full are discarded (non-blocking
Put). - High Performance: Uses atomic operations and internal sharding (based on
runtime.GOMAXPROCS) to minimize contention under high load. Aims for high throughput (millions of ops/sec). - Thread-Safe: Designed for safe use across multiple goroutines.
- Generic: Works with any Go type (
[T any]). - Factory Function: Provide your own function to create new objects when the pool is empty.
- Interface-Based API:
NewPoolreturns aPooler[T]interface for better decoupling. - Clean Close: Provides a
Closemethod to safely shut down the pool and release resources.
Why use boundedpool-go over sync.Pool?
- Predictable Size:
sync.Poolcan shrink unexpectedly due to garbage collection, discarding pooled items.boundedpool-gomaintains its configured capacity. - Explicit Capacity Control: You define the exact upper limit on the number of pooled items.
- High Throughput Design: Internal sharding specifically targets reducing contention in highly concurrent applications.
Documentation
¶
Index ¶
Constants ¶
const DefaultShardFactor = 2 // e.g., 2 shards per core
DefaultShardFactor determines how many shards per CPU core. Can be tuned based on specific workload benchmarks.
Variables ¶
var ErrPoolClosed = errors.New("boundedpool: pool is closed")
ErrPoolClosed is returned when an operation is attempted on a closed pool.
Functions ¶
This section is empty.
Types ¶
type Pooler ¶
type Pooler[T any] interface { // Get retrieves an item from the pool or creates a new one if the pool is empty. Get() (T, error) // Put adds an item back to the pool into one of the shards. Put(item T) error // Close closes the pool, preventing further Gets or Puts. Close() bool // Len returns the approximate total number of items currently in the pool. Len() int // Cap returns the total capacity of the pool across all shards. Cap() int // NumShards returns the number of internal shards being used. NumShards() int }
Pooler defines the interface for the bounded pool. This allows users to depend on the interface rather than the concrete implementation.
Source Files