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`)

```go
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

```go
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

```go
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
```go
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`)

```go
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`)

```go
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

```go
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

```go
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