README
¶
pool
Production-grade object pools, connection pools, and goroutine worker pools.
Components
ObjectPool — Generic Object Pool
A generic, thread-safe object pool with configurable max open objects.
pool := pool.NewObjectPool(func() (*sql.Conn, error) {
return db.Conn(ctx)
}, 10, func(c *sql.Conn) { c.Close() })
conn, err := pool.Get()
defer pool.Put(conn)
stats := pool.Stats() // OpenCount, IdleCount, InUse
ConnPool — Connection Pool with Health Check + Idle Eviction
Extends the object pool with:
- Health check on Get — unhealthy connections are destroyed and replaced
- Max lifetime — connections older than
MaxLifetimeare recycled - Idle eviction — a background janitor evicts connections idle longer than
MaxIdleTime
pool := pool.NewConnPool(factory, destroyer, pool.ConnConfig{
MaxOpen: 20,
MaxIdle: 10,
MaxIdleTime: 5 * time.Minute,
MaxLifetime: 30 * time.Minute,
HealthCheck: func(c *sql.Conn) error { return c.PingContext(ctx) },
HealthPeriod: 1 * time.Minute,
})
WorkerPool — Goroutine Worker Pool
A fixed-size goroutine pool with a buffered task queue and graceful shutdown.
wp := pool.NewWorkerPool(8, 1000) // 8 workers, 1000 task buffer
wp.Start()
err := wp.Submit(func() {
// do work
})
wp.Stop() // graceful — waits for all tasks to complete
License
MIT
Documentation
¶
Overview ¶
Package pool provides reusable resource pooling primitives for the ling-base foundation library.
It ships with three building blocks:
- ObjectPool: a generic, bounded object pool backed by a channel-based idle queue and a configurable maximum open count. Get blocks when the pool is at capacity and resumes as soon as an object is returned.
- ConnPool: a connection pool built on top of the object-pool concept that adds health checks, per-connection max lifetime and background idle eviction.
- WorkerPool: a fixed-size goroutine worker pool that dispatches submitted tasks to N workers with graceful shutdown and panic recovery.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrPoolClosed = errors.New("pool: closed")
ErrPoolClosed is returned when an operation is attempted on a closed pool.
Functions ¶
This section is empty.
Types ¶
type ConnConfig ¶
type ConnConfig struct {
MaxOpen int
MaxIdle int
MaxIdleTime time.Duration
MaxLifetime time.Duration
HealthCheck func(any) error
HealthPeriod time.Duration
}
ConnConfig configures a ConnPool.
type ConnPool ¶
type ConnPool[T any] struct { // contains filtered or unexported fields }
ConnPool is a connection pool that extends the object-pool concept with health checks, per-connection max lifetime and background idle eviction.
On Get, idle connections are validated against MaxLifetime and the configured HealthCheck function; invalid connections are destroyed and another is tried. A background janitor goroutine periodically evicts idle connections that have been idle longer than MaxIdleTime and runs health checks at HealthPeriod intervals.
func NewConnPool ¶
func NewConnPool[T any](factory Factory[T], destroyer Destroyer[T], cfg ConnConfig) *ConnPool[T]
NewConnPool returns a new ConnPool with the given factory, destroyer and configuration. The pool is ready to use immediately and starts its background janitor goroutine when MaxIdleTime or HealthPeriod is positive.
func (*ConnPool[T]) Close ¶
func (p *ConnPool[T]) Close()
Close closes the pool. It stops the background janitor, drains the idle queue invoking the destroyer on every idle connection, and marks the pool as closed. It is safe to call Close more than once.
func (*ConnPool[T]) Get ¶
Get returns a healthy connection from the idle queue, or creates a new one if the pool is below MaxOpen. It blocks while the pool is at capacity. Idle connections are checked against MaxLifetime and HealthCheck; those that fail are destroyed and another connection is tried.
type Destroyer ¶
type Destroyer[T any] func(x T)
Destroyer releases resources associated with x. It is optional; a nil destroyer means no cleanup is performed when an object is discarded.
type ObjectPool ¶
type ObjectPool[T any] struct { // contains filtered or unexported fields }
ObjectPool is a generic, bounded pool of reusable objects.
Objects are kept in a channel-based idle queue. Get returns an idle object when available, or creates a new one while the number of open objects is below maxOpen. When the pool is at capacity, Get blocks until an object is returned via Put.
func NewObjectPool ¶
func NewObjectPool[T any](factory Factory[T], maxOpen int, destroyer Destroyer[T]) *ObjectPool[T]
NewObjectPool returns a new ObjectPool with the given factory, maximum open count and optional destroyer. The pool is ready to use immediately.
func (*ObjectPool[T]) Close ¶
func (p *ObjectPool[T]) Close()
Close closes the pool. It drains the idle queue, invoking the destroyer on every idle object, and marks the pool as closed so that further Get calls return ErrPoolClosed. It is safe to call Close more than once.
func (*ObjectPool[T]) Get ¶
func (p *ObjectPool[T]) Get() (T, error)
Get returns an object from the idle queue, or creates a new one if the pool is below maxOpen. It blocks while the pool is at capacity and resumes when an object is returned. It returns ErrPoolClosed if the pool is closed.
func (*ObjectPool[T]) Put ¶
func (p *ObjectPool[T]) Put(x T)
Put returns x to the idle queue. If the pool is closed or the idle queue is full, the destroyer (if any) is invoked on x and the open count is decremented.
func (*ObjectPool[T]) Stats ¶
func (p *ObjectPool[T]) Stats() PoolStats
Stats returns a snapshot of the pool's current state.
type WorkerPool ¶
type WorkerPool struct {
// contains filtered or unexported fields
}
WorkerPool is a fixed-size goroutine worker pool. Tasks submitted via Submit are dispatched to one of N worker goroutines. The pool supports graceful shutdown via Stop, which waits for all in-flight tasks to complete, and recovers from task panics so that a panicking task never brings down a worker.
func NewWorkerPool ¶
func NewWorkerPool(workers int, queueSize int) *WorkerPool
NewWorkerPool returns a new WorkerPool with the given worker count and queue size. The pool is not started until Start is called.
func (*WorkerPool) Start ¶
func (p *WorkerPool) Start()
Start launches the worker goroutines. It must be called before Submit.
func (*WorkerPool) Stats ¶
func (p *WorkerPool) Stats() WorkerStats
Stats returns a snapshot of the pool's current metrics.
func (*WorkerPool) Stop ¶
func (p *WorkerPool) Stop()
Stop initiates a graceful shutdown: it stops accepting new tasks, lets workers finish all queued tasks, and waits for all workers to exit. It is safe to call Stop more than once.
func (*WorkerPool) Submit ¶
func (p *WorkerPool) Submit(task func()) error
Submit enqueues task for execution by a worker. It returns ErrPoolClosed if the pool has been stopped. When the queue is full, Submit blocks until space is available or the pool is stopped.
Source Files