Object Recycling

Purpose and Scope

This page provides an overview of the automated recycling subsystem in the hypervel/object-pool package. Object recycling is the process of periodically cleaning up idle objects in pools to maintain pool health and prevent resource leaks.

This document covers the high-level architecture and process flow of the recycling system. For detailed information on specific components, see:

• Recycle Strategies - for the RecycleStrategy interface and implementations
• Object Recycler - for the ObjectRecycler scheduler implementation

For information on how pools are managed, see Pool Manager.

---

Overview

Object recycling addresses the problem of stale or unhealthy objects accumulating in pools over time. Without recycling, objects that remain idle for extended periods may:

• Hold open connections that exceed timeout limits
• Maintain stale state that is no longer valid
• Consume memory unnecessarily
• Fail when eventually retrieved due to expired resources

The recycling subsystem solves this by providing:

1. Automated scheduling - periodic checks without manual intervention
2. Pluggable strategies - different recycling policies for different pool types
3. Pool-level control - each pool can have its own recycling configuration
4. Non-blocking operation - recycling runs in the background without blocking pool operations

Sources: src/ObjectRecycler.php1-134 src/Contracts/RecycleStrategy.php1-20

---

Component Architecture

The recycling subsystem consists of three primary components working together:

Component Responsibilities:

Component	Purpose	Location
ObjectRecycler	Schedules and coordinates recycling operations across all pools	src/ObjectRecycler.php
Recycler	Interface defining recycler contract	src/Contracts/Recycler.php
RecycleStrategy	Interface for pluggable recycling policies	src/Contracts/RecycleStrategy.php
Timer	Hyperf's coroutine-safe timer for periodic execution	Hyperf\Coordinator\Timer
PoolManager	Provides access to all registered pools	See Pool Manager

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

---

Recycling Process Flow

The following sequence diagram illustrates how the recycling system operates from initialization through periodic cleanup:

Process Steps:

1. Initialization - StartRecycler listener starts ObjectRecycler on worker startup
2. Scheduling - ObjectRecycler registers a periodic callback with Timer src/ObjectRecycler.php94-97
3. Iteration - On each tick, recycleObjects() iterates through all pools src/ObjectRecycler.php124-133
4. Strategy evaluation - Each pool's RecycleStrategy determines if recycling is needed src/ObjectRecycler.php129
5. Execution - If needed, the strategy performs the recycling operation src/ObjectRecycler.php130
6. Cleanup - On shutdown, the timer is cleared to stop recycling src/ObjectRecycler.php103-110

Sources: src/ObjectRecycler.php88-133 src/Contracts/RecycleStrategy.php9-19

---

ObjectRecycler Implementation

The ObjectRecycler class is the central coordinator of the recycling subsystem, implementing the Recycler interface.

Key Attributes

Attribute	Type	Purpose
$manager	PoolFactory	Reference to pool manager for accessing all pools
$interval	float	Time in seconds between recycling checks
$timer	?Timer	Hyperf timer instance for scheduling
$timerId	?int	ID of the active timer for cleanup

Sources: src/ObjectRecycler.php14-34

Constructor Configuration

The constructor accepts:

• $manager - The pool factory (typically PoolManager) to access registered pools
• $interval - Recycling check interval in seconds (default: 10.0)

Sources: src/ObjectRecycler.php31-35

Lifecycle Methods

The recycler provides start/stop control over the recycling process:

Method	Purpose	Location
start()	Begin periodic recycling	src/ObjectRecycler.php88-98
stop()	Halt recycling and clear timer	src/ObjectRecycler.php103-110
getLastRecycledAt(string $name)	Query last recycle timestamp for a pool	src/ObjectRecycler.php115-119

Sources: src/ObjectRecycler.php88-119

---

RecycleStrategy Interface

The RecycleStrategy interface enables pluggable recycling policies. Each pool can have a different strategy based on its requirements.

Interface Methods

shouldRecycle(ObjectPool $pool): bool

Determines whether a pool needs recycling at the current moment. This method is called on every recycling interval for each pool.

recycle(ObjectPool $pool): void

Performs the actual recycling operation on the pool. This typically involves flushing idle objects and updating the pool's lastRecycledAt timestamp.

Sources: src/Contracts/RecycleStrategy.php9-19

---

Configuration

Recycling Interval

The interval between recycling checks can be configured when constructing the ObjectRecycler or modified at runtime:

The interval must be greater than 0, or a RuntimeException is thrown src/ObjectRecycler.php48-55

Sources: src/ObjectRecycler.php31-55 src/Contracts/Recycler.php14-23

Timer Configuration

The recycler uses Hyperf's Timer by default, but a custom timer can be injected:

Sources: src/ObjectRecycler.php60-75 src/Contracts/Recycler.php25-33

---

Integration with Pool System

The recycling subsystem integrates with the core pooling system through several touchpoints:

PoolManager Integration

ObjectRecycler depends on PoolFactory (typically PoolManager) to:

• Iterate through all registered pools src/ObjectRecycler.php126
• Query specific pools for last recycled timestamps src/ObjectRecycler.php117-118

ObjectPool Integration

Each ObjectPool instance:

• Stores a RecycleStrategy instance
• Provides getRecycleStrategy() to retrieve its strategy src/ObjectRecycler.php127
• Tracks lastRecycledAt timestamp
• Exposes methods called by strategies to perform cleanup

Framework Integration

The StartRecycler event listener (covered in Framework Integration) automatically starts the recycler when the Hyperf worker initializes, ensuring recycling begins without manual intervention.

Sources: src/ObjectRecycler.php28-133

---

Summary

The object recycling subsystem provides automated background maintenance for object pools through:

• ObjectRecycler - schedules periodic recycling checks
• RecycleStrategy - defines pluggable recycling policies
• Timer - provides coroutine-safe periodic execution
• Integration - works seamlessly with PoolManager and ObjectPool

For implementation details on strategies, see Recycle Strategies. For the complete ObjectRecycler API reference, see Object Recycler.

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