conncache

Documentation

Index

• type Cache
  • func New(opts Options) Cache
• type Connection
• type Metrics
• type Options
• type ReleaseFunc

Types

type Cache

type Cache interface {
	// Acquire retrieves or opens a connection for the given config. The returned ReleaseFunc must be called when the connection is no longer needed.
	// While a connection is acquired, it will not be closed unless EvictWhere or Close is called.
	// If Acquire is called while the underlying connection is being evicted, it will wait for the close to complete and then open a new connection.
	// If opening the connection fails, Acquire may return the error on subsequent calls without trying to open again until the entry is evicted.
	Acquire(ctx context.Context, cfg any) (Connection, ReleaseFunc, error)

	// EvictWhere closes the connections that match the predicate.
	// It immediately starts closing the connections, even those that are currently acquired.
	// It returns quickly and does not wait for connections to finish closing in the background.
	EvictWhere(predicate func(cfg any) bool)

	// Close closes all open connections and prevents new connections from being acquired.
	// It returns when all cached connections have been closed or when the provided ctx is cancelled.
	Close(ctx context.Context) error

	// HangingErr returns an error containing the name of a connection that is hanging
	HangingErr() error
}

Cache is a concurrency-safe cache of stateful connection objects. It differs from a connection pool in that it's designed for caching heterogenous connections. The cache will at most open one connection per key, even under concurrent access. The cache automatically evicts connections that are not in use ("acquired") using a least-recently-used policy.

func New

func New(opts Options) Cache

type Connection

type Connection interface {
	Driver() string
	Close() error
}

Connection is a connection that may be cached.

type Metrics

type Metrics struct {
	Opens          metric.Int64Counter
	Closes         metric.Int64Counter
	SizeTotal      metric.Int64UpDownCounter
	SizeLRU        metric.Int64UpDownCounter
	OpenLatencyMS  metric.Int64Histogram
	CloseLatencyMS metric.Int64Histogram
}

Metrics are optional instruments for observability. If an instrument is nil, it will not be collected.

type Options

type Options struct {
	// MaxIdleConnections is the maximum number of non-acquired connections that will be kept open.
	MaxIdleConnections int
	// OpenTimeout is the maximum amount of time to wait for a connection to open.
	OpenTimeout time.Duration
	// CloseTimeout is the maximum amount of time to wait for a connection to close.
	CloseTimeout time.Duration
	// CheckHangingInterval is the interval at which to check for hanging open/close calls.
	CheckHangingInterval time.Duration
	// OpenFunc opens a connection.
	OpenFunc func(ctx context.Context, cfg any) (Connection, error)
	// KeyFunc computes a comparable key for a connection config.
	KeyFunc func(cfg any) string
	// HangingFunc is called when an open or close exceeds its timeout and does not respond to context cancellation.
	HangingFunc func(cfg any, open bool)
	// Metrics are optional instruments for observability.
	Metrics Metrics
}

Options configures a new connection cache.

type ReleaseFunc

type ReleaseFunc func()

ReleaseFunc is a function that must be called when an acquired connection is no longer needed.