NIOConnectionPool connectionPoolExhausted: Immediate Failure Versus Back-Pressure Semantics

Direct answer

ConnectionPoolError.connectionPoolExhausted is an immediate-failure, transient resource-limit signal, not a hard failure. SwiftNIO’s fixed-size pool does not queue or back-pressure new requests when every connection is busy; it fails the new request’s ChannelFuture immediately. Callers should treat it as retryable, typically with back-off or application-level throttling, rather than as a fatal connection error.

Confirmed facts versus assumptions

Recommended caller behavior

1. Catch ConnectionPoolError.connectionPoolExhausted in the future’s failure handler.
2. Retry the request after a short delay, preferably with exponential back-off.
3. If exhaustion persists, reduce concurrency or increase maxConnections by recreating the pool.
4. Do not treat a single exhaustion event as a fatal connection or pool failure.

Replacing the pool without dropping in-flight requests

SwiftNIO does not provide a documented runtime resize operation. The safe approach is to create a replacement pool, atomically swap the reference, wait for the old pool’s active request count to reach zero, then close the old pool.

// Illustrative only; verify exact API against your SwiftNIO version.
let replacement = NIOConnectionPool(maxConnections: newLimit, ...)
let previous = self.pool
self.pool = replacement // perform on a serial queue or actor
previous.close() // call only after activeCount is 0

1. Create the new pool with the desired maxConnections.
2. Swap the pool reference used by clients on a serial queue or actor to avoid races.
3. Poll or observe the old pool until no requests are active.
4. Close the old pool; its existing connections can finish in-flight work before shutdown.

Verification

1. Configure a test pool with maxConnections smaller than your concurrent request burst.
2. Issue more concurrent requests than the pool size and assert the future fails with connectionPoolExhausted.
3. Implement a retry loop and confirm success once a connection is released.
4. During a pool swap, log active requests before and after closing the old pool to confirm zero in-flight loss.

Missing diagnostic

Which SwiftNIO major version are you deploying? The pool API and shutdown behavior can differ between versions, and the swap-and-drain steps should be verified against your release’s source or release notes.