Connection Pooling

Purpose and Scope

This page documents the RedisPool class, which provides custom connection pooling functionality for the Hypervel Redis library. The pool extends Hyperf's native Redis pool to create RedisConnection instances with Laravel-style API transformations instead of Hyperf's default connections.

For information about how pools are created and managed by the factory, see Redis Factory. For details about the connection class itself and its transformation capabilities, see Laravel-Style Redis Connection.

Sources: src/RedisPool.php1-16

---

Overview

The RedisPool class serves as a critical integration point between Hyperf's connection pooling system and Hypervel's Laravel-style Redis API. By extending Hyperf\Redis\Pool\RedisPool and overriding the connection creation method, it ensures that all connections retrieved from the pool are instances of RedisConnection with transformation capabilities enabled.

System Position

Diagram: RedisPool in System Architecture

The diagram illustrates how RedisPool intercepts the default connection creation process. While Hyperf's native pool would create standard Hyperf\Redis\RedisConnection instances, the custom pool creates Hypervel\Redis\RedisConnection instances that provide Laravel-style API transformations.

Sources: src/RedisPool.php1-16 src/RedisConnection.php260-261

---

RedisPool Class Implementation

The RedisPool class is remarkably minimal, consisting of only a single method override. This simplicity is by design—it leverages all of Hyperf's existing pooling infrastructure while changing only the connection creation behavior.

Class Definition

Aspect	Details
Namespace	Hypervel\Redis
Parent Class	Hyperf\Redis\Pool\RedisPool
Methods	createConnection() (override)
Properties	Inherits all from parent

Key Method: createConnection()

Diagram: Connection Creation Flow

The createConnection() method src/RedisPool.php12-15 is invoked by Hyperf's pooling system whenever a new connection needs to be instantiated. It receives three parameters from the parent pool infrastructure:

Parameter	Type	Source	Purpose
$this->container	ContainerInterface	Dependency injection container	Provides access to framework services
$this->pool	RedisPool	Self-reference	Allows connection to release itself back to pool
$this->config	PoolConfig	Pool configuration	Contains Redis server settings, pool size, etc.

Sources: src/RedisPool.php12-15 src/RedisConnection.php260

---

Connection Creation Process

The connection creation process follows a specific sequence that integrates with Hyperf's connection pool lifecycle.

Creation Sequence

Diagram: Connection Instantiation Sequence

Connection State Initialization

When a RedisConnection is created, it initializes with the following default state:

Property	Initial Value	Purpose
shouldTransform	false	Transformation disabled by default src/RedisConnection.php265
connection	phpredis instance	Native Redis connection (inherited)
pool	RedisPool reference	Used for releasing connection back to pool

The shouldTransform flag is set to false initially and gets enabled later by the Redis class when it retrieves a connection for Laravel-style operations.

Sources: src/RedisPool.php12-15 src/RedisConnection.php260-265

---

Connection Lifecycle in Pool

The pool manages connections through a borrow-and-return lifecycle, ensuring efficient resource utilization in a coroutine environment.

Borrow and Return Flow

Diagram: Connection State Machine

Key Lifecycle Methods

The connection lifecycle involves several methods that interact with the pool:

Method	Location	Called By	Purpose
get()	Inherited from HyperfRedisPool	Redis class	Borrow connection from pool
release()	RedisConnection src/RedisConnection.php289-294	Redis class or connection itself	Return connection to pool
shouldTransform()	RedisConnection src/RedisConnection.php299-304	Redis class	Enable/disable transformations

Release Process

When a connection is released back to the pool src/RedisConnection.php289-294 it performs cleanup:

1. Reset transformation flag: Sets shouldTransform = false to ensure the next borrower gets a clean state
2. Call parent release: Invokes parent::release() to return the connection to Hyperf's pool

This two-step process ensures that transformation state doesn't leak between different uses of the same connection instance.

Sources: src/RedisConnection.php289-294 src/RedisConnection.php299-304

---

Multiple Pool Architecture

The system supports multiple named Redis pools, each managed by its own RedisPool instance. This enables applications to maintain separate connection pools for different purposes (e.g., caching, sessions, primary database).

Multi-Pool Structure

Diagram: Multiple Pool Configuration

Pool Configuration

Each pool is configured independently in the config/autoload/redis.php configuration file. The configuration structure looks like:

Pool Instantiation

The dependency injection container creates separate RedisPool instances for each configured pool name. The pool name is used as a key in the container, allowing the RedisFactory to retrieve the appropriate pool for a given connection request.

Sources: src/RedisPool.php1-16

---

Integration with Hyperf Framework

The RedisPool class integrates seamlessly with Hyperf's connection pooling infrastructure by leveraging the framework's built-in mechanisms.

Integration Points

Diagram: Framework Integration Points

Configuration Provider Override

The ConfigProvider class registers the custom RedisPool as a replacement for Hyperf's default pool through the dependencies configuration array. This override ensures that whenever the framework needs to create a Redis pool, it uses Hypervel\Redis\RedisPool instead of Hyperf\Redis\Pool\RedisPool.

Inherited Pooling Features

By extending HyperfRedisPool, the custom pool inherits all standard pooling features:

Feature	Source	Description
Min/Max connections	Hyperf pool config	Configurable pool size bounds
Wait timeout	Hyperf pool config	Max time to wait for available connection
Connection validation	HyperfRedisPool	Automatic connection health checks
Coroutine safety	Hyperf pooling system	Thread-safe connection management
Connection recycling	Hyperf pooling system	Automatic connection lifecycle management
Lazy initialization	Hyperf pooling system	Connections created on-demand

The only aspect that changes is the type of connection created—everything else remains consistent with Hyperf's pooling behavior.

Sources: src/RedisPool.php1-16 src/RedisPool.php10

---

Connection Pool Size and Configuration

The pool size and behavior are controlled through Hyperf's standard pool configuration, which each RedisPool instance reads from its $this->config property.

Configuration Parameters

Parameter	Type	Default	Purpose
min_connections	int	1	Minimum connections maintained in pool
max_connections	int	10	Maximum connections allowed in pool
connect_timeout	float	10.0	Timeout for establishing new connection
wait_timeout	float	3.0	Max wait time when pool is exhausted
heartbeat	int	-1	Connection heartbeat interval (seconds)
max_idle_time	float	60.0	Max idle time before connection is closed

Pool Behavior Under Load

Diagram: Pool Behavior Under Different Load Conditions

When the pool is exhausted (all connections borrowed and max_connections reached), subsequent borrow requests will wait up to wait_timeout seconds for a connection to become available. If no connection becomes available within this time, Hyperf throws a ConnectionException.

Sources: src/RedisPool.php14

---

Connection Validation and Health Checks

The RedisPool inherits connection validation logic from HyperfRedisPool, which performs automatic health checks to ensure connections remain viable.

Validation Process

Diagram: Connection Validation Flow

Heartbeat Mechanism

If configured, the pool sends periodic heartbeat commands to maintain connection validity:

• Heartbeat Command: The pool executes a lightweight command (typically PING) to verify the connection is responsive
• Frequency: Controlled by the heartbeat configuration parameter (in seconds)
• Purpose: Prevents connections from being closed by intermediate proxies or firewalls due to inactivity

Sources: src/RedisPool.php10

---

Summary

The RedisPool class provides a minimal but critical override to Hyperf's connection pooling system:

Key Characteristics

Aspect	Implementation
Lines of Code	7 (excluding namespace and use statements)
Complexity	Minimal—single method override
Purpose	Create RedisConnection instances instead of default connections
Integration	Seamless with Hyperf's pooling infrastructure
Inheritance	All pooling features from HyperfRedisPool

Design Philosophy

The design follows the principle of minimal intervention: change only what's necessary (connection type) while preserving all of Hyperf's robust pooling capabilities. This approach ensures:

• Reliability: Leverages battle-tested pooling logic from Hyperf
• Maintainability: Minimal custom code reduces maintenance burden
• Compatibility: Works with all Hyperf pooling features and configurations
• Flexibility: Supports multiple pools with different configurations

Sources: src/RedisPool.php1-16