pool

package
v9.15.0 Latest Latest
Warning

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

 Go to latest Published: Sep 26, 2025 License: BSD-2-Clause Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrClosed performs any operation on the closed client will return this error.
	ErrClosed = errors.New("redis: client is closed")

	// ErrPoolExhausted is returned from a pool connection method
	// when the maximum number of database connections in the pool has been reached.
	ErrPoolExhausted = errors.New("redis: connection pool exhausted")

	// ErrPoolTimeout timed out waiting to get a connection from the connection pool.
	ErrPoolTimeout = errors.New("redis: connection pool timeout")
)

Functions

This section is empty.

Types

type BadConnError 

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

func (BadConnError) Error 

func (e BadConnError) Error() string

func (BadConnError) Unwrap 

func (e BadConnError) Unwrap() error

type Conn 

type Conn struct {
	Inited atomic.Bool
	// contains filtered or unexported fields
}

func NewConn 

func NewConn(netConn net.Conn) *Conn

func NewConnWithBufferSize added in v9.12.0 

func NewConnWithBufferSize(netConn net.Conn, readBufSize, writeBufSize int) *Conn

func (*Conn) ClearHandoffState added in v9.15.0 

func (cn *Conn) ClearHandoffState()

ClearHandoffState clears the handoff state after successful handoff (lock-free).

func (*Conn) ClearRelaxedTimeout added in v9.15.0 

func (cn *Conn) ClearRelaxedTimeout()

ClearRelaxedTimeout removes relaxed timeouts, returning to normal timeout behavior. Uses atomic operations for lock-free access.

func (*Conn) Close 

func (cn *Conn) Close() error

func (*Conn) ExecuteInitConn added in v9.15.0 

func (cn *Conn) ExecuteInitConn(ctx context.Context) error

ExecuteInitConn runs the stored connection initialization function if available.

func (*Conn) GetHandoffEndpoint added in v9.15.0 

func (cn *Conn) GetHandoffEndpoint() string

GetHandoffEndpoint returns the new endpoint for handoff (lock-free).

func (*Conn) GetHandoffInfo added in v9.15.0 

func (cn *Conn) GetHandoffInfo() (bool, string, int64)

GetHandoffInfo returns all handoff information atomically (lock-free). This method prevents race conditions by returning all handoff state in a single atomic operation. Returns (shouldHandoff, endpoint, seqID).

func (*Conn) GetID added in v9.15.0 

func (cn *Conn) GetID() uint64

GetID returns the unique identifier for this connection.

func (*Conn) GetMovingSeqID added in v9.15.0 

func (cn *Conn) GetMovingSeqID() int64

GetMovingSeqID returns the sequence ID from the MOVING notification (lock-free).

func (*Conn) GetNetConn added in v9.15.0 

func (cn *Conn) GetNetConn() net.Conn

GetNetConn safely returns the current network connection using atomic load (lock-free). This method is used by the pool for health checks and provides better performance.

func (*Conn) HandoffRetries added in v9.15.0 

func (cn *Conn) HandoffRetries() int

GetHandoffRetries returns the current handoff retry count (lock-free).

func (*Conn) HasBufferedData added in v9.15.0 

func (cn *Conn) HasBufferedData() bool

HasBufferedData safely checks if the connection has buffered data. This method is used to avoid data races when checking for push notifications.

func (*Conn) HasRelaxedTimeout added in v9.15.0 

func (cn *Conn) HasRelaxedTimeout() bool

HasRelaxedTimeout returns true if relaxed timeouts are currently active on this connection. This checks both the timeout values and the deadline (if set). Uses atomic operations for lock-free access.

func (*Conn) IncrementAndGetHandoffRetries added in v9.15.0 

func (cn *Conn) IncrementAndGetHandoffRetries(n int) int

IncrementAndGetHandoffRetries atomically increments and returns handoff retries (lock-free).

func (*Conn) IsClosed added in v9.15.0 

func (cn *Conn) IsClosed() bool

func (*Conn) IsInited added in v9.15.0 

func (cn *Conn) IsInited() bool

func (*Conn) IsPooled added in v9.15.0 

func (cn *Conn) IsPooled() bool

IsPooled returns true if the connection is managed by a pool and will be pooled on Put.

func (*Conn) IsPubSub added in v9.15.0 

func (cn *Conn) IsPubSub() bool

IsPubSub returns true if the connection is used for PubSub.

func (*Conn) IsUsable added in v9.15.0 

func (cn *Conn) IsUsable() bool

IsUsable returns true if the connection is safe to use for new commands (lock-free).

func (*Conn) MarkForHandoff added in v9.15.0 

func (cn *Conn) MarkForHandoff(newEndpoint string, seqID int64) error

MarkForHandoff marks the connection for handoff due to MOVING notification (lock-free). Returns an error if the connection is already marked for handoff. This method uses atomic compare-and-swap to ensure all handoff state is updated atomically.

func (*Conn) MarkQueuedForHandoff added in v9.15.0 

func (cn *Conn) MarkQueuedForHandoff() error

func (*Conn) MaybeHasData added in v9.15.0 

func (cn *Conn) MaybeHasData() bool

MaybeHasData tries to peek at the next byte in the socket without consuming it This is used to check if there are push notifications available Important: This will work on Linux, but not on Windows

func (*Conn) PeekReplyTypeSafe added in v9.15.0 

func (cn *Conn) PeekReplyTypeSafe() (byte, error)

PeekReplyTypeSafe safely peeks at the reply type. This method is used to avoid data races when checking for push notifications.

func (*Conn) RemoteAddr 

func (cn *Conn) RemoteAddr() net.Addr

func (*Conn) SetInitConnFunc added in v9.15.0 

func (cn *Conn) SetInitConnFunc(fn func(context.Context, *Conn) error)

SetInitConnFunc sets the connection initialization function to be called on reconnections.

func (*Conn) SetNetConn 

func (cn *Conn) SetNetConn(netConn net.Conn)

func (*Conn) SetNetConnAndInitConn added in v9.15.0 

func (cn *Conn) SetNetConnAndInitConn(ctx context.Context, netConn net.Conn) error

SetNetConnAndInitConn replaces the underlying connection and executes the initialization.

func (*Conn) SetOnClose added in v9.9.0 

func (cn *Conn) SetOnClose(fn func() error)

func (*Conn) SetRelaxedTimeout added in v9.15.0 

func (cn *Conn) SetRelaxedTimeout(readTimeout, writeTimeout time.Duration)

SetRelaxedTimeout sets relaxed timeouts for this connection during maintenanceNotifications upgrades. These timeouts will be used for all subsequent commands until the deadline expires. Uses atomic operations for lock-free access.

func (*Conn) SetRelaxedTimeoutWithDeadline added in v9.15.0 

func (cn *Conn) SetRelaxedTimeoutWithDeadline(readTimeout, writeTimeout time.Duration, deadline time.Time)

SetRelaxedTimeoutWithDeadline sets relaxed timeouts with an expiration deadline. After the deadline, timeouts automatically revert to normal values. Uses atomic operations for lock-free access.

func (*Conn) SetUsable added in v9.15.0 

func (cn *Conn) SetUsable(usable bool)

SetUsable sets the usable flag for the connection (lock-free).

func (*Conn) SetUsedAt 

func (cn *Conn) SetUsedAt(tm time.Time)

func (*Conn) ShouldHandoff added in v9.15.0 

func (cn *Conn) ShouldHandoff() bool

ShouldHandoff returns true if the connection needs to be handed off (lock-free).

func (*Conn) UsedAt 

func (cn *Conn) UsedAt() time.Time

func (*Conn) WithReader 

func (cn *Conn) WithReader(
	ctx context.Context, timeout time.Duration, fn func(rd *proto.Reader) error,
) error

func (*Conn) WithWriter 

func (cn *Conn) WithWriter(
	ctx context.Context, timeout time.Duration, fn func(wr *proto.Writer) error,
) error

func (*Conn) Write 

func (cn *Conn) Write(b []byte) (int, error)

type ConnPool 

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

func NewConnPool 

func NewConnPool(opt *Options) *ConnPool

func (*ConnPool) AddPoolHook added in v9.15.0 

func (p *ConnPool) AddPoolHook(hook PoolHook)

AddPoolHook adds a pool hook to the pool.

func (*ConnPool) Close 

func (p *ConnPool) Close() error

func (*ConnPool) CloseConn 

func (p *ConnPool) CloseConn(cn *Conn) error

func (*ConnPool) Filter 

func (p *ConnPool) Filter(fn func(*Conn) bool) error

func (*ConnPool) Get 

func (p *ConnPool) Get(ctx context.Context) (*Conn, error)

Get returns existed connection from the pool or creates a new one.

func (*ConnPool) IdleLen 

func (p *ConnPool) IdleLen() int

IdleLen returns number of idle connections.

func (*ConnPool) Len 

func (p *ConnPool) Len() int

Len returns total number of connections.

func (*ConnPool) NewConn 

func (p *ConnPool) NewConn(ctx context.Context) (*Conn, error)

NewConn creates a new connection and returns it to the user. This will still obey MaxActiveConns but will not include it in the pool and won't increase the pool size.

NOTE: If you directly get a connection from the pool, it won't be pooled and won't support maintnotifications upgrades.

func (*ConnPool) Put 

func (p *ConnPool) Put(ctx context.Context, cn *Conn)

func (*ConnPool) Remove 

func (p *ConnPool) Remove(_ context.Context, cn *Conn, reason error)

func (*ConnPool) RemovePoolHook added in v9.15.0 

func (p *ConnPool) RemovePoolHook(hook PoolHook)

RemovePoolHook removes a pool hook from the pool.

func (*ConnPool) Stats 

func (p *ConnPool) Stats() *Stats

type HandoffState added in v9.15.0 

type HandoffState struct {
	ShouldHandoff bool   // Whether connection should be handed off
	Endpoint      string // New endpoint for handoff
	SeqID         int64  // Sequence ID from MOVING notification
}

HandoffState represents the atomic state for connection handoffs This struct is stored atomically to prevent race conditions between checking handoff status and reading handoff parameters

type Options 

type Options struct {
	Dialer          func(context.Context) (net.Conn, error)
	ReadBufferSize  int
	WriteBufferSize int

	PoolFIFO                 bool
	PoolSize                 int32
	DialTimeout              time.Duration
	PoolTimeout              time.Duration
	MinIdleConns             int32
	MaxIdleConns             int32
	MaxActiveConns           int32
	ConnMaxIdleTime          time.Duration
	ConnMaxLifetime          time.Duration
	PushNotificationsEnabled bool

	// DialerRetries is the maximum number of retry attempts when dialing fails.
	// Default: 5
	DialerRetries int

	// DialerRetryTimeout is the backoff duration between retry attempts.
	// Default: 100ms
	DialerRetryTimeout time.Duration
}

type PoolHook added in v9.15.0 

type PoolHook interface {
	// OnGet is called when a connection is retrieved from the pool.
	// It can modify the connection or return an error to prevent its use.
	// It has isNewConn flag to indicate if this is a new connection (rather than idle from the pool)
	// The flag can be used for gathering metrics on pool hit/miss ratio.
	OnGet(ctx context.Context, conn *Conn, isNewConn bool) error

	// OnPut is called when a connection is returned to the pool.
	// It returns whether the connection should be pooled and whether it should be removed.
	OnPut(ctx context.Context, conn *Conn) (shouldPool bool, shouldRemove bool, err error)
}

PoolHook defines the interface for connection lifecycle hooks.

type PoolHookManager added in v9.15.0 

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

PoolHookManager manages multiple pool hooks.

func NewPoolHookManager added in v9.15.0 

func NewPoolHookManager() *PoolHookManager

NewPoolHookManager creates a new pool hook manager.

func (*PoolHookManager) AddHook added in v9.15.0 

func (phm *PoolHookManager) AddHook(hook PoolHook)

AddHook adds a pool hook to the manager. Hooks are called in the order they were added.

func (*PoolHookManager) GetHookCount added in v9.15.0 

func (phm *PoolHookManager) GetHookCount() int

GetHookCount returns the number of registered hooks (for testing).

func (*PoolHookManager) GetHooks added in v9.15.0 

func (phm *PoolHookManager) GetHooks() []PoolHook

GetHooks returns a copy of all registered hooks.

func (*PoolHookManager) ProcessOnGet added in v9.15.0 

func (phm *PoolHookManager) ProcessOnGet(ctx context.Context, conn *Conn, isNewConn bool) error

ProcessOnGet calls all OnGet hooks in order. If any hook returns an error, processing stops and the error is returned.

func (*PoolHookManager) ProcessOnPut added in v9.15.0 

func (phm *PoolHookManager) ProcessOnPut(ctx context.Context, conn *Conn) (shouldPool bool, shouldRemove bool, err error)

ProcessOnPut calls all OnPut hooks in order. The first hook that returns shouldRemove=true or shouldPool=false will stop processing.

func (*PoolHookManager) RemoveHook added in v9.15.0 

func (phm *PoolHookManager) RemoveHook(hook PoolHook)

RemoveHook removes a pool hook from the manager.

type Pooler 

type Pooler interface {
	NewConn(context.Context) (*Conn, error)
	CloseConn(*Conn) error

	Get(context.Context) (*Conn, error)
	Put(context.Context, *Conn)
	Remove(context.Context, *Conn, error)

	Len() int
	IdleLen() int
	Stats() *Stats

	AddPoolHook(hook PoolHook)
	RemovePoolHook(hook PoolHook)

	Close() error
}

type PubSubPool added in v9.15.0 

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

PubSubPool manages a pool of PubSub connections.

func NewPubSubPool added in v9.15.0 

func NewPubSubPool(opt *Options, netDialer func(ctx context.Context, network, addr string) (net.Conn, error)) *PubSubPool

func (*PubSubPool) Close added in v9.15.0 

func (p *PubSubPool) Close() error

func (*PubSubPool) NewConn added in v9.15.0 

func (p *PubSubPool) NewConn(ctx context.Context, network string, addr string, channels []string) (*Conn, error)

func (*PubSubPool) Stats added in v9.15.0 

func (p *PubSubPool) Stats() *PubSubStats

func (*PubSubPool) TrackConn added in v9.15.0 

func (p *PubSubPool) TrackConn(cn *Conn)

func (*PubSubPool) UntrackConn added in v9.15.0 

func (p *PubSubPool) UntrackConn(cn *Conn)

type PubSubStats added in v9.15.0 

type PubSubStats struct {
	Created   uint32
	Untracked uint32
	Active    uint32
}

type SingleConnPool 

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

func NewSingleConnPool 

func NewSingleConnPool(pool Pooler, cn *Conn) *SingleConnPool

func (*SingleConnPool) AddPoolHook added in v9.15.0 

func (p *SingleConnPool) AddPoolHook(hook PoolHook)

func (*SingleConnPool) Close 

func (p *SingleConnPool) Close() error

func (*SingleConnPool) CloseConn 

func (p *SingleConnPool) CloseConn(cn *Conn) error

func (*SingleConnPool) Get 

func (p *SingleConnPool) Get(ctx context.Context) (*Conn, error)

func (*SingleConnPool) IdleLen 

func (p *SingleConnPool) IdleLen() int

func (*SingleConnPool) Len 

func (p *SingleConnPool) Len() int

func (*SingleConnPool) NewConn 

func (p *SingleConnPool) NewConn(ctx context.Context) (*Conn, error)

func (*SingleConnPool) Put 

func (p *SingleConnPool) Put(ctx context.Context, cn *Conn)

func (*SingleConnPool) Remove 

func (p *SingleConnPool) Remove(ctx context.Context, cn *Conn, reason error)

func (*SingleConnPool) RemovePoolHook added in v9.15.0 

func (p *SingleConnPool) RemovePoolHook(hook PoolHook)

func (*SingleConnPool) Stats 

func (p *SingleConnPool) Stats() *Stats

type Stats 

type Stats struct {
	Hits           uint32 // number of times free connection was found in the pool
	Misses         uint32 // number of times free connection was NOT found in the pool
	Timeouts       uint32 // number of times a wait timeout occurred
	WaitCount      uint32 // number of times a connection was waited
	Unusable       uint32 // number of times a connection was found to be unusable
	WaitDurationNs int64  // total time spent for waiting a connection in nanoseconds

	TotalConns uint32 // number of total connections in the pool
	IdleConns  uint32 // number of idle connections in the pool
	StaleConns uint32 // number of stale connections removed from the pool

	PubSubStats PubSubStats
}

Stats contains pool state information and accumulated stats.

type StickyConnPool 

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

func NewStickyConnPool 

func NewStickyConnPool(pool Pooler) *StickyConnPool

func (*StickyConnPool) AddPoolHook added in v9.15.0 

func (p *StickyConnPool) AddPoolHook(hook PoolHook)

func (*StickyConnPool) Close 

func (p *StickyConnPool) Close() error

func (*StickyConnPool) CloseConn 

func (p *StickyConnPool) CloseConn(cn *Conn) error

func (*StickyConnPool) Get 

func (p *StickyConnPool) Get(ctx context.Context) (*Conn, error)

func (*StickyConnPool) IdleLen 

func (p *StickyConnPool) IdleLen() int

func (*StickyConnPool) Len 

func (p *StickyConnPool) Len() int

func (*StickyConnPool) NewConn 

func (p *StickyConnPool) NewConn(ctx context.Context) (*Conn, error)

func (*StickyConnPool) Put 

func (p *StickyConnPool) Put(ctx context.Context, cn *Conn)

func (*StickyConnPool) Remove 

func (p *StickyConnPool) Remove(ctx context.Context, cn *Conn, reason error)

func (*StickyConnPool) RemovePoolHook added in v9.15.0 

func (p *StickyConnPool) RemovePoolHook(hook PoolHook)

func (*StickyConnPool) Reset 

func (p *StickyConnPool) Reset(ctx context.Context) error

func (*StickyConnPool) Stats 

func (p *StickyConnPool) Stats() *Stats

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.