Pool Configuration

Purpose and Scope

This document describes the PoolOption class and all configuration parameters available for controlling object pool behavior. It covers parameter defaults, validation constraints, and how configuration affects pool operations.

For information about how pools use this configuration during object lifecycle management, see Object Pool Implementation. For details on how recycling strategies interpret configuration, see Recycle Strategies.

---

Configuration Overview

The PoolOption class encapsulates all configuration parameters that control pool behavior. Each pool instance maintains its own configuration object, allowing different pools to operate with different settings.

Sources: src/PoolOption.php9-29 src/ObjectPool.php175-185

---

Configuration Parameters

Object Count Limits

These parameters control the minimum and maximum number of objects that the pool manages.

Parameter	Type	Default	Description
minObjects	int	1	Minimum number of objects to maintain in the pool
maxObjects	int	10	Maximum number of objects that can exist in the pool

minObjects

The minimum object count determines the floor for pool operations. When recycling occurs via flush() or flushOne(), the pool will never destroy objects if doing so would reduce the count below minObjects.

Getter: getMinObjects()
Setter: setMinObjects(int $minObjects)

Usage locations:

• src/ObjectPool.php113 - Checked during flush() operation
• src/ObjectPool.php129 - Checked during flushOne() operation

maxObjects

The maximum object count sets the ceiling for object creation. When get() is called and no objects are available in the channel, the pool will only create a new object if currentObjectNumber < maxObjects. Otherwise, the pool waits for an object to be released.

Getter: getMaxObjects()
Setter: setMaxObjects(int $maxObjects)

Usage locations:

• src/ObjectPool.php69 - Used to initialize channel size
• src/ObjectPool.php204 - Checked before creating new objects

Sources: src/PoolOption.php32-65 src/ObjectPool.php69 src/ObjectPool.php113 src/ObjectPool.php129 src/ObjectPool.php204

---

Timeout Configuration

waitTimeout

The timeout in seconds to wait when attempting to retrieve an object from an empty pool. If no object becomes available within this time, a RuntimeException is thrown.

Parameter	Type	Default	Unit	Description
waitTimeout	float	3.0	seconds	Maximum time to wait for an available object

Getter: getWaitTimeout()
Setter: setWaitTimeout(float $waitTimeout)

Behavior:

• If waitTimeout elapses without an object becoming available, the pool throws: RuntimeException('Object pool exhausted. Cannot create new object before wait_timeout.')
• The timeout applies only when the pool is at maximum capacity and all objects are in use

Usage location: src/ObjectPool.php216

Sources: src/PoolOption.php67-83 src/ObjectPool.php216-219

---

Object Lifetime Management

maxLifetime

The maximum lifetime in seconds for an object in the pool. Objects exceeding this age are automatically destroyed and replaced when retrieved via get().

Parameter	Type	Default	Unit	Description
maxLifetime	float	60.0	seconds	Maximum age of an object before automatic replacement

Getter: getMaxLifetime()
Setter: setMaxLifetime(float $maxLifetime)

Behavior:

• When maxLifetime is 0 or falsy, lifetime checking is disabled
• Object age is tracked using microsecond-precision timestamps in ObjectPool::$creationTimestamps
• Age is calculated as: microtime(true) - creationTimestamp
• Objects are checked for age violations in:
  • ObjectPool::get() - src/ObjectPool.php81-92
  • ObjectPool::flushOne() - src/ObjectPool.php139

Sources: src/PoolOption.php85-101 src/ObjectPool.php81-92 src/ObjectPool.php239-248

---

Recycling Configuration

recycleRatio

The ratio of objects to recycle when a recycling operation occurs. This value is used by recycling strategies to determine how aggressively to reduce pool size.

Parameter	Type	Default	Range	Description
recycleRatio	float	0.2	0.0 - 1.0	Proportion of objects to recycle per operation

Getter: getRecycleRatio()
Setter: setRecycleRatio(float $recycleRatio)

Example calculations:

• If pool has 10 objects and recycleRatio = 0.2, up to 2 objects may be recycled
• If pool has 5 objects and recycleRatio = 0.5, up to 2-3 objects may be recycled
• Actual recycling behavior depends on the RecycleStrategy implementation

Sources: src/PoolOption.php122-137

---

recycleStrategy

The fully-qualified class name of the RecycleStrategy implementation to use for this pool. The strategy determines when and how recycling occurs.

Parameter	Type	Default	Description
recycleStrategy	string	TimeStrategy::class	Class name of recycle strategy

Getter: getStrategy()
Setter: setStrategy(?string $strategy)

Default strategy: Hypervel\ObjectPool\Strategies\TimeStrategy

Usage:

• The strategy class is instantiated lazily via dependency injection when first accessed
• Retrieved through ObjectPool::getRecycleStrategy() at src/ObjectPool.php292-300
• The recycler uses the strategy to determine when to call flush() or flushOne()

Sources: src/PoolOption.php103-119 src/ObjectPool.php292-311

---

Configuration Initialization

Array-Based Configuration

Pools accept configuration as an associative array with snake_case keys. This format is typically provided by Hyperf's configuration system or directly in code.

Key transformation:

• Array keys use snake_case: min_objects, max_objects, etc.
• Constructor parameters use camelCase: minObjects, maxObjects, etc.
• Performed at src/ObjectPool.php175-185

Sources: src/ObjectPool.php175-185

---

Constructor Signature

The PoolOption constructor accepts all parameters with defaults:

All parameters are optional; omitted values use the defaults shown above.

Sources: src/PoolOption.php21-29

---

Runtime Configuration Access

Retrieving Configuration

The pool's configuration object can be accessed via ObjectPool::getOption():

Source: src/ObjectPool.php159-162

---

Modifying Configuration

All configuration parameters have setter methods that allow runtime modification. Setters return $this for method chaining:

Important considerations:

• Changing maxObjects does not resize the internal Channel (which is created with the initial maxObjects value)
• Changing minObjects affects future recycling operations but does not immediately adjust the current object count
• Changing maxLifetime affects only subsequent get() calls; existing objects retain their creation timestamps

Sources: src/PoolOption.php42-137

---

Configuration Reference Table

Parameter	Type	Default	Array Key	Affects
minObjects	int	1	min_objects	Minimum pool size, recycling floor
maxObjects	int	10	max_objects	Maximum pool size, channel capacity
waitTimeout	float	3.0	wait_timeout	Timeout when pool exhausted
maxLifetime	float	60.0	max_lifetime	Object age before replacement
recycleRatio	float	0.2	recycle_ratio	Recycling aggressiveness
recycleStrategy	string	TimeStrategy::class	recycle_strategy	Recycling timing logic

Sources: src/PoolOption.php21-29 src/ObjectPool.php175-185

---

Configuration Examples

Example 1: High-Performance Pool

Configuration optimized for high-throughput scenarios with many concurrent requests:

Characteristics:

• Large pool size (10-100 objects)
• Short wait timeout for fast failure
• Long lifetime (5 minutes) to reduce churn
• Low recycle ratio for stability

---

Example 2: Resource-Constrained Pool

Configuration for environments with limited resources:

Characteristics:

• Small pool size (1-5 objects)
• Long wait timeout for patience
• Short lifetime to detect stale connections
• High recycle ratio for aggressive cleanup

---

Example 3: Custom Recycling Strategy

Configuration with a custom recycling implementation:

Note: Custom strategies must implement Hypervel\ObjectPool\Contracts\RecycleStrategy.

Sources: src/ObjectPool.php175-185 src/PoolOption.php21-29