go-redis/docs/redis_pool.md

Redis Connection Pool Implementation

Overview

The Redis client implements a sophisticated connection pooling mechanism to efficiently manage Redis connections. This document details the implementation, features, and behavior of the connection pool system.

Core Components

1. Connection Interface (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

    Close() error
}

The Pooler interface defines the contract for all connection pool implementations:

• Connection lifecycle management
• Connection acquisition and release
• Pool statistics and monitoring
• Resource cleanup

2. Connection Pool Options

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

    PoolFIFO        bool
    PoolSize        int
    DialTimeout     time.Duration
    PoolTimeout     time.Duration
    MinIdleConns    int
    MaxIdleConns    int
    MaxActiveConns  int
    ConnMaxIdleTime time.Duration
    ConnMaxLifetime time.Duration
}

Key configuration parameters:

• PoolFIFO: Use FIFO mode for connection pool GET/PUT (default LIFO)
• PoolSize: Base number of connections (default: 10 * runtime.GOMAXPROCS)
• MinIdleConns: Minimum number of idle connections
• MaxIdleConns: Maximum number of idle connections
• MaxActiveConns: Maximum number of active connections
• ConnMaxIdleTime: Maximum idle time for connections
• ConnMaxLifetime: Maximum lifetime for connections

3. Connection Pool Statistics

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

    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
}

4. Main Connection Pool Implementation (ConnPool)

Structure

type ConnPool struct {
    cfg *Options

    dialErrorsNum uint32 // atomic
    lastDialError atomic.Value

    queue chan struct{}

    connsMu   sync.Mutex
    conns     []*Conn
    idleConns []*Conn

    poolSize     int
    idleConnsLen int

    stats Stats

    _closed uint32 // atomic
}

Key Features

1. Thread Safety

   • Mutex-protected connection lists
   • Atomic operations for counters
   • Thread-safe connection management

2. Connection Management

   • Automatic connection creation
   • Connection reuse
   • Connection cleanup
   • Health checks

3. Resource Control

   • Maximum connection limits
   • Idle connection management
   • Connection lifetime control
   • Timeout handling

4. Error Handling

   • Connection error tracking
   • Automatic error recovery
   • Error propagation
   • Connection validation

5. Single Connection Pool (SingleConnPool)

type SingleConnPool struct {
    pool      Pooler
    cn        *Conn
    stickyErr error
}

Use cases:

• Single connection scenarios
• Transaction operations
• Pub/Sub subscriptions
• Pipeline operations

Features:

• Dedicated connection management
• Error state tracking
• Connection reuse
• Resource cleanup

6. Sticky Connection Pool (StickyConnPool)

type StickyConnPool struct {
    pool   Pooler
    shared int32 // atomic
    state  uint32 // atomic
    ch     chan *Conn
    _badConnError atomic.Value
}

Features:

• Connection stickiness
• State management
• Error handling
• Thread safety
• Connection sharing

7. Connection Health Checks

func (p *ConnPool) isHealthyConn(cn *Conn) bool {
    now := time.Now()

    if p.cfg.ConnMaxLifetime > 0 && now.Sub(cn.createdAt) >= p.cfg.ConnMaxLifetime {
        return false
    }
    if p.cfg.ConnMaxIdleTime > 0 && now.Sub(cn.UsedAt()) >= p.cfg.ConnMaxIdleTime {
        return false
    }

    if connCheck(cn.netConn) != nil {
        return false
    }

    cn.SetUsedAt(now)
    return true
}

Health check criteria:

• Connection lifetime
• Idle time
• Network connectivity
• Protocol state

8. Error Types

var (
    ErrClosed = errors.New("redis: client is closed")
    ErrPoolExhausted = errors.New("redis: connection pool exhausted")
    ErrPoolTimeout = errors.New("redis: connection pool timeout")
)

type BadConnError struct {
    wrapped error
}

9. Best Practices

1. Pool Configuration

   • Set appropriate pool size based on workload
   • Configure timeouts based on network conditions
   • Monitor pool statistics
   • Adjust idle connection settings

2. Connection Management

   • Proper connection cleanup
   • Error handling
   • Resource limits
   • Health monitoring

3. Performance Optimization

   • Connection reuse
   • Efficient pooling
   • Resource cleanup
   • Error recovery

4. Monitoring

   • Track pool statistics
   • Monitor connection health
   • Watch for errors
   • Resource usage

10. Known Issues and Limitations

1. Performance Considerations

   • Lock contention in high-concurrency scenarios
   • Connection creation overhead
   • Resource cleanup impact
   • Memory usage

2. Resource Management

   • Connection leaks in edge cases
   • Resource cleanup timing
   • Memory fragmentation
   • Network resource usage

3. Error Handling

   • Error recovery strategies
   • Connection validation
   • Error propagation
   • State management

11. Future Improvements

1. Performance

   • Optimize lock contention
   • Improve connection reuse
   • Enhance resource cleanup
   • Better memory management

2. Features

   • Enhanced monitoring
   • Better error handling
   • Improved resource management
   • Advanced connection validation

3. Reliability

   • Better error recovery
   • Enhanced health checks
   • Improved state management
   • Better resource cleanup