Documentation
¶
Overview ¶
Package pool provides memory pooling utilities to reduce allocations and improve performance for frequently allocated objects like buffers, readers, writers, and HTTP connections.
Index ¶
- Constants
- Variables
- func AppendString(dst []byte, s string) []byte
- func BytesToString(b []byte) string
- func BytesToStringCopy(b []byte) string
- func EqualFoldASCII(s, t []byte) bool
- func GetSizeClass(size int) *[]byte
- func GetSizeClassSlice(size int) []byte
- func Go(task func())
- func PutSizeClass(buf *[]byte)
- func PutSizeClassSlice(buf []byte)
- func Release()
- func ReleaseRequestArena(a *RequestArena)
- func StringToBytes(s string) []byte
- func StringToBytesCopy(s string) []byte
- func Submit(task func()) error
- type BufferPool
- type BufferPoolStats
- type BytesBufferPool
- type ConnPool
- type DialFunc
- type Headers
- func (h *Headers) Add(key, value string)
- func (h *Headers) Clone() *Headers
- func (h *Headers) Del(key string)
- func (h *Headers) FromMap(m map[string][]string)
- func (h *Headers) Get(key string) string
- func (h *Headers) GetAll(key string) []string
- func (h *Headers) Len() int
- func (h *Headers) Range(fn func(key string, values []string) bool)
- func (h *Headers) Release()
- func (h *Headers) Reset()
- func (h *Headers) Set(key, value string)
- func (h *Headers) ToMap() map[string][]string
- type HeadersPool
- type ManagedConn
- func (mc *ManagedConn) Close() error
- func (mc *ManagedConn) ForceClose() error
- func (mc *ManagedConn) LocalAddr() net.Addr
- func (mc *ManagedConn) Read(b []byte) (n int, err error)
- func (mc *ManagedConn) RemoteAddr() net.Addr
- func (mc *ManagedConn) SetDeadline(t time.Time) error
- func (mc *ManagedConn) SetReadDeadline(t time.Time) error
- func (mc *ManagedConn) SetWriteDeadline(t time.Time) error
- func (mc *ManagedConn) Write(b []byte) (n int, err error)
- type PoolConfig
- type PoolStats
- type ReaderPool
- type RequestArena
- type RingBuffer
- func (rb *RingBuffer) Cap() int
- func (rb *RingBuffer) Close() error
- func (rb *RingBuffer) CloseWithError(err error) error
- func (rb *RingBuffer) Len() int
- func (rb *RingBuffer) Read(p []byte) (int, error)
- func (rb *RingBuffer) Release()
- func (rb *RingBuffer) Reset()
- func (rb *RingBuffer) Write(data []byte) (int, error)
- type RingBufferPool
- type SizeClassPool
- type WorkerPool
- func (p *WorkerPool) Capacity() int
- func (p *WorkerPool) Close()
- func (p *WorkerPool) Free() int
- func (p *WorkerPool) Go(task func())
- func (p *WorkerPool) IsClosed() bool
- func (p *WorkerPool) Reboot()
- func (p *WorkerPool) Release()
- func (p *WorkerPool) ReleaseTimeout(timeout time.Duration) error
- func (p *WorkerPool) Running() int
- func (p *WorkerPool) Submit(task func()) error
- func (p *WorkerPool) Tune(size int)
- func (p *WorkerPool) Waiting() int
- type WorkerPoolConfig
- type WriterPool
Constants ¶
const ( SmallBufferSize = 4 * 1024 // 4KB - headers, small responses MediumBufferSize = 64 * 1024 // 64KB - typical responses LargeBufferSize = 1 * 1024 * 1024 // 1MB - large responses )
Buffer sizes for different use cases.
const ( SizeClass512B = 512 // Small headers, short frames SizeClass2KB = 2 * 1024 // Typical header blocks SizeClass8KB = 8 * 1024 // Large header blocks SizeClass32KB = 32 * 1024 // Very large responses )
Size class thresholds for variable-sized allocations. These sizes are optimized for HPACK encoding, frame payloads, and similar hot paths.
Variables ¶
var ( ErrPoolClosed = errors.New("connection pool is closed") ErrNoConnection = errors.New("no available connection") ErrConnUnhealthy = errors.New("connection is unhealthy") )
var DefaultSizeClassPool = NewSizeClassPool()
Global instance for convenience
Functions ¶
func AppendString ¶
AppendString appends a string to a byte slice without intermediate allocation.
func BytesToString ¶
BytesToString converts a byte slice to a string without allocation. The returned string shares memory with the byte slice. WARNING: Mutating the byte slice after conversion causes undefined behavior.
func BytesToStringCopy ¶
BytesToStringCopy converts a byte slice to a string with allocation. Use this when you need to store the string beyond the lifetime of the byte slice.
func EqualFoldASCII ¶
EqualFold reports whether s and t are equal under Unicode case-folding. This is a fast path for ASCII-only comparisons.
func GetSizeClass ¶
GetSizeClass retrieves a buffer from the default pool.
func GetSizeClassSlice ¶
GetSizeClassSlice retrieves a buffer slice from the default pool.
func PutSizeClass ¶
func PutSizeClass(buf *[]byte)
PutSizeClass returns a buffer to the default pool.
func PutSizeClassSlice ¶
func PutSizeClassSlice(buf []byte)
PutSizeClassSlice returns a slice to the default pool.
func ReleaseRequestArena ¶
func ReleaseRequestArena(a *RequestArena)
ReleaseRequestArena returns a RequestArena to the pool. All slices allocated from the arena are returned to their pools.
func StringToBytes ¶
StringToBytes converts a string to a byte slice without allocation. The returned slice shares memory with the string. WARNING: Mutating the returned slice causes undefined behavior (strings are immutable).
func StringToBytesCopy ¶
StringToBytesCopy converts a string to a byte slice with allocation. Use this when you need to mutate the byte slice.
Types ¶
type BufferPool ¶
type BufferPool struct {
// contains filtered or unexported fields
}
BufferPool manages byte buffers using sync.Pool for maximum performance. sync.Pool is significantly faster than custom Treiber stack implementations (4.6x single-threaded, 180x parallel according to benchmarks).
func (*BufferPool) Get ¶
func (p *BufferPool) Get(size int) *[]byte
Get retrieves a buffer of at least the specified size.
func (*BufferPool) ResetStats ¶
func (p *BufferPool) ResetStats()
ResetStats is a no-op (sync.Pool doesn't track stats).
func (*BufferPool) Stats ¶
func (p *BufferPool) Stats() BufferPoolStats
Stats returns pool statistics (placeholder for compatibility).
type BufferPoolStats ¶
BufferPoolStats tracks pool usage (no-op for sync.Pool based impl).
type BytesBufferPool ¶
type BytesBufferPool struct {
// contains filtered or unexported fields
}
BytesBufferPool manages sync.Pool for bytes.Buffer.
func NewBytesBufferPool ¶
func NewBytesBufferPool(initialSize int) *BytesBufferPool
NewBytesBufferPool creates a new bytes.Buffer pool.
func (*BytesBufferPool) Get ¶
func (p *BytesBufferPool) Get() *bytes.Buffer
Get retrieves a buffer from the pool.
func (*BytesBufferPool) Put ¶
func (p *BytesBufferPool) Put(buf *bytes.Buffer)
Put returns a buffer to the pool.
type ConnPool ¶
type ConnPool struct {
// contains filtered or unexported fields
}
ConnPool manages host-based connection pooling with LIFO strategy. LIFO (Last-In-First-Out) provides better CPU cache locality than FIFO because recently used connections are more likely to have warm caches.
func NewConnPool ¶
func NewConnPool(cfg PoolConfig) *ConnPool
NewConnPool creates a new connection pool with LIFO strategy.
func (*ConnPool) CloseConn ¶
func (p *ConnPool) CloseConn(mc *ManagedConn)
CloseConn marks a connection as unhealthy and closes it.
func (*ConnPool) GetConn ¶
GetConn retrieves or creates a connection for the host. Uses LIFO strategy to return most recently used connections first.
func (*ConnPool) ReturnConn ¶
func (p *ConnPool) ReturnConn(mc *ManagedConn)
ReturnConn returns a connection to the pool using LIFO strategy.
type Headers ¶
type Headers struct {
// contains filtered or unexported fields
}
Headers is a slice-based header storage that avoids map allocations. For typical HTTP requests (< 20 headers), slice iteration is faster than map lookup due to better cache locality and no hashing overhead.
type HeadersPool ¶
type HeadersPool struct {
// contains filtered or unexported fields
}
HeadersPool manages Headers object reuse.
func (*HeadersPool) Get ¶
func (p *HeadersPool) Get() *Headers
Get retrieves a Headers object from the pool.
func (*HeadersPool) Put ¶
func (p *HeadersPool) Put(h *Headers)
Put returns a Headers object to the pool.
type ManagedConn ¶
ManagedConn wraps a connection with metadata.
func (*ManagedConn) Close ¶
func (mc *ManagedConn) Close() error
Close returns the connection to the pool instead of closing it.
func (*ManagedConn) ForceClose ¶
func (mc *ManagedConn) ForceClose() error
ForceClose actually closes the underlying connection.
func (*ManagedConn) LocalAddr ¶
func (mc *ManagedConn) LocalAddr() net.Addr
LocalAddr returns the local address.
func (*ManagedConn) Read ¶
func (mc *ManagedConn) Read(b []byte) (n int, err error)
Read implements io.Reader for ManagedConn.
func (*ManagedConn) RemoteAddr ¶
func (mc *ManagedConn) RemoteAddr() net.Addr
RemoteAddr returns the remote address.
func (*ManagedConn) SetDeadline ¶
func (mc *ManagedConn) SetDeadline(t time.Time) error
SetDeadline sets the connection deadline.
func (*ManagedConn) SetReadDeadline ¶
func (mc *ManagedConn) SetReadDeadline(t time.Time) error
SetReadDeadline sets the read deadline.
func (*ManagedConn) SetWriteDeadline ¶
func (mc *ManagedConn) SetWriteDeadline(t time.Time) error
SetWriteDeadline sets the write deadline.
type PoolConfig ¶
type PoolConfig struct {
MaxConnsPerHost int
MaxTotalConns int
IdleTimeout time.Duration
HealthInterval time.Duration
DialFunc DialFunc
}
PoolConfig holds configuration for the connection pool.
func DefaultPoolConfig ¶
func DefaultPoolConfig() PoolConfig
DefaultPoolConfig returns sensible defaults for high-throughput use.
type ReaderPool ¶
type ReaderPool struct {
// contains filtered or unexported fields
}
ReaderPool manages bufio.Reader recycling.
func NewReaderPool ¶
func NewReaderPool(bufferSize int) *ReaderPool
NewReaderPool creates a new reader pool with the specified buffer size.
func (*ReaderPool) Get ¶
func (p *ReaderPool) Get(r io.Reader) *bufio.Reader
Get retrieves a reader from the pool and resets it with the given reader.
func (*ReaderPool) Put ¶
func (p *ReaderPool) Put(br *bufio.Reader)
Put returns a reader to the pool.
type RequestArena ¶
type RequestArena struct {
// contains filtered or unexported fields
}
RequestArena provides arena-like allocation semantics for per-request allocations. All allocations from a RequestArena can be freed together when Free() is called.
Note: Go's experimental arena package was removed. This implementation uses size-class pooling to provide similar benefits without true arena semantics. The API is designed to allow easy migration if arena-like functionality returns to Go in the future.
func AcquireRequestArena ¶
func AcquireRequestArena() *RequestArena
AcquireRequestArena gets a RequestArena from the pool.
func NewRequestArena ¶
func NewRequestArena() *RequestArena
NewRequestArena creates a new per-request allocation arena.
func (*RequestArena) Free ¶
func (a *RequestArena) Free()
Free returns all allocated slices to the pool. After calling Free(), the arena should not be used again.
func (*RequestArena) MakeSlice ¶
func (a *RequestArena) MakeSlice(size int) []byte
MakeSlice allocates a byte slice of the given size. The slice will be returned to the pool when Free() is called.
type RingBuffer ¶
type RingBuffer struct {
// contains filtered or unexported fields
}
RingBuffer is a lock-free ring buffer for streaming body data. It provides better cache locality and lower overhead than channel-based readers.
func (*RingBuffer) Close ¶
func (rb *RingBuffer) Close() error
Close signals that no more data will be written.
func (*RingBuffer) CloseWithError ¶
func (rb *RingBuffer) CloseWithError(err error) error
CloseWithError closes the buffer with a specific error.
func (*RingBuffer) Read ¶
func (rb *RingBuffer) Read(p []byte) (int, error)
Read reads data from the ring buffer. Blocks if buffer is empty (unless closed).
func (*RingBuffer) Release ¶
func (rb *RingBuffer) Release()
Release returns the buffer to its pool.
type RingBufferPool ¶
type RingBufferPool struct {
// contains filtered or unexported fields
}
RingBufferPool manages RingBuffer reuse.
func NewRingBufferPool ¶
func NewRingBufferPool(bufferSize int) *RingBufferPool
NewRingBufferPool creates a new ring buffer pool.
func (*RingBufferPool) Get ¶
func (p *RingBufferPool) Get() *RingBuffer
Get retrieves a ring buffer from the pool.
func (*RingBufferPool) Put ¶
func (p *RingBufferPool) Put(rb *RingBuffer)
Put returns a ring buffer to the pool.
type SizeClassPool ¶
type SizeClassPool struct {
// contains filtered or unexported fields
}
SizeClassPool provides granular pooling for variable-sized byte slices. Optimized for hot paths like HPACK encoding and frame serialization.
func NewSizeClassPool ¶
func NewSizeClassPool() *SizeClassPool
NewSizeClassPool creates a new size-class pool.
func (*SizeClassPool) Get ¶
func (p *SizeClassPool) Get(size int) *[]byte
Get retrieves a buffer of at least the specified size. Returns a pointer to a slice; caller should use (*buf)[:n] to set desired length.
func (*SizeClassPool) GetSlice ¶
func (p *SizeClassPool) GetSlice(size int) []byte
GetSlice retrieves a buffer and returns the underlying slice with requested length. This is a convenience method that avoids pointer dereferencing at the call site.
func (*SizeClassPool) GetWithLength ¶
func (p *SizeClassPool) GetWithLength(size int) *[]byte
GetWithLength retrieves a buffer and sets its length to the requested size.
func (*SizeClassPool) Put ¶
func (p *SizeClassPool) Put(buf *[]byte)
Put returns a buffer to the appropriate pool based on its capacity.
func (*SizeClassPool) PutSlice ¶
func (p *SizeClassPool) PutSlice(buf []byte)
PutSlice returns a slice to the pool. Note: Only works if the slice was originally obtained from this pool and hasn't been resliced beyond the original capacity.
type WorkerPool ¶
type WorkerPool struct {
// contains filtered or unexported fields
}
WorkerPool wraps ants.Pool for goroutine pooling. This provides a high-performance goroutine pool that:
- Reuses goroutines to reduce allocation and scheduling overhead
- Automatically scales based on load
- Cleans up idle workers to prevent resource waste
- Provides 2-6x better performance than unlimited goroutines
func GetDefaultPool ¶
func GetDefaultPool() *WorkerPool
GetDefaultPool returns the default global worker pool.
func NewWorkerPool ¶
func NewWorkerPool(cfg WorkerPoolConfig) (*WorkerPool, error)
NewWorkerPool creates a new goroutine pool using ants.
func (*WorkerPool) Capacity ¶
func (p *WorkerPool) Capacity() int
Capacity returns the maximum number of workers.
func (*WorkerPool) Close ¶
func (p *WorkerPool) Close()
Close is an alias for Release for API compatibility.
func (*WorkerPool) Free ¶
func (p *WorkerPool) Free() int
Free returns the number of available workers.
func (*WorkerPool) Go ¶
func (p *WorkerPool) Go(task func())
Go submits a task and panics if submission fails.
func (*WorkerPool) IsClosed ¶
func (p *WorkerPool) IsClosed() bool
IsClosed returns whether the pool is closed.
func (*WorkerPool) Release ¶
func (p *WorkerPool) Release()
Release closes the pool and releases all resources.
func (*WorkerPool) ReleaseTimeout ¶
func (p *WorkerPool) ReleaseTimeout(timeout time.Duration) error
ReleaseTimeout closes the pool with a timeout for pending tasks.
func (*WorkerPool) Running ¶
func (p *WorkerPool) Running() int
Running returns the number of running workers.
func (*WorkerPool) Submit ¶
func (p *WorkerPool) Submit(task func()) error
Submit submits a task to the pool. Returns error if the pool is closed or overloaded.
func (*WorkerPool) Tune ¶
func (p *WorkerPool) Tune(size int)
Tune dynamically adjusts the pool capacity.
func (*WorkerPool) Waiting ¶
func (p *WorkerPool) Waiting() int
Waiting returns the number of tasks waiting in queue.
type WorkerPoolConfig ¶
type WorkerPoolConfig struct {
// Capacity is the maximum number of workers.
// Default: 10000
Capacity int
// IdleTimeout is how long an idle worker stays alive.
// Workers idle longer than this are terminated.
// Default: 10 seconds
IdleTimeout time.Duration
// PreAlloc pre-allocates worker memory for better performance
// in high-capacity scenarios.
// Default: false
PreAlloc bool
// PanicHandler is called when a task panics.
// Default: nil (panics are logged but don't crash)
PanicHandler func(interface{})
}
WorkerPoolConfig configures the worker pool.
func DefaultWorkerPoolConfig ¶
func DefaultWorkerPoolConfig() WorkerPoolConfig
DefaultWorkerPoolConfig returns sensible defaults.
type WriterPool ¶
type WriterPool struct {
// contains filtered or unexported fields
}
WriterPool manages bufio.Writer recycling.
func NewWriterPool ¶
func NewWriterPool(bufferSize int) *WriterPool
NewWriterPool creates a new writer pool with the specified buffer size.
func (*WriterPool) Get ¶
func (p *WriterPool) Get(w io.Writer) *bufio.Writer
Get retrieves a writer from the pool and resets it with the given writer.
func (*WriterPool) Put ¶
func (p *WriterPool) Put(bw *bufio.Writer)
Put returns a writer to the pool after flushing.
Source Files