Core Components

Purpose and Scope

This document provides an overview of the fundamental building blocks that implement the object pooling mechanism in the hypervel/object-pool package. The core components handle object lifecycle management, storage, and configuration.

For information about managing multiple pools and factory patterns, see Pool Management. For automated recycling and cleanup strategies, see Object Recycling. For framework integration details, see Integration & Configuration.

---

Component Architecture

The core pooling system consists of four primary components that work together to provide efficient object reuse:

Sources: src/ObjectPool.php1-330 src/Channel.php1-79 src/SimpleObjectPool.php1-54 src/Contracts/ObjectPool.php1-61

---

Core Component Responsibilities

Component	File	Primary Responsibility
ObjectPool	src/ObjectPool.php	Abstract base class managing object lifecycle, creation timestamps, and pool statistics
Channel	src/Channel.php	Coroutine-safe storage that automatically switches between Hyperf\Engine\Channel and SplQueue
SimpleObjectPool	src/SimpleObjectPool.php	Concrete implementation using callback functions for object creation
PoolOption	src/PoolOption.php	Configuration value object holding pool parameters
ObjectPool (interface)	src/Contracts/ObjectPool.php	Contract defining the public API for pool implementations

Sources: src/ObjectPool.php22-330 src/Channel.php11-79 src/SimpleObjectPool.php9-54 src/Contracts/ObjectPool.php10-61

---

The ObjectPool Abstract Class

The ObjectPool abstract class serves as the foundation for all pool implementations. It manages the complete lifecycle of pooled objects from creation through retrieval, usage, and eventual destruction.

Key Properties

Sources: src/ObjectPool.php24-57

Core Methods

The ObjectPool class defines the following essential operations:

Method	Signature	Description
get()	public function get(): object	Retrieves an object from the pool, creating one if necessary or waiting if pool is exhausted
release()	public function release(object $object): void	Returns an object to the pool for reuse
flush()	public function flush(): void	Removes excess objects, reducing pool size to min_objects
flushOne()	public function flushOne(bool $force = false): void	Removes a single object if it exceeds lifetime or force is true
createObject()	abstract protected function createObject(): object	Abstract method that subclasses must implement to create new objects

Sources: src/ObjectPool.php77-222 src/Contracts/ObjectPool.php14-30

Object Lifecycle Management

The ObjectPool implements sophisticated lifecycle tracking:

1. Creation Tracking: Each object's creation time is stored in creationTimestamps using spl_object_hash() as the key src/ObjectPool.php207
2. Lifetime Validation: Before returning objects, exceedsMaxLifetime() checks if the object has exceeded its configured max_lifetime src/ObjectPool.php239-248
3. Automatic Destruction: Objects exceeding their lifetime are destroyed via destroyObject() and replaced with new instances src/ObjectPool.php86-90
4. Counter Management: The currentObjectNumber property tracks total objects and is incremented on creation, decremented on destruction src/ObjectPool.php205-262

Sources: src/ObjectPool.php199-265

---

The Channel Storage System

The Channel class provides a dual-mode storage mechanism that adapts to the execution context:

Sources: src/Channel.php11-79

Channel Operations

The Channel provides three primary operations that transparently delegate to the appropriate underlying storage:

Method	Coroutine Mode	Non-Coroutine Mode
push(object $data)	$this->channel->push($data)	$this->queue->push($data)
pop(float $timeout)	$this->channel->pop($timeout)	$this->queue->shift()
length()	$this->channel->getLength()	$this->queue->count()

Context Detection: The isCoroutine() method checks Coroutine::id() > 0 to determine execution context src/Channel.php75-78

Sources: src/Channel.php38-70

---

SimpleObjectPool Implementation

The SimpleObjectPool extends ObjectPool to provide a concrete implementation using callback-based object creation:

Sources: src/SimpleObjectPool.php9-54

Constructor Parameters

The SimpleObjectPool constructor requires:

__construct(
 protected ContainerInterface $container,
 callable $callback,
 array $config = []
)

• $container: PSR-11 container for dependency resolution src/SimpleObjectPool.php24
• $callback: Callable that returns a new object instance when invoked src/SimpleObjectPool.php16-28
• $config: Configuration array passed to parent ObjectPool constructor src/SimpleObjectPool.php26-30

Sources: src/SimpleObjectPool.php23-31

Object Creation Flow

When SimpleObjectPool::get() is called and a new object is needed:

1. ObjectPool::getObject() determines a new object is required src/ObjectPool.php204-209
2. SimpleObjectPool::createObject() is invoked src/SimpleObjectPool.php50-53
3. The stored callback is executed: return ($this->callback)(); src/SimpleObjectPool.php52
4. The returned object is tracked and added to the pool

Sources: src/SimpleObjectPool.php50-53 src/ObjectPool.php192-222

---

Pool Configuration

Pool behavior is controlled by the PoolOption value object, which encapsulates all configuration parameters. Configuration is initialized in the ObjectPool::initOption() method:

Sources: src/ObjectPool.php175-185

Configuration Parameters

Parameter	Type	Default	Description
min_objects	int	1	Minimum number of objects maintained in the pool
max_objects	int	10	Maximum number of objects the pool can create
wait_timeout	float	3.0	Seconds to wait for an available object before throwing exception
max_lifetime	float	60.0	Maximum lifetime of an object in seconds before forced recreation
recycle_ratio	float	0.2	Proportion of pool to recycle during cleanup (0.0-1.0)
recycle_strategy	string	TimeStrategy::class	Fully-qualified class name of the recycling strategy

For detailed information about configuration options and their effects, see Pool Configuration.

Sources: src/ObjectPool.php177-184

---

Component Interaction Flow

The following diagram illustrates how core components interact during a typical get/release cycle:

Sources: src/ObjectPool.php62-222 src/SimpleObjectPool.php23-53 src/Channel.php38-58

---

Object Pool Contract

The ObjectPool interface in src/Contracts/ObjectPool.php defines the public API that all pool implementations must provide:

Required Interface Methods

Sources: src/Contracts/ObjectPool.php10-61

The interface ensures that different pool implementations can be used interchangeably throughout the system, supporting the strategy pattern used in pool management.

---

Thread Safety and Coroutine Support

The core components are designed to work correctly in both traditional synchronous PHP and Hyperf's coroutine-based execution model:

Channel Adaptation Strategy

Sources: src/Channel.php40-78

This dual-mode design allows the object pool to:

• Function correctly in traditional PHP environments without coroutine support
• Leverage Hyperf's coroutine capabilities when available for non-blocking I/O
• Maintain consistent API regardless of execution context

Sources: src/Channel.php11-79