Connection Pool
Relevant source files
The following files were used as context for generating this wiki page:
The Connection Pool is a critical infrastructure component within the FLEXT gRPC platform designed to manage the lifecycle and reuse of gRPC channels. By maintaining a pool of active connections, the system reduces the overhead associated with frequently opening and closing channels, thereby enhancing performance for high-frequency gRPC operations.
The pool is implemented as a service mixin (FlextGrpcConnectionPool) that is composed into the primary FlextGrpc facade. It provides thread-safe mechanisms for acquiring, releasing, and cleaning up GrpcChannel resources, ensuring that connection management follows the project's Clean Architecture and Domain-Driven Design principles.
Sources: src/flext_grpc/services/connection_pool.py:1-15, src/flext_grpc/README.md:43-58
Architecture and Components
The connection pooling logic is encapsulated within a nested class structure that separates the service mixin from the underlying resource management logic.
Core Components
- FlextGrpcConnectionPool: A mixin class providing the interface for pooling within the facade. It initializes a
_resource_managerusing a private attribute pattern. - ConnectionPool (Inner Class): The concrete implementation of the pooling logic. It utilizes a synchronized queue and a set to track available and active connections.
- GrpcClientManager: Utilizes the connection pool to manage client-side connections, ensuring that requests for the same target can potentially reuse existing channels.
Sources: src/flext_grpc/services/connection_pool.py:11-20, src/flext_grpc/services/client.py:27-37
Thread Safety and Resource Tracking
The system uses a threading.RLock to ensure that operations on the pool are thread-safe. It maintains two primary data structures:
_pool: AQueuecontaining idleGrpcChannelobjects available for reuse._active: Asettracking channels currently in use by the application to prevent premature cleanup or duplicate acquisition.
Sources: src/flext_grpc/services/connection_pool.py:22-31
Connection Lifecycle Flow
The following diagram illustrates how a connection is managed from acquisition through release within the pool.
The diagram shows the logic for acquire() and release() methods, including the use of thread locks and capacity checks.
Sources: src/flext_grpc/services/connection_pool.py:33-60
Integration with Client Service
The GrpcClientManager serves as the primary consumer of the connection pool. When a connection is requested for a specific target, the manager first checks its internal mapping of active channels before attempting to establish new ones.
Client Connection Process
This flow explains how the GrpcClientManager interacts with utilities and the pooling mechanism to provide a m.Grpc.Client entity.
Sources: src/flext_grpc/services/client.py:39-65, src/flext_grpc/_utilities/grpc.py:126-141
Key Methods and Operations
The following table summarizes the primary operations available in the ConnectionPool implementation.
| Method | Description | Return Type |
|---|---|---|
acquire() | Attempts to retrieve an idle channel from the queue and marks it as active. | p.Result[p.Grpc.GrpcChannel] |
release(connection) | Marks an active connection as idle and returns it to the pool queue if space allows. | p.Result[bool] |
cleanup() | Clears the active set and drains the idle queue to release all resources. | p.Result[bool] |
Sources: src/flext_grpc/services/connection_pool.py:33-60
Configuration and Limits
The connection pool behavior is governed by constants defined within the enterprise gRPC platform.
| Configuration Field | Default Value | Source |
|---|---|---|
max_size (Resource Manager) | 20 | connection_pool.py:13 |
CONNECTION_DEFAULT_POOL_SIZE | Defined in c.Grpc | client.py:35 |
NETWORK_DEFAULT_CHANNEL_READY_TIMEOUT | Defined in c.Grpc | _utilities/grpc.py:129 |
Sources: src/flext_grpc/services/connection_pool.py:13-20, src/flext_grpc/services/client.py:35, src/flext_grpc/_utilities/grpc.py:126-130
Implementation Details
The implementation leverages the r result pattern for explicit error handling, avoiding standard exceptions for business logic failures like pool exhaustion.
def acquire(self) -> p.Result[p.Grpc.GrpcChannel]:
"""Acquire connection from pool."""
with self._lock:
if not self._pool.empty():
conn = self._pool.get_nowait()
self._active.add(conn)
return r[p.Grpc.GrpcChannel].ok(conn)
return e.fail_not_found("connection", "available")
Sources: src/flext_grpc/services/connection_pool.py:33-40
Summary
The Connection Pool module provides a thread-safe, resilient mechanism for managing gRPC channels. By centralizing channel lifecycle management within the FlextGrpcConnectionPool and GrpcClientManager, the system ensures efficient resource utilization and aligns with the broader project's goals of high performance and clean architectural boundaries.
Sources: src/flext_grpc/README.md:15-30, src/README.md:25-40