Pool Management

Purpose and Scope

This document provides an overview of the components responsible for creating, managing, and interacting with multiple object pools in the hypervel/object-pool package. Pool management encompasses three primary systems:

1. PoolManager - Factory and registry for creating named pools
2. PoolProxy - Transparent method interception for automatic lifecycle management
3. HasPoolProxy - Trait for managing multiple pool proxies with release callbacks

For detailed implementation of the base pool abstraction, see Object Pool Implementation. For configuration options that control pool behavior, see Pool Configuration.

Overview of Management Components

The pool management layer sits between client code and the core pooling system, providing convenient abstractions for working with object pools. The following table summarizes the three main components:

Component	File	Primary Responsibility	Key Methods
PoolManager	src/PoolManager.php	Factory pattern for creating and registering named pools	create(), get(), has(), remove()
PoolProxy	src/PoolProxy.php	Transparent method interception with automatic get/release	__call(), __construct()
HasPoolProxy	src/Traits/HasPoolProxy.php	Multi-proxy management with release callbacks	createPoolProxy(), setReleaseCallback(), addPoolable()

Sources: src/PoolManager.php1-116 src/PoolProxy.php1-67 src/Traits/HasPoolProxy.php1-104

Component Architecture

The following diagram shows how the management components relate to each other and to the core pooling system:

Diagram: Pool Management Component Architecture

Sources: src/PoolManager.php12-27 src/PoolProxy.php12-40 src/Traits/HasPoolProxy.php11-40 src/Contracts/Factory.php7-13

PoolManager: Factory and Registry

PoolManager implements the Factory pattern, serving dual roles as both a factory for creating pools and a registry for storing them by name. It implements the Factory interface defined in src/Contracts/Factory.php

Key Responsibilities

1. Pool Creation: Instantiates SimpleObjectPool instances with given resolver callbacks and options src/PoolManager.php44-56
2. Pool Registration: Stores pools in a name-keyed array src/PoolManager.php19
3. Pool Retrieval: Provides access to registered pools by name src/PoolManager.php32-38
4. Pool Lifecycle: Supports pool removal and bulk operations src/PoolManager.php100-115

Pool Naming Convention

Pool names must be unique within a PoolManager instance. When creating a pool, the manager throws a RuntimeException if the name already exists src/PoolManager.php46-48 The HasPoolProxy trait uses a convention of concatenating the host class name with the driver name: {ClassName}:{driver} src/Traits/HasPoolProxy.php35

Registry Operations

The following table shows the registry operations provided by PoolManager:

Method	Parameters	Purpose	Error Handling
create()	$name, $callback, $options	Create and register new pool	Throws if name exists
get()	$name	Retrieve registered pool	Throws if name not found
has()	$name	Check pool existence	Returns boolean
set()	$name, $pool	Manually register pool	Overwrites if exists
remove()	$name	Unregister pool	Silent if not found
flush()	None	Clear all pools	Always succeeds

Sources: src/PoolManager.php30-115 src/Contracts/Factory.php8-32

PoolProxy: Transparent Method Interception

PoolProxy implements the Proxy design pattern to provide transparent object lifecycle management. When client code calls methods on the proxy, it automatically handles object acquisition, method execution, cleanup, and release.

Proxy Mechanism

Diagram: PoolProxy Method Interception Flow

The __call() magic method src/PoolProxy.php53-65 implements this flow:

1. Acquire: Get object from pool via $this->pool->get() src/PoolProxy.php55
2. Execute: Call requested method on the pooled object src/PoolProxy.php58
3. Cleanup: Invoke releaseCallback if configured src/PoolProxy.php60-62
4. Release: Return object to pool via $this->pool->release() src/PoolProxy.php63

The try-finally block ensures objects are always released, even if the method call throws an exception src/PoolProxy.php57-64

Construction and Initialization

PoolProxy accepts four constructor parameters src/PoolProxy.php27-32:

Parameter	Type	Purpose
$name	string	Unique identifier for the pool
$resolver	Closure	Callback to create new objects
$options	array	Configuration passed to pool
$releaseCallback	?Closure	Optional cleanup before release

During construction, the proxy retrieves PoolFactory from the container and calls create() to instantiate the underlying pool src/PoolProxy.php33-39

Sources: src/PoolProxy.php12-66

HasPoolProxy: Multi-Pool Management

The HasPoolProxy trait enables a single host class to manage multiple pool proxies, each with its own configuration and release callback. This is particularly useful for classes that need to pool different types of resources (e.g., database connections, Redis clients, HTTP clients).

Trait Components

Diagram: HasPoolProxy Trait Structure

Sources: src/Traits/HasPoolProxy.php11-104

Pool Proxy Creation

The createPoolProxy() method src/Traits/HasPoolProxy.php21-40 constructs a PoolProxy instance with the following behavior:

1. Proxy Class Resolution: Uses $this->poolProxyClass if defined, otherwise defaults to PoolProxy::class src/Traits/HasPoolProxy.php23-28
2. Validation: Ensures the proxy class extends PoolProxy src/Traits/HasPoolProxy.php30-32
3. Name Generation: Combines host class name with driver identifier src/Traits/HasPoolProxy.php35
4. Callback Association: Retrieves the driver-specific release callback src/Traits/HasPoolProxy.php38

Release Callback Management

Release callbacks provide per-driver cleanup logic that executes before objects return to pools. The trait maintains a driver-keyed array of callbacks src/Traits/HasPoolProxy.php16:

Method	Purpose	Example Use Case
setReleaseCallback($driver, $callback)	Register cleanup for specific driver	Reset transaction state on database connections
getReleaseCallback($driver)	Retrieve callback for driver	Internal use by createPoolProxy()

Poolables List Management

The poolables array tracks which drivers should use object pooling. This allows selective pooling in classes that support both pooled and non-pooled drivers:

Method	Operation	Return Type
addPoolable($driver)	Add to list (idempotent)	static
removePoolable($driver)	Remove from list (safe if not present)	static
getPoolables()	Retrieve entire list	array
setPoolables(array $poolables)	Replace list	static

Sources: src/Traits/HasPoolProxy.php44-103

Integration Patterns

Pattern 1: Direct PoolManager Usage

Client code can directly use PoolManager to create and retrieve pools:

Sources: src/PoolManager.php44-56 src/Contracts/Factory.php16-17

Pattern 2: PoolProxy for Transparent Access

PoolProxy eliminates manual get()/release() calls:

Sources: src/PoolProxy.php27-65

Pattern 3: HasPoolProxy for Multi-Pool Management

Classes managing multiple resource types use the trait:

Sources: src/Traits/HasPoolProxy.php21-40

Pool Identification and Namespacing

Pool names serve as unique identifiers in the PoolManager registry. The system uses different naming strategies:

Context	Naming Pattern	Example	Source
Direct creation	User-defined string	"my-database-pool"	src/PoolManager.php44
PoolProxy constructor	User-defined string	"redis-connections"	src/PoolProxy.php28
HasPoolProxy trait	{ClassName}:{driver}	"App\Database:mysql"	src/Traits/HasPoolProxy.php35

The HasPoolProxy namespacing convention prevents naming collisions when multiple classes use the trait, as each class generates distinct pool names.

Sources: src/PoolManager.php32-48 src/Traits/HasPoolProxy.php35

Error Handling

The management layer enforces strict error handling:

PoolManager Errors

Condition	Method	Exception Type	Message Pattern
Pool already exists	create()	RuntimeException	"The pool name \{$name}` already exists."`
Pool not found	get()	RuntimeException	"The pool name \{$name}` does not exist."`

PoolProxy Errors

Condition	Method	Exception Type	Message Pattern
Invalid proxy class	createPoolProxy()	InvalidArgumentException	"The pool proxy class must be an instance of {PoolProxy::class}"

Sources: src/PoolManager.php35-48 src/Traits/HasPoolProxy.php30-32

Summary

The pool management layer provides three complementary approaches for working with object pools:

1. PoolManager: Low-level factory and registry for explicit pool control
2. PoolProxy: High-level abstraction for transparent lifecycle management
3. HasPoolProxy: Multi-pool management for complex resource scenarios

For detailed information on each component, see:

• Pool Manager for factory pattern details
• Pool Proxy for transparent proxying
• HasPoolProxy Trait for trait usage patterns

Sources: src/PoolManager.php1-116 src/PoolProxy.php1-67 src/Traits/HasPoolProxy.php1-104 src/Contracts/Factory.php1-34