Overview

Purpose and Scope

The hypervel/object-pool package provides an object pooling system for Hyperf 3.1 applications. The package enables reuse of expensive objects (database connections, HTTP clients, etc.) across coroutine contexts, reducing instantiation overhead and improving resource utilization.

This page covers the package architecture, core concepts, and component relationships. For implementation details of ObjectPool and Channel, see section 2. For PoolManager and PoolProxy usage patterns, see section 3. For ObjectRecycler and recycling strategies, see section 4. For ConfigProvider and framework integration, see section 5.

Sources: composer.json1-11

<old_str>

Package Architecture

The Hypervel Object Pool system implements a multi-layered architecture that provides transparent object pooling with automatic lifecycle management, designed for high-concurrency environments.

System Architecture Overview

Sources: composer.json23-31 based on package dependencies and structure

Component Relationships

The system organizes around five distinct architectural layers, each with specific responsibilities:

Layer	Purpose	Key Components
Application Layer	Client interfaces and transparent access patterns	PoolProxy, HasPoolProxy trait
Management Layer	Pool creation, management, and automated maintenance	PoolManager, ObjectRecycler
Core Pooling Layer	Object storage, lifecycle, and retrieval mechanisms	ObjectPool, SimpleObjectPool, Channel
Strategy Layer	Pluggable recycling and maintenance policies	RecycleStrategy, TimeStrategy
Configuration Layer	Dependency injection and framework integration	PoolOption, ConfigProvider

## Package Architecture

The package consists of four functional layers that handle object pooling, lifecycle management, and framework integration.

Component Architecture

Sources: composer.json32-35 for package structure

Component Organization

The system organizes into four architectural layers:

Layer	Components	File Paths
Application Interface	PoolProxy, HasPoolProxy trait	src/PoolProxy.php, src/HasPoolProxy.php
Pool Management	PoolManager, ObjectRecycler	src/PoolManager.php, src/ObjectRecycler.php
Core Pooling	ObjectPool, SimpleObjectPool, Channel, PoolOption	src/ObjectPool.php, src/SimpleObjectPool.php, src/Channel.php, src/PoolOption.php
Recycling Strategy	RecycleStrategy, TimeStrategy	src/RecycleStrategy.php, src/TimeStrategy.php

Sources: composer.json33-35 for PSR-4 autoloading structure

Package Architecture

The Hypervel Object Pool system implements a multi-layered architecture that provides transparent object pooling with automatic lifecycle management, designed for high-concurrency environments.

System Architecture Overview

Sources: composer.json23-31 based on package dependencies and structure

Component Relationships

The system organizes around five distinct architectural layers, each with specific responsibilities:

Layer	Purpose	Key Components
Application Layer	Client interfaces and transparent access patterns	PoolProxy, HasPoolProxy trait
Management Layer	Pool creation, management, and automated maintenance	PoolManager, ObjectRecycler
Core Pooling Layer	Object storage, lifecycle, and retrieval mechanisms	ObjectPool, SimpleObjectPool, Channel
Strategy Layer	Pluggable recycling and maintenance policies	RecycleStrategy, TimeStrategy
Configuration Layer	Dependency injection and framework integration	PoolOption, ConfigProvider

Core Concepts

Object Pool Lifecycle

Sources: Based on architectural flow from management and core components

Dual-Mode Operation

The system operates in two modes depending on the runtime environment:

Mode	Environment	Storage Mechanism	Blocking Behavior
Coroutine Mode	Swoole/Hyperf with coroutines	Hyperf\Engine\Channel	Non-blocking with coroutine suspension
Standard Mode	Traditional PHP or non-coroutine context	SplQueue	Blocking operations

The Channel class automatically detects the runtime environment and selects the appropriate storage mechanism.

Key Framework Integration Points

Dependency Injection Setup

Sources: composer.json38-39 for ConfigProvider registration

The ConfigProvider class registers the necessary dependencies with Hyperf's PSR-11 container, enabling automatic dependency injection throughout the application. Event listeners automatically start the recycling system when workers initialize.

Runtime Dependencies

The package integrates with several Hyperf framework components:

Component	Purpose	Usage
hyperf/coroutine	Coroutine context detection	Determines dual-mode operation
hyperf/engine	High-performance channels	Coroutine-aware object storage
hyperf/coordinator	Timer management	Automated recycling coordination
hyperf/contract	Interface definitions	Framework contract compliance
nesbot/carbon	Time-based operations	Recycling strategy timing

Sources: composer.json23-30

Usage Patterns

The package supports three primary usage patterns:

1. Direct Pool Access: Using PoolManager to create pools and manually acquiring/releasing objects
2. Proxy Pattern: Using PoolProxy for transparent method delegation with automatic resource management
3. Trait Integration: Using HasPoolProxy trait to add pooling capabilities to existing classes

Each pattern provides different levels of abstraction while maintaining the same underlying pooling mechanics and automatic recycling capabilities.

Sources: Based on architectural analysis of application layer components