SimpleObjectPool

Purpose and Scope

SimpleObjectPool is a concrete implementation of the abstract ObjectPool class that uses a callback function to create pooled objects. It provides a flexible, closure-based approach to object instantiation, allowing users to define custom object creation logic without subclassing.

For information about the abstract ObjectPool base class and its lifecycle management capabilities, see Object Pool Implementation. For details on managing multiple pools via the factory pattern, see Pool Manager.

Sources: src/SimpleObjectPool.php1-54

---

Class Overview

SimpleObjectPool extends ObjectPool and implements its abstract createObject() method using a user-provided callback function. This design eliminates the need to create custom pool subclasses for simple object creation scenarios.

Inheritance Hierarchy

Sources: src/ObjectPool.php22 src/SimpleObjectPool.php9

Key Properties

Property	Type	Visibility	Description
$callback	callable	protected	Function invoked to create new pooled objects
$container	ContainerInterface	protected	Dependency injection container (inherited)
$channel	Channel	protected	Storage for available objects (inherited)
$option	PoolOption	protected	Pool configuration (inherited)
$currentObjectNumber	int	protected	Count of managed objects (inherited)

Sources: src/SimpleObjectPool.php12-16 src/ObjectPool.php24-42

---

Constructor and Initialization

The SimpleObjectPool constructor requires three parameters: a PSR-11 container, a callback function, and an optional configuration array.

Constructor Signature

Parameters:

• $container: PSR-11 container for dependency resolution
• $callback: Callable that returns a new object instance when invoked
• $config: Optional array of configuration parameters (see Pool Configuration)

Initialization Sequence

1. Store the callback function in $this->callback (src/SimpleObjectPool.php28)
2. Invoke parent constructor to initialize inherited properties (src/SimpleObjectPool.php30)
3. Parent creates PoolOption from config array (src/ObjectPool.php66)
4. Parent initializes Channel with maxObjects capacity (src/ObjectPool.php69)

Sources: src/SimpleObjectPool.php23-31 src/ObjectPool.php62-70

---

Object Creation Mechanism

The callback-based creation mechanism is the defining feature of SimpleObjectPool. When the pool needs a new object, it invokes the stored callback rather than requiring a subclass to override createObject().

Creation Flow

Implementation Details

The createObject() method implementation is minimal, delegating all logic to the callback:

This method is called by the parent's getObject() method when:

• The Channel is empty AND
• currentObjectNumber is below maxObjects limit

Key Characteristics:

• Synchronous execution: Callback executes in the current coroutine context
• Type safety: Callback must return an object (enforced by parent's type hints)
• Error handling: Exceptions thrown by callback propagate to caller and decrement currentObjectNumber (src/ObjectPool.php211-213)
• Timestamp tracking: Object creation time is recorded automatically by parent (src/ObjectPool.php207)

Sources: src/SimpleObjectPool.php45-53 src/ObjectPool.php199-222

---

Callback Management

The callback can be dynamically updated after pool creation using the setCallback() method. This enables runtime reconfiguration of object creation logic.

Callback Update Method

Fluent Interface Pattern

The method returns static (the current instance), enabling method chaining:

Considerations

Aspect	Behavior
Existing objects	Remain in pool unchanged; new callback only affects future object creation
Thread safety	No synchronization; callback updates in coroutine environments should be done during initialization
Type compatibility	New callback must return objects compatible with pool's generic type parameter
Validation	No runtime validation that callback returns objects (type error will occur on next creation)

Sources: src/SimpleObjectPool.php34-43

---

Integration with ObjectPool Lifecycle

SimpleObjectPool inherits the complete object lifecycle management from ObjectPool. The callback is invoked as part of this lifecycle at specific points.

Complete Lifecycle Diagram

Lifecycle Methods Interaction

ObjectPool Method	Impact on Callback
get()	May trigger callback if new object needed (src/ObjectPool.php77-93)
release()	No callback invocation; object returned to Channel (src/ObjectPool.php98-101)
flush()	Destroys excess objects; callback triggered when replacements needed (src/ObjectPool.php106-122)
flushOne()	May destroy one object; callback triggered on next get() (src/ObjectPool.php127-146)

Sources: src/ObjectPool.php77-146 src/SimpleObjectPool.php45-53

---

Usage Patterns

Basic Usage with PoolManager

The most common pattern is creating a SimpleObjectPool via PoolManager:

Callback Requirements

The callback must satisfy these requirements:

Requirement	Description	Example
Return type	Must return an object	fn() => new MyClass()
Idempotent	Should create independent instances	Avoid fn() => self::$singleton
Exception safe	Should handle initialization errors	Wrap in try-catch if needed
Stateless	Should not rely on pool state	Avoid referencing $this from outside scope

Comparison with Custom Pool Subclasses

When to use SimpleObjectPool:

• Simple object creation logic
• No shared state across creations
• Callback can capture necessary dependencies via closure

When to extend ObjectPool directly:

• Complex initialization requiring multiple steps
• Need to store additional state in pool instance
• Object creation depends on pool's internal state
• Custom lifecycle hooks beyond callback

Sources: src/SimpleObjectPool.php1-54 src/ObjectPool.php192

---

Code Entity Mapping

File Structure

src/
└── SimpleObjectPool.php # 54 lines
 ├── Property: $callback # Line 16
 ├── Method: __construct() # Lines 23-31
 ├── Method: setCallback() # Lines 38-43
 └── Method: createObject() # Lines 50-53

Class Relationship Map

Sources: src/SimpleObjectPool.php1-54 src/ObjectPool.php1-330