Object Pooling for Cloud Drivers

This page documents the object pooling implementation for cloud filesystem drivers in the hypervel/filesystem package. Object pooling reduces the overhead of repeatedly creating and destroying expensive cloud storage client instances (AWS S3Client, Google Cloud StorageClient) by reusing them across filesystem operations.

The pooling system is implemented via FilesystemPoolProxy, which wraps cloud adapters in a proxy that delegates operations to pooled instances managed by hypervel/object-pool.

For the broader architecture context, see System Design and Component Interaction. For cloud driver specifics, see AWS S3 Driver and Google Cloud Storage Driver.

Overview

Cloud storage drivers (S3, GCS) require expensive SDK client initialization - AWS S3Client and Google StorageClient instances involve authentication, region configuration, and network setup. Creating these clients on every filesystem operation introduces significant overhead.

The pooling system maintains a pool of pre-initialized adapter instances that can be reused across operations. The FilesystemPoolProxy class implements the Cloud contract and delegates all method calls to pooled adapter instances via the PoolProxy base class from hypervel/object-pool.

Object Pool Component Architecture

Sources: src/FilesystemManager.php41 src/FilesystemManager.php56 src/FilesystemManager.php61 src/FilesystemPoolProxy.php13 composer.json37

Poolable Drivers

The FilesystemManager class defines which drivers use pooling via the $poolables property at src/FilesystemManager.php61 Only cloud drivers are pooled by default:

Driver	Cloud SDK Client	Reason for Pooling
s3	Aws\S3\S3Client	Client initialization includes credential resolution, region config, and HTTP client setup
gcs	Google\Cloud\Storage\StorageClient	Client requires authentication (keyfile/credentials), project ID resolution, and API endpoint configuration

Local filesystem (local), FTP (ftp), and SFTP (sftp) drivers are not pooled because they do not have expensive client initialization overhead.

Driver Resolution and Pooling Decision

Sources: src/FilesystemManager.php61 src/FilesystemManager.php124-161 src/FilesystemManager.php133

FilesystemPoolProxy Implementation

The FilesystemPoolProxy class at src/FilesystemPoolProxy.php13 extends PoolProxy from hypervel/object-pool and implements the Cloud contract. It provides a complete implementation of all filesystem methods by delegating to the parent PoolProxy::__call() method, which manages acquiring and releasing pooled instances.

FilesystemPoolProxy Class Structure

Method Category	Methods Implemented	Delegation Pattern
File Operations	exists(), get(), put(), readStream(), writeStream()	$this->__call(__FUNCTION__, func_get_args())
File Metadata	size(), lastModified(), getVisibility(), setVisibility()	$this->__call(__FUNCTION__, func_get_args())
File Manipulation	copy(), move(), delete(), append(), prepend()	$this->__call(__FUNCTION__, func_get_args())
Directory Operations	files(), allFiles(), directories(), allDirectories(), makeDirectory(), deleteDirectory()	$this->__call(__FUNCTION__, func_get_args())
Cloud Operations	url() (from Cloud contract)	$this->__call(__FUNCTION__, func_get_args())
Upload Handling	putFile(), putFileAs(), readStreamRange()	$this->__call(__FUNCTION__, func_get_args())

All 23 public methods follow the same pattern: delegate to $this->__call(), which invokes the parent PoolProxy::__call() to handle pool management.

Method Call Flow Through Pool Proxy

Sources: src/FilesystemPoolProxy.php13-223 src/FilesystemPoolProxy.php18-21 src/FilesystemPoolProxy.php65-68

Pool Creation and Configuration

The FilesystemManager uses the HasPoolProxy trait at src/FilesystemManager.php41 to access the createPoolProxy() method. This method instantiates a FilesystemPoolProxy and configures the underlying ObjectPool from hypervel/object-pool.

createPoolProxy Invocation Points

The third parameter $config['pool'] ?? [] passes pool configuration from the disk configuration. Pool configuration options are defined by hypervel/object-pool and may include:

• Maximum pool size (max number of cached instances)
• Idle timeout (how long instances remain in pool)
• Maximum lifetime (when to recreate instances)
• Validation callbacks (check instance health before reuse)

Pool Proxy Creation Flow

Sources: src/FilesystemManager.php41 src/FilesystemManager.php56 src/FilesystemManager.php136-141 src/FilesystemManager.php152-158

Custom Driver Pooling

Custom drivers can be registered as poolable through the extend method with the poolable parameter set to true. This adds the driver to the poolable drivers list and enables automatic pool proxy creation.

The HasPoolProxy trait provides the infrastructure for creating pool proxies and managing the relationship between the proxy class and poolable drivers.

Custom Driver Pool Integration

Sources: src/FilesystemManager.php470-479 src/FilesystemManager.php135-143