Transport Pooling

Purpose and Scope

This document explains the transport pooling system in hypervel/mail, which provides connection pooling for email transports to optimize performance in high-throughput scenarios. Transport pooling reuses transport connections across multiple email sends, reducing the overhead of establishing new connections for each message.

For information about the transport layer architecture and available transport types, see Transport System Overview and Transport Drivers. For custom transport implementations, see Custom Transport Drivers.

Overview

Transport pooling is a performance optimization technique that maintains a pool of reusable transport connections. When sending emails, instead of creating a new transport connection for each message, the system borrows an existing connection from the pool, uses it, and returns it for reuse. This approach significantly reduces connection establishment overhead, particularly for protocols like SMTP that involve handshake negotiations.

Connection Pooling Benefits

Benefit	Description
Reduced Latency	Eliminates connection establishment overhead for subsequent sends
Resource Efficiency	Maintains a controlled number of connections rather than creating/destroying continuously
Throughput Improvement	Enables higher email sending rates by reusing authenticated connections
Connection Management	Automatic cleanup and lifecycle management of transport connections

Sources: src/MailManager.php1-562

Architecture

The transport pooling system uses a proxy pattern to transparently wrap transport instances with pooling capabilities. The architecture consists of three main components:

Diagram: Transport Pooling Architecture

Sources: src/MailManager.php21-73 src/TransportPoolProxy.php1-29

Component Responsibilities

Diagram: Pooling Component Interactions

Sources: src/MailManager.php155-188 src/TransportPoolProxy.php15-28

TransportPoolProxy Class

The TransportPoolProxy class is the core implementation of the pooling mechanism. It extends the base PoolProxy class from the hypervel/object-pool package and implements the TransportInterface to transparently act as a transport.

Class Structure

Component	Purpose
Base Class	Hypervel\ObjectPool\PoolProxy - Provides core pooling functionality
Interfaces	TransportInterface - Symfony mailer transport contract
Stringable - Enables string representation for debugging
Methods	send() - Proxies message sending to pooled transport instance
__toString() - Returns string representation via __call proxy

The proxy uses PHP's __call magic method to delegate all method calls to a pooled transport instance, automatically handling borrowing from and returning to the pool.

Diagram: Pooled Transport Execution Flow

Sources: src/TransportPoolProxy.php1-29

Implementation Details

The TransportPoolProxy class delegates transport operations through the __call method inherited from PoolProxy:

• Line 20-23: The send() method delegates to __call(__FUNCTION__, func_get_args()), which handles pool borrowing/returning
• Line 25-28: The __toString() method similarly delegates through __call for string representation

This delegation pattern ensures that the proxy transparently handles all TransportInterface methods while managing the connection pool lifecycle.

Sources: src/TransportPoolProxy.php15-29

Poolable Transport Types

The MailManager defines which transport types support pooling through the $poolables array. These are transports that benefit from connection reuse and can safely share connections across multiple sends.

Supported Poolable Transports

Diagram: Poolable Transport Types

The complete list of poolable transports is defined at src/MailManager.php71-73:

Non-Poolable Transports

Transports not included in the $poolables array are not wrapped with pooling:

Transport	Reason Not Poolable
log	Writes to log files; no connection to pool
array	Stores in memory array; stateful for testing

Sources: src/MailManager.php71-73

Configuration

Transport pooling is configured at the mailer level through the pool configuration key. Each mailer can specify its own pool settings, or use the pool proxy with default settings.

Pool Configuration Structure

Diagram: Pool Configuration Hierarchy

Example Configuration

Configuration Parameters

Parameter	Type	Description
min_connections	int	Minimum number of connections maintained in the pool
max_connections	int	Maximum number of concurrent connections allowed
wait_timeout	float	Seconds to wait for an available connection before timeout
max_idle_time	float	Seconds a connection can remain idle before being closed

Sources: src/MailManager.php163-168 src/MailManager.php179-185

Integration with MailManager

The MailManager integrates pooling through the HasPoolProxy trait and determines when to apply pooling during transport creation.

Pool Proxy Creation Logic

Diagram: Pool Proxy Creation Decision Flow

The key logic is in src/MailManager.php155-188:

1. Line 124: Check if transport is in $poolables array: $hasPool = in_array($transport, $this->poolables);
2. Line 132: Pass pool name to createSymfonyTransport() if poolable: $this->createSymfonyTransport($config, $hasPool ? $name : null)
3. Lines 163-168: For custom creators, wrap in pool proxy if $poolName is not null
4. Lines 179-185: For built-in transports, wrap in pool proxy if $poolName is not null

Sources: src/MailManager.php115-188

Pool Proxy Instantiation

When a transport is determined to be poolable, the createPoolProxy() method (provided by HasPoolProxy trait) is invoked:

The method accepts:

• Pool name: Identifier for the pool (typically the mailer name)
• Factory closure: Creates the actual transport instance
• Pool config: Configuration array for pool settings

Sources: src/MailManager.php179-185

Pool Lifecycle

Understanding the pool lifecycle is important for proper resource management and debugging connection-related issues.

Diagram: Transport Pool Lifecycle States

Lifecycle Phases

Phase	Description
Initialization	MailManager creates TransportPoolProxy wrapping the transport factory
Pool Creation	Object pool initializes with min_connections transport instances
Idle State	Pool maintains ready connections within min_connections to max_connections range
Borrowing	When send() is called, a connection is borrowed from the pool
In Use	The borrowed connection sends the email message
Returning	After send completes, connection is returned to pool for reuse
Cleanup	Connections exceeding max_idle_time are closed automatically
Shutdown	On application shutdown, all pool connections are gracefully closed

Sources: src/TransportPoolProxy.php20-23

Extending Poolable Transports

When registering custom transport drivers, you can specify whether they should support pooling using the extend() method's third parameter.

Registering a Poolable Custom Transport

The extend() method signature at src/MailManager.php516-525:

When $poolable = true, the custom driver is added to the $poolables array via the addPoolable() method (provided by HasPoolProxy trait), enabling automatic pool proxy wrapping.

Sources: src/MailManager.php516-525

Performance Considerations

Transport pooling provides significant performance benefits in specific scenarios, but also introduces considerations for resource management.

When Pooling Provides Benefits

Scenario	Benefit
High-Volume Sending	Reduces per-message overhead when sending many emails
SMTP Transports	Eliminates repeated TLS handshakes and authentication
Long-Running Workers	Amortizes connection cost across worker lifetime
API-Based Transports	Reuses HTTP client connections for API calls

Resource Management Considerations

Consideration	Recommendation
Connection Limits	Configure max_connections based on SMTP server limits
Memory Usage	Each pooled connection consumes memory; balance pool size with available resources
Idle Connections	Set appropriate max_idle_time to free unused connections
Worker Restart	Pool state is lost on worker restart; connections are re-established

Pool Size Tuning

Optimal pool configuration depends on your sending patterns:

• Low-Volume Applications: Small pool (min_connections: 1, max_connections: 3)
• Medium-Volume Applications: Moderate pool (min_connections: 2, max_connections: 10)
• High-Volume Applications: Large pool (min_connections: 5, max_connections: 25)

Monitor connection usage and adjust based on actual throughput requirements.

Sources: src/MailManager.php71-73 src/MailManager.php155-188