Channel

Purpose and Scope

The Channel class provides a dual-mode storage mechanism for objects within the object pool system. It automatically switches between coroutine-safe storage (Hyperf\Engine\Channel) and standard synchronous storage (SplQueue) based on the execution context, ensuring thread-safe operations in Swoole/Swow coroutine environments while maintaining compatibility with traditional PHP execution.

This document covers the Channel implementation, its mode detection logic, and API operations. For information about how pools use channels to manage objects, see 2.1. For the broader framework integration context, see 5.2.

Sources: src/Channel.php1-79

---

Dual-Mode Architecture

The Channel class maintains two internal storage mechanisms simultaneously and selects the appropriate one at runtime based on coroutine context detection:

Storage Mode	Backend	Use Case	Safety Guarantee
Coroutine Mode	Hyperf\Engine\Channel	Swoole/Swow coroutine context	Coroutine-safe, blocks on pop()
Non-Coroutine Mode	SplQueue	Traditional PHP execution	Single-threaded, immediate return

Architecture Overview

Sources: src/Channel.php11-33

---

Coroutine Context Detection

The Channel determines which storage backend to use by checking if the current execution is within a coroutine context. This detection occurs on every operation to ensure correctness even when objects are accessed from different contexts.

Detection Mechanism

The isCoroutine() method src/Channel.php75-78 calls Coroutine::id(), which returns:

• > 0: A positive integer coroutine ID when executing inside a coroutine
• 0: When executing in traditional synchronous PHP context

Sources: src/Channel.php75-78

---

Constructor and Initialization

The Channel constructor initializes both storage backends simultaneously, even though only one will be used per operation:

The $size parameter src/Channel.php28-33 specifies the maximum capacity for the coroutine channel. The SplQueue has no built-in size limit but the ObjectPool enforces object limits separately.

Sources: src/Channel.php24-33

---

API Operations

The Channel class provides three core operations that abstract away the mode selection logic:

pop() - Retrieve Objects

Retrieves an object from the channel with timeout support:

Method Signature: public function pop(float $timeout): false|object

Behavior Differences:

• Coroutine Mode: Blocks the current coroutine until an object is available or timeout expires
• Non-Coroutine Mode: Returns immediately; timeout parameter is ignored

Sources: src/Channel.php35-45

push() - Store Objects

Adds an object to the channel:

Method Signature: public function push(object $data): bool

Behavior Differences:

• Coroutine Mode: Returns true if successful, false if channel is full
• Non-Coroutine Mode: Always returns true; SplQueue has no size limit

Sources: src/Channel.php47-58

length() - Query Size

Returns the current number of objects stored in the channel:

Method Signature: public function length(): int

Implementation:

• Coroutine Mode: Calls CoChannel::getLength()
• Non-Coroutine Mode: Calls SplQueue::count()

Sources: src/Channel.php60-70

---

Operation Summary Table

Operation	Coroutine Mode	Non-Coroutine Mode	Timeout Respected
pop()	channel->pop($timeout)	queue->shift()	Yes (coroutine only)
push()	channel->push($data)	queue->push($data)	N/A
length()	channel->getLength()	queue->count()	N/A

Sources: src/Channel.php38-69

---

Integration with ObjectPool

The ObjectPool uses Channel as its internal storage mechanism for available objects. The dual-mode design ensures correct behavior regardless of how the pool is accessed:

Usage Scenarios

Scenario 1: Coroutine-Based Web Server

• Multiple coroutines request objects simultaneously
• Channel uses CoChannel with proper coroutine synchronization
• pop() blocks coroutines when pool is empty, yielding to other coroutines

Scenario 2: Traditional PHP-FPM or CLI

• Single-threaded execution
• Channel uses SplQueue with immediate operations
• pop() returns immediately with available object or false

Scenario 3: Mixed Execution (Testing)

• Tests may run outside coroutine context even in Swoole environment
• Channel automatically switches to SplQueue mode
• No code changes required in tests

Sources: src/Channel.php1-79

---

Implementation Details

Property Definitions

The class maintains both storage backends as protected properties:

Property	Type	Purpose	Initialization
$channel	CoChannel	Coroutine-safe storage	new CoChannel($size)
$queue	SplQueue	Synchronous storage	new SplQueue()
$size	int	Channel capacity	Constructor parameter

Sources: src/Channel.php13-21

Coroutine Safety Guarantee

The coroutine-safe behavior relies on Hyperf\Engine\Channel, which abstracts the underlying Swoole or Swow channel implementation. This ensures:

1. Atomicity: Push and pop operations are atomic within coroutine context
2. Blocking Semantics: Pop operations properly suspend the current coroutine
3. Capacity Management: Channel enforces size limits in coroutine mode

In non-coroutine mode, safety is guaranteed by PHP's single-threaded execution model.

Sources: src/Channel.php1-79

---

Class Structure Reference

Sources: src/Channel.php1-79

---

Performance Considerations

Coroutine Mode

• Overhead: Minimal coroutine context switching overhead
• Blocking: Efficient coroutine suspension when pool is empty
• Concurrency: Supports thousands of concurrent coroutine operations

Non-Coroutine Mode

• Overhead: Near-zero overhead, direct PHP data structure operations
• Blocking: No blocking support; immediate returns
• Concurrency: Single-threaded by definition

The dual-mode design ensures optimal performance in both contexts without requiring different code paths at the application level.

Sources: src/Channel.php1-79