The pool is a state machine that maintains a queue of waiters and a list of connections.

Pool state

Interactions with the pool modifies the pool state and then the pool executes actions to make progress satisfying the pool requests.

The pool is implemented as a non blocking state machine.

Calls to the pool are serialized to avoid race conditions and maintain its invariants. This pool can be called from different threads safely. The pool state is mutated exclusively by Executor.Action and actions are serialized by the executor.

Pool capacity

To constrain the number of connections the pool maintains a capacity field that must remain lesser than maxCapacity to create a connection. Such capacity is used instead of counting connection because the pool can mix connections with different concurrency (HTTP/1 and HTTP/2) and this flexibility is necessary.

Pool connector

The pool interacts with connections with the PoolConnector. The PoolConnector.Listener let the connector interact with pool:

• The connector can remove connections from the pool using PoolConnector.Listener#onRemove().
• The connector can signal the change of the connection capacity using PoolConnector.Listener#onConcurrencyChange(long).

Connection eviction

Connections can be evicted from the pool with ConnectionPool#evict(Predicate, Handler). It can be used to implement keep alive timeout.

Waiter lifecycle

Connection requests are done with ConnectionPool#acquire(ContextInternal, int, Handler). Such request creates a PoolWaiter. When such request is made

• the waiter can be handed back a connection when one is immediately available
• a connection can be created and then handed back to the waiter that initiated the action
• the waiter can be enqueued when the pool is full and the wait queue is not full
• the waiter can be failed

A connection acquisition a PoolWaiter.Listener can be provided, letting the requester to get a reference on the waiter and later use cancel(PoolWaiter, Handler) to cancel a request.