Object Recycler

The Object Recycler is an automated scheduler that periodically executes recycling operations on managed object pools. It iterates through all registered pools at configurable intervals and applies their recycling strategies to maintain pool health by removing stale or expired objects.

For information about the recycling strategies themselves, see Recycle Strategies. For details on framework integration and how the recycler is initialized, see Framework Integration.

---

Purpose and Responsibilities

The ObjectRecycler class serves as the central coordinator for automated pool maintenance. Its primary responsibilities include:

• Periodic Execution: Schedules recurring recycling operations using Hyperf's Timer
• Strategy Application: Delegates recycling decisions to each pool's RecycleStrategy
• Pool Iteration: Queries the PoolManager to access all registered pools
• Lifecycle Control: Provides start/stop methods for managing the recycling process
• Timestamp Tracking: Retrieves last recycling timestamps from individual pools

Sources: src/ObjectRecycler.php1-134 src/Contracts/Recycler.php1-54

---

Architecture Overview

Diagram: ObjectRecycler Component Architecture

This diagram shows how ObjectRecycler integrates with Hyperf's event system, timer infrastructure, and the pool management layer.

Sources: src/ObjectRecycler.php13-134 src/Listeners/StartRecycler.php12-31

---

Core Components

Recycler Interface

The Recycler contract defines the complete API for recycling schedulers:

Method	Return Type	Purpose
getInterval()	float	Returns the interval between recycling operations in seconds
setInterval(float)	void	Sets the interval; throws RuntimeException if ≤ 0
getTimer()	Timer	Returns the Hyperf Timer instance for scheduling
setTimer(Timer)	void	Injects a custom Timer instance
getTimerId()	?int	Returns the current timer ID or null if not started
start()	void	Begins periodic recycling operations
stop()	void	Halts recycling and clears the timer
getLastRecycledAt(string)	DateTime|int|null	Retrieves the last recycling timestamp for a named pool

Sources: src/Contracts/Recycler.php11-54

Constructor Dependencies

The ObjectRecycler constructor requires two parameters:

• $manager: A PoolFactory instance (typically PoolManager) that provides access to all registered pools via the pools() method
• $interval: The default recycling interval in seconds (default: 10.0)

Sources: src/ObjectRecycler.php31-35

Timer Management

The recycler lazily initializes a Hyperf Timer instance when start() is called:

• src/ObjectRecycler.php60-67: The getTimer() method creates a new Timer if none exists
• src/ObjectRecycler.php72-75: The setTimer() method allows injecting a custom timer for testing
• src/ObjectRecycler.php18: The timer is stored in the $timer property
• src/ObjectRecycler.php23: The timer ID is stored in $timerId to track the active tick

Sources: src/ObjectRecycler.php18-75

---

Lifecycle Management

Diagram: ObjectRecycler State Machine

Sources: src/ObjectRecycler.php88-110 src/ObjectRecycler.php124-133

Starting the Recycler

The start() method initiates the periodic recycling process:

1. Guard Clause: Returns early if $timerId is already set src/ObjectRecycler.php90-92
2. Timer Creation: Calls $this->getTimer()->tick() with the configured interval src/ObjectRecycler.php94-97
3. Callback Registration: Registers recycleObjects() as the recurring callback
4. ID Storage: Stores the timer ID for later cleanup

The method is idempotent—calling start() multiple times has no additional effect if already running.

Sources: src/ObjectRecycler.php88-98

Stopping the Recycler

The stop() method halts recycling operations:

1. Timer Clearing: Calls $this->getTimer()->clear($timerId) if a timer ID exists src/ObjectRecycler.php105-107
2. Reset State: Sets $timerId to null src/ObjectRecycler.php109

Sources: src/ObjectRecycler.php103-110

Framework Integration

The StartRecycler listener automatically starts the recycler when a Hyperf worker process initializes:

• Event: Listens for Hyperf\Framework\Event\AfterWorkerStart src/Listeners/StartRecycler.php19-24
• Action: Resolves the Recycler from the container and calls start() src/Listeners/StartRecycler.php26-30

This ensures the recycler begins operation automatically in each worker process without manual intervention.

Sources: src/Listeners/StartRecycler.php12-31

---

Recycling Process

Diagram: Recycling Execution Flow

Sources: src/ObjectRecycler.php124-133

The recycleObjects Method

The core recycling logic is implemented in the protected recycleObjects() method:

Step-by-step execution:

1. Pool Iteration: Calls $this->manager->pools() to get an iterator of all registered pools src/ObjectRecycler.php126
2. Strategy Retrieval: For each pool, calls getRecycleStrategy() to obtain its recycling strategy src/ObjectRecycler.php127
3. Decision Check: Calls shouldRecycle($pool) on the strategy to determine if recycling is needed src/ObjectRecycler.php129
4. Strategy Execution: If needed, calls recycle($pool) to execute the actual recycling operation src/ObjectRecycler.php130

The recycler delegates all decision-making and execution logic to individual strategies, making the system extensible and allowing different pools to have different recycling behaviors.

Sources: src/ObjectRecycler.php124-133

---

Configuration

Interval Configuration

The recycling interval can be configured in three ways:

1. Constructor Injection

2. Setter Method

The setInterval() method validates the interval and throws a RuntimeException if invalid:

src/ObjectRecycler.php48-55

3. Runtime Retrieval

The current interval can be retrieved using getInterval():

src/ObjectRecycler.php40-43

Validation Rules

Rule	Enforcement	Error
Interval > 0	setInterval()	RuntimeException: 'Interval must be greater than 0.'
Single active timer	start() guard	Idempotent—no error, just returns early

Sources: src/ObjectRecycler.php40-55 src/Contracts/Recycler.php20-23

---

Timestamp Tracking

The getLastRecycledAt() method provides access to recycling timestamps for monitoring and debugging:

Return values:

• DateTime: When the pool uses Carbon timestamps
• int: When the pool uses Unix timestamps
• null: If the pool has never been recycled

This method delegates to the individual pool's tracking mechanism, allowing applications to monitor recycling activity per pool.

Sources: src/ObjectRecycler.php115-119

---

Integration Points

Dependencies

The ObjectRecycler integrates with several framework components:

Component	Namespace	Usage
Timer	Hyperf\Coordinator\Timer	Schedules periodic callbacks src/ObjectRecycler.php8
PoolFactory	Hypervel\ObjectPool\Contracts\Factory	Accesses registered pools src/ObjectRecycler.php9
Recycler	Hypervel\ObjectPool\Contracts\Recycler	Interface implementation src/ObjectRecycler.php10

Sources: src/ObjectRecycler.php5-13

Container Registration

The recycler is registered in the Hyperf container through the ConfigProvider class, which binds:

• The Recycler interface to the ObjectRecycler implementation
• The StartRecycler listener to the AfterWorkerStart event

For details on container configuration, see Configuration Provider.

Sources: src/Listeners/StartRecycler.php14-16 src/Listeners/StartRecycler.php28-29

---

Error Handling

The ObjectRecycler implements basic error handling:

Invalid Interval

src/ObjectRecycler.php50-52

Defensive Coding

• Null Timer ID: The stop() method checks for $timerId existence before clearing src/ObjectRecycler.php105
• Lazy Timer Initialization: The getTimer() method creates a timer only when needed src/ObjectRecycler.php62-66
• Idempotent Start: The start() method guards against multiple starts src/ObjectRecycler.php90-92

Sources: src/ObjectRecycler.php48-110

---

Usage Example

In a typical Hyperf application, the StartRecycler listener handles initialization automatically, so manual start() calls are unnecessary.

Sources: src/ObjectRecycler.php31-35 src/ObjectRecycler.php88-98 src/ObjectRecycler.php103-110 src/Listeners/StartRecycler.php26-30