Object Pool Pattern Generator

Creates Object Pool pattern infrastructure for managing reusable expensive objects.

When to Use

Scenario	Example
Expensive creation	Database connections
Limited resources	HTTP client handles
Connection reuse	Socket connections
Memory management	Large object caching

Component Characteristics

PoolInterface

• Acquire/release semantics
• Pool lifecycle management
• Capacity configuration

Pool Implementation

• Manages available objects
• Creates on demand
• Recycles returned objects

Poolable Objects

• Resettable state
• Validate before reuse
• Track usage metrics

---

Generation Process

Step 1: Generate Core Pool Components

Path: src/Infrastructure/Pool/

1. PoolInterface.php — Generic pool contract with acquire/release
2. PoolConfig.php — Configuration value object (min/max size, timeouts)
3. PoolableInterface.php — Contract for poolable objects (reset, isValid, close)
4. ObjectPool.php — Generic pool implementation
5. PooledObject.php — Wrapper tracking usage metrics
6. PoolExhaustedException.php — Exception for exhausted pool
7. InvalidPoolObjectException.php — Exception for invalid objects

Step 2: Generate Specialized Pool (if needed)

Path: src/Infrastructure/{Domain}/

1. {Type}Pool.php — Specialized pool (ConnectionPool, HttpClientPool)
2. Poolable{Type}.php — Poolable implementation for specific resource

Step 3: Generate Tests

Path: tests/Unit/Infrastructure/Pool/

1. ObjectPoolTest.php — Core pool functionality tests
2. {Type}PoolTest.php — Specialized pool tests

---

File Placement

Component	Path
Pool Interface	src/Infrastructure/Pool/
Pool Implementation	src/Infrastructure/Pool/
Specialized Pools	src/Infrastructure/{Domain}/
Unit Tests	tests/Unit/Infrastructure/Pool/

---

Naming Conventions

Component	Pattern	Example
Interface	PoolInterface	PoolInterface
Implementation	ObjectPool	ObjectPool
Poolable Interface	PoolableInterface	PoolableInterface
Config	PoolConfig	PoolConfig
Wrapper	PooledObject	PooledObject
Specialized Pool	{Type}Pool	ConnectionPool
Test	{ClassName}Test	ObjectPoolTest

---

Quick Template Reference

PoolInterface

/**
 * @template T
 */
interface PoolInterface
{
    /** @return T */
    public function acquire(): mixed;
    /** @param T $object */
    public function release(mixed $object): void;
    public function getAvailableCount(): int;
    public function getActiveCount(): int;
    public function getMaxSize(): int;
    public function clear(): void;
}

PoolableInterface

interface PoolableInterface
{
    public function reset(): void;
    public function isValid(): bool;
    public function close(): void;
}

PoolConfig

final readonly class PoolConfig
{
    public function __construct(
        public int $minSize = 0,
        public int $maxSize = 10,
        public int $maxWaitTimeMs = 5000,
        public int $idleTimeoutSeconds = 300,
        public bool $validateOnAcquire = true,
        public bool $validateOnRelease = false
    );

    public static function default(): self;
    public static function forDatabase(): self;
    public static function forHttpClients(): self;
}

---

Usage Example

// Create pool
$pool = new ObjectPool(
    name: 'database',
    factory: fn() => $connectionFactory->create(),
    config: PoolConfig::forDatabase(),
    logger: $logger
);

// Acquire and release
$connection = $pool->acquire();
try {
    $result = $connection->query('SELECT ...');
} finally {
    $pool->release($connection);
}

// Or use helper
$result = $connectionPool->execute(fn($conn) => $conn->query('SELECT ...'));

---

Anti-patterns to Avoid

Anti-pattern	Problem	Solution
No Validation	Returning broken objects	Validate on acquire
No Reset	State leaks between uses	Call reset() on release
No Timeout	Infinite wait	Set maxWaitTime
Unbounded Pool	Memory exhaustion	Set maxSize
Not Releasing	Pool exhaustion	Use try/finally
Wrong Scope	Per-request pools	Use singleton/shared pool

---

References

For complete PHP templates and examples, see:

• references/templates.md — All component templates
• references/examples.md — ConnectionPool, HttpClientPool examples and tests