interface.go

package connpool

import (
	"context"
)

// Factory defines a function that creates a new connection.
// The provided context can be used for timeouts or cancellation during connection creation.
// The returned connection should be ready to use.
type Factory func(ctx context.Context) (interface{}, error)

// CloseFunc defines a function that closes a connection.
// This function should handle the necessary cleanup for the connection.
type CloseFunc func(conn interface{}) error

// PingFunc defines a function that checks the health of a connection.
// It should return nil if the connection is healthy, or an error if it is not.
// PingFunc should not modify the connection state.
type PingFunc func(conn interface{}) error

// Pool represents a generic connection pool.
// Implementations must be safe for concurrent use by multiple goroutines.
type Pool interface {
	// Get retrieves a connection from the pool.
	// If the pool has an idle connection available, it may be returned.
	// If no idle connection is available, and the pool has not reached its
	// maximum size, a new connection may be created using the Factory.
	// If a PingFunc is configured, it may be called to check health before returning an existing connection.
	// If the pool is at maximum capacity and no idle connections are available,
	// Get will block until a connection is returned to the pool or the context
	// is cancelled.
	Get(ctx context.Context) (interface{}, error)

	// Put returns a connection to the pool, making it available for reuse.
	// If the connection is nil, invalid, or does not belong to this pool, Put attempts
	// to close it using the configured CloseFunc and returns.
	// If the pool is closed, the connection is closed.
	// Otherwise, Put attempts to hand the connection to a waiting goroutine (from Get).
	// If no goroutines are waiting, it adds the connection to the idle list, potentially
	// evicting the oldest idle connection if MaxIdle is reached.
	Put(conn interface{})

	// Discard removes a connection from the pool and closes it, usually because
	// the connection is known to be broken or unhealthy. Discard closes the connection
	// using the configured CloseFunc.
	// It returns ErrInvalidConnection if the provided connection is nil, does not belong
	// to this pool, or is already closed.
	// It returns ErrPoolClosed if the pool was already closed when Discard was called,
	// but still attempts to close the connection. Otherwise, it returns the result
	// of the underlying CloseFunc call.
	Discard(conn interface{}) error

	// Close closes the pool and all its connections.
	// After Close returns, Get will return an error.
	// Close immediately closes all idle connections. It then waits for all active
	// connections to be returned (via Put or Discard) before returning.
	// If the context is cancelled before all connections are returned, the context's
	// error is returned. Close returns ErrPoolClosed if called more than once.
	Close(ctx context.Context) error

	// Len returns the current number of connections in the pool (both active and idle).
	Len() int

	// IdleLen returns the current number of idle connections in the pool.
	IdleLen() int

	// Stats returns a snapshot of the pool's metrics.
	Stats() Metrics
}