io.vertx.core.net.impl.clientconnection

Class Pool<C>

java.lang.Object

io.vertx.core.net.impl.clientconnection.Pool<C>

public class Pool<C>
extends Object

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

Interactions with the pool modifies the pool state and then the pool will run tasks to make progress satisfying the pool requests.

The pool maintains a few invariants:

• a connection in the available set has its Holder#capacity> 0
• weight is the sum of all connection's Holder#weight
• capacity is the sum of all connection's Holder#capacity
• connecting is the number of the connections connecting but not yet connected

A connection is delivered to a Waiter on the pool's context event loop thread, the waiter must take care of calling ContextInternal.execute(io.vertx.core.Handler<java.lang.Void>) if necessary.

Calls to the pool are synchronized on the pool to avoid race conditions and maintain its invariants. This pool can be called from different threads safely (although it is not encouraged for performance reasons, we benefit from biased locking which makes the overhead of synchronized near zero), since it synchronizes on the pool.

Pool weight

To constrain the number of connections the pool maintains a weight field that must remain lesser than maxWeight to create a connection. Such weight 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.

When a connection is created an initialWeight is added to the current weight. When the channel is connected the ConnectResult callback value provides actual connection weight so it can be used to correct the pool weight. When the channel fails to connect the initial weight is used to correct the pool weight.

Recycling a connection

When a connection is recycled and reaches its full capacity (i.e Holder#concurrency == Holder#capacity, then it is put back in the pool so it can be borrowed again.

Acquiring a connection

When a waiter wants to acquire a connection it is added to the waitersQueue and the request is handled by the pool asynchronously:

• when there is an available pooled connection, this connection is delivered to the waiter and it is removed from the queue
• when there is no available connection a connection is created when weight<maxWeight
• when the max number of waiters is reached, the request is failed
• otherwise the waiter remains in the queue until progress can be done (i.e a connection is recycled, etc...)

Waiter notifications happens on the event-loop thread to avoid races with connection event happening on the same thread.

Connection eviction

Connection can be evicted from the pool with ConnectionListener.onEvict(), after this call, the connection is fully managed by the caller. This can be used for signaling a connection close or when the connection has been upgraded for an HTTP connection.

Idle closing

Closing idle connection can be achieved by calling closeIdle(). This will check every available connection (i.e that are not borrowed) by calling the ConnectionProvider.isValid(C) predicate. When ConnectionProvider.isValid(C) return false then the connection is closed.

Pool progress

When the pool state is modified, an asynchronous task is executed to make the pool state progress. The pool ensures that a single progress task is executed with the checkInProgress flag.

Author:

Julien Viet, Tim Fox

Constructor Summary

Constructors

Constructor and Description
Pool(Context context, ConnectionProvider<C> connector, int queueMaxSize, long initialWeight, long maxWeight, Consumer<C> connectionAdded, Consumer<C> connectionRemoved, boolean fifo)

Method Summary

Modifier and Type	Method and Description
long	capacity()
void	checkInvariants() Sanity check of pool invariants.
void	closeIdle() Close all connections returning false when ConnectionProvider.isValid(C) is called.
void	getConnection(Handler<AsyncResult<Lease<C>>> handler) Get a connection for a waiter asynchronously.
String	toString()
int	waitersInQueue()
long	weight()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Pool

public Pool(Context context,
            ConnectionProvider<C> connector,
            int queueMaxSize,
            long initialWeight,
            long maxWeight,
            Consumer<C> connectionAdded,
            Consumer<C> connectionRemoved,
            boolean fifo)

Method Detail

waitersInQueue

public int waitersInQueue()

weight

public long weight()

capacity

public long capacity()

getConnection

public void getConnection(Handler<AsyncResult<Lease<C>>> handler)

Get a connection for a waiter asynchronously.

Parameters:

handler - the handler

closeIdle

public void closeIdle()

Close all connections returning false when ConnectionProvider.isValid(C) is called.

checkInvariants

public void checkInvariants()

Sanity check of pool invariants.

Throws:

IllegalStateException - when an invariant is invalid

toString

public String toString()

Overrides:

toString in class Object