Recycle Strategies

Purpose and Scope

This document covers the strategy pattern implementation used for automated pool recycling in the hypervel/object-pool package. Recycle strategies determine when and how idle objects in a pool should be flushed to prevent resource staleness and memory buildup. The document focuses on the RecycleStrategy interface and its implementations, particularly the built-in TimeStrategy.

For information about the automated scheduler that applies these strategies to pools, see Object Recycler. For details on pool configuration options that affect recycling behavior, see Pool Configuration.

---

Strategy Pattern Overview

The recycling subsystem uses the strategy pattern to decouple recycling logic from the core pool implementation. Each ObjectPool instance can have its own recycling strategy that determines when objects should be flushed from the pool.

Sources: src/Contracts/RecycleStrategy.php1-21 src/Contracts/TimeStrategy.php1-14 src/Strategies/TimeStrategy.php1-64

---

RecycleStrategy Interface

The RecycleStrategy interface defines the contract that all recycling strategies must implement. It consists of two methods that work together to manage the recycling lifecycle.

Interface Definition

Method	Return Type	Description
shouldRecycle(ObjectPool $pool)	bool	Determines if the pool should recycle objects at this moment
recycle(ObjectPool $pool)	void	Performs the actual recycling operation on the pool

The interface is located at src/Contracts/RecycleStrategy.php9-20 and is designed to be simple yet flexible, allowing different implementations to use various criteria for recycling decisions.

Decision and Execution Flow

Sources: src/Contracts/RecycleStrategy.php11-19 src/Strategies/TimeStrategy.php33-54

---

TimeStrategy Interface

The TimeStrategy interface extends RecycleStrategy to provide time-based recycling semantics. It adds one additional method for querying the recycling interval.

Interface Definition

Located at src/Contracts/TimeStrategy.php7-13 the interface adds:

Method	Return Type	Description
getRecycleInterval()	float	Returns the time interval (in seconds) between recycling operations

This interface enables the recycler to coordinate the strategy's timing expectations with the scheduler's execution interval.

Sources: src/Contracts/TimeStrategy.php1-14

---

TimeStrategy Implementation

The concrete TimeStrategy class located at src/Strategies/TimeStrategy.php1-64 implements time-based recycling using timestamps and configurable intervals.

Class Structure

Sources: src/Strategies/TimeStrategy.php14-28

Constructor and Initialization

The strategy is initialized through dependency injection at src/Strategies/TimeStrategy.php24-28:

• Receives a ContainerInterface instance
• Retrieves the global recycler interval from the Recycler instance
• Stores the interval in the recycleInterval property for efficient access

This design allows the strategy to align its timing expectations with the global recycler's execution schedule.

Sources: src/Strategies/TimeStrategy.php24-28

shouldRecycle Implementation

The shouldRecycle() method at src/Strategies/TimeStrategy.php33-41 implements time-based decision logic:

Algorithm details:

1. Retrieves lastRecycledAt timestamp from the pool
2. Converts DateTime objects to Unix timestamps, defaults to 0 if null
3. Calculates elapsed time: Carbon::now()->timestamp - timestamp
4. Returns true if elapsed time exceeds recycleInterval

Sources: src/Strategies/TimeStrategy.php33-41

recycle Implementation

The recycle() method at src/Strategies/TimeStrategy.php46-54 performs the actual object flushing:

Step	Operation	Code Reference
1. Calculate count	recycleCount = floor(recycleRatio × objectsInPool)	src/Strategies/TimeStrategy.php48
2. Flush objects	Loop recycleCount times calling flushOne()	src/Strategies/TimeStrategy.php49-51
3. Update timestamp	Set lastRecycledAt to current time	src/Strategies/TimeStrategy.php53

Key configuration dependency:

• The recycleRatio is obtained from the pool's PoolOption configuration
• This ratio determines what percentage of idle objects to flush (e.g., 0.5 = 50%)

Sources: src/Strategies/TimeStrategy.php46-54

---

Custom Strategy Implementation

To implement a custom recycling strategy, create a class that implements the RecycleStrategy interface. The following table outlines common use cases:

Strategy Type	shouldRecycle Logic	recycle Logic	Use Case
Time-based	Check elapsed time	Flush percentage of objects	Periodic maintenance (default)
Usage-based	Check object access count	Flush least-used objects	High-traffic pools
Health-based	Check object validation	Flush failed objects	Connection pools with health checks
Memory-based	Check memory usage	Flush until under threshold	Resource-constrained environments
Hybrid	Multiple conditions (AND/OR)	Combined flush strategies	Complex requirements

Implementation Pattern

Important considerations:

1. Thread safety: Strategies execute in the recycler's coroutine context
2. Performance: Keep shouldRecycle() lightweight as it's called frequently
3. State management: Store state in the strategy instance or use pool methods
4. Timestamp tracking: Always update lastRecycledAt after recycling

Sources: src/Contracts/RecycleStrategy.php9-20

---

Integration with ObjectPool

Each ObjectPool instance maintains its recycling state and exposes methods for strategies to interact with:

Pool State Management

Available Pool Methods

Method	Purpose	Used By
getLastRecycledAt(): ?DateTime	Get timestamp of last recycle operation	shouldRecycle()
setLastRecycledAt(DateTime $time): void	Update last recycled timestamp	recycle()
getOption(): PoolOption	Access pool configuration	Both methods
getObjectNumberInPool(): int	Get count of idle objects	recycle()
flushOne(): void	Flush a single object from pool	recycle()
flush(): void	Flush all objects from pool	Custom strategies

Sources: src/Strategies/TimeStrategy.php33-54

---

Configuration Dependencies

Recycle strategies depend on several configuration parameters from PoolOption:

Configuration	Type	Default	Impact on Recycling
recycleRatio	float	0.5	Percentage of objects to flush (TimeStrategy)
Custom properties	varies	varies	Available through getOption() for custom strategies

The global recycler interval (separate from PoolOption) controls how frequently the ObjectRecycler evaluates strategies. This interval is accessed at src/Strategies/TimeStrategy.php27 through the Recycler contract.

Sources: src/Strategies/TimeStrategy.php27-28 src/Strategies/TimeStrategy.php48

---

Lifecycle and Event Flow

The complete lifecycle showing how strategies integrate with the broader recycling system:

Sources: src/Listeners/StartRecycler.php26-30 src/Strategies/TimeStrategy.php33-54