Object Pooling & Performance

This document explains the connection pooling mechanism used by the broadcasting system to optimize performance when using external service broadcasters. It covers which drivers support pooling, how the pool proxy is implemented, and how to configure pool parameters.

For information about the overall broadcasting architecture and driver system, see Core Architecture. For details on specific broadcaster implementations, see Broadcasting Drivers.

---

Purpose and Scope

Connection pooling in the broadcasting system addresses performance bottlenecks that occur when creating new connections to external services (Pusher, Ably) for each broadcast operation. Instead of establishing a new HTTP connection for every broadcast, the system maintains a pool of reusable broadcaster instances, significantly reducing latency and resource consumption in high-throughput scenarios.

This document covers:

• The pooling architecture and driver eligibility
• The BroadcastPoolProxy implementation and its role
• Configuration parameters for tuning pool behavior
• Performance characteristics and recommendations

---

Pooling Architecture

The broadcasting system implements object pooling through the hypervel/object-pool package, which provides connection lifecycle management for expensive-to-create resources. The pooling mechanism is transparent to application code—when a poolable broadcaster is requested, the BroadcastManager automatically wraps it in a pool proxy.

Poolable Driver Detection

Sources: src/BroadcastManager.php248-263

The BroadcastManager maintains a list of poolable drivers in the $poolables property src/BroadcastManager.php61 Currently, only 'ably' and 'pusher' drivers support pooling, as these broadcasters make external HTTP API calls that benefit from connection reuse.

Driver	Poolable	Reason
pusher	Yes	External HTTP API calls to Pusher service
ably	Yes	External REST API calls to Ably platform
redis	No	Uses persistent Redis connections from Hyperf pool
log	No	Local file/stream operations, no external connections
null	No	No-op broadcaster, no actual operations

---

Pool Proxy Implementation

BroadcastPoolProxy Class Structure

The BroadcastPoolProxy class serves as a wrapper that implements the Broadcaster contract while delegating actual operations to pooled broadcaster instances. It extends PoolProxy from the hypervel/object-pool package and transparently manages connection lifecycle.

Sources: src/BroadcastPoolProxy.php1-34

Method Delegation Pattern

The BroadcastPoolProxy implements all methods from the Broadcaster contract by delegating to the inherited __call() method from PoolProxy:

Sources: src/BroadcastPoolProxy.php13-32

Each method in BroadcastPoolProxy follows this pattern:

• auth() src/BroadcastPoolProxy.php13-16
• validAuthenticationResponse() src/BroadcastPoolProxy.php21-24
• broadcast() src/BroadcastPoolProxy.php29-32

The __call() method inherited from PoolProxy handles:

1. Acquiring a broadcaster instance from the pool
2. Invoking the requested method on the instance
3. Returning the instance to the pool
4. Returning the method result to the caller

---

Pool Resolution Flow

Manager Resolution Logic

The BroadcastManager uses the HasPoolProxy trait to implement pool creation and management. When a driver is requested, the manager checks if it requires pooling:

Sources: src/BroadcastManager.php228-263

Key aspects of the resolution process:

1. Driver Caching src/BroadcastManager.php232: Resolved drivers are cached in $drivers array to avoid repeated resolution
2. Poolability Check src/BroadcastManager.php256: Compares $config['driver'] against $poolables array
3. Factory Closure src/BroadcastManager.php259: When pooling, passes a closure that creates the actual broadcaster
4. Pool Configuration src/BroadcastManager.php260: Extracts pool key from connection config, defaults to empty array

Trait Integration

The HasPoolProxy trait src/BroadcastManager.php28-41 provides:

• createPoolProxy(string $name, Closure $factory, array $config) method
• Pool instance management and configuration
• Integration with hypervel/object-pool package

The $poolProxyClass property src/BroadcastManager.php56 specifies which proxy class to instantiate (BroadcastPoolProxy::class).

---

Pool Configuration

Configuration Parameters

Each poolable connection in the configuration file can define a pool array with the following parameters:

Parameter	Type	Description	Default
min_objects	int	Minimum number of connections to maintain in pool	1
max_objects	int	Maximum number of connections allowed in pool	10
wait_timeout	float	Seconds to wait for available connection (seconds)	3.0
max_lifetime	float	Maximum lifetime of connection before recreation (seconds)	60.0

Sources: public/broadcasting.php67-83

Pusher Pool Configuration

Example configuration for Pusher broadcaster public/broadcasting.php51-73:

Ably Pool Configuration

Example configuration for Ably broadcaster public/broadcasting.php75-84:

Configuration Tuning Guidelines

min_objects: Minimum pool size

• Set higher (e.g., 5-10) for applications with steady broadcast load
• Keep at 1 for applications with sporadic broadcasting
• Trade-off: Higher values use more memory but reduce cold-start latency

max_objects: Maximum pool size

• Should accommodate peak concurrent broadcast operations
• Formula: max_objects >= (peak broadcasts per second × average broadcast duration)
• Too low: Requests wait or timeout; Too high: Excessive resource consumption

wait_timeout: Connection acquisition timeout

• Default 3.0 seconds is suitable for most scenarios
• Increase for applications where broadcasts can tolerate higher latency
• Decrease for strict real-time requirements (risk: more timeouts during peaks)

max_lifetime: Connection recycling interval

• Default 60.0 seconds prevents connection staleness
• Lower for unstable network environments
• Higher for stable connections to reduce recreation overhead

---

Performance Characteristics

Pooling Benefits

Connection pooling provides significant performance improvements for Pusher and Ably broadcasters:

Metric	Without Pooling	With Pooling	Improvement
Connection Establishment	Per broadcast	Amortized	~50-200ms saved per broadcast
TLS Handshake	Per broadcast	Amortized	~30-100ms saved per broadcast
HTTP Keep-Alive	Not utilized	Utilized	Reduced network overhead
Memory Allocation	Per broadcast	Pooled instances	Reduced GC pressure

Sources: src/BroadcastManager.php248-263

Non-Pooled Drivers

The Redis, Log, and Null broadcasters do not use pooling:

Redis Broadcaster: Already uses connection pooling provided by hyperf/redis through RedisFactory. The Redis pool is managed separately at a lower level src/BroadcastManager.php359-367

Log Broadcaster: Writes to PSR logger instance, which is a lightweight operation that doesn't benefit from pooling src/BroadcastManager.php372-375

Null Broadcaster: No-op implementation that performs no actual operations src/BroadcastManager.php380-383

Connection Lifecycle

Sources: src/BroadcastManager.php256-262 src/BroadcastPoolProxy.php1-34

Factory Closure

The factory closure passed to createPoolProxy() is invoked whenever a new broadcaster instance needs to be created src/BroadcastManager.php259:

This closure:

1. Calls doResolve() with the connection configuration
2. Instantiates the appropriate broadcaster (Pusher or Ably)
3. Initializes the underlying HTTP client (Guzzle for Pusher, Ably SDK for Ably)
4. Returns a fully configured Broadcaster instance

For Pusher, this involves creating a Pusher instance with Guzzle client src/BroadcastManager.php304-338 For Ably, this creates an AblyRest instance src/BroadcastManager.php343-354

---

Summary

The broadcasting system's object pooling mechanism optimizes performance for external service broadcasters (Pusher and Ably) by:

1. Automatic Pool Management: The BroadcastManager automatically detects poolable drivers and wraps them in BroadcastPoolProxy instances
2. Transparent Operation: Application code interacts with pool proxies identically to direct broadcaster instances
3. Configurable Behavior: Pool parameters can be tuned per-connection for optimal performance
4. Selective Application: Only drivers that benefit from pooling (those making external HTTP calls) are pooled

The pooling implementation leverages the hypervel/object-pool package through the HasPoolProxy trait, providing a standardized approach to resource management across the Hypervel framework.

Sources: src/BroadcastManager.php1-469 src/BroadcastPoolProxy.php1-34 public/broadcasting.php1-100