org.apache.manifoldcf.connectorcommon.throttler

Class ConnectionBin

java.lang.Object

org.apache.manifoldcf.connectorcommon.throttler.ConnectionBin

public class ConnectionBin
extends java.lang.Object

Connection tracking for a bin. This class keeps track of information needed to figure out throttling for connections, on a bin-by-bin basis. It is *not*, however, a connection pool. Actually establishing connections, and pooling established connections, is functionality that must reside in the caller. The 'connections' each connection bin tracks are connections outstanding that share this bin name. Not all such connections are identical; some may in fact have entirely different sets of bins associated with them, but they all have the specific bin in common. Since each bin has its own unique limit, this effectively means that in order to get a connection, you need to find an available slot in ALL of its constituent connection bins. If the connections are pooled, it makes the most sense to divide the pool up by characteristics such that identical connections are all handled together - and it is reasonable to presume that an identical connection has identical connection bins. NOTE WELL: This is entirely local in operation

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	ConnectionBin.SumClass

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	binName This is the bin name which this connection pool belongs to
static int	CONNECTION_DESTROY
static int	CONNECTION_POOLEMPTY
static int	CONNECTION_WITHINBOUNDS
protected int	inUseConnections This is the number of connections in this bin that are connected; immaterial whether they are in use or in a pool somewhere.
protected boolean	isAlive True if this bin is alive still
protected int	localMax This is the local maximum number of active connections allowed for this bin
protected int	maxActiveConnections This is the maximum number of active connections allowed for this bin
protected static java.util.Random	randomNumberGenerator Random number
protected int	referencingPools This is the number of active referring connection pools.
protected int	reservedConnections This is the number of connections in this bin that have been reserved - that is, they are promised to various callers, but those callers have not yet committed to obtaining them.
protected java.lang.String	serviceName The (anonymous) service name
protected java.lang.String	serviceTypeName Service type name
protected static java.lang.String	serviceTypePrefix The service type prefix for connection bins
protected java.lang.String	targetCalcLockName The target calculation lock name
protected static java.lang.String	targetCalcLockPrefix The target calculation lock prefix

Constructor Summary

Constructors

Constructor and Description
ConnectionBin(IThreadContext threadContext, java.lang.String throttlingGroupName, java.lang.String binName) Constructor.

Method Summary

Modifier and Type	Method and Description
protected static java.lang.String	buildServiceTypeName(java.lang.String throttlingGroupName, java.lang.String binName)
protected static java.lang.String	buildTargetCalcLockName(java.lang.String throttlingGroupName, java.lang.String binName)
java.lang.String	getBinName() Get the bin name.
boolean	hasPooledConnection(java.util.concurrent.atomic.AtomicInteger poolCount) Check only if there's a pooled connection, and make moves to take it from the pool.
void	noteConnectionCreation() Note the creation of an active connection that belongs to this bin.
void	noteConnectionDestroyed() Note the destruction of an active connection that belongs to this bin.
void	noteConnectionReturnedToPool(java.util.concurrent.atomic.AtomicInteger poolCount) Note a connection returned to the pool.
protected static byte[]	pack(int target, int inUse)
void	poll(IThreadContext threadContext) Poll this bin
int	shouldPooledConnectionBeDestroyed(java.util.concurrent.atomic.AtomicInteger poolCount) Figure out whether we are currently over target or not for this bin, and whether a connection should be pulled from the pool and destroyed.
boolean	shouldReturnedConnectionBeDestroyed() Figure out whether we are currently over target or not for this bin.
void	shutDown(IThreadContext threadContext) Shut down the bin, and release everything that is waiting on it.
void	undoPooledConnectionDecision(java.util.concurrent.atomic.AtomicInteger poolCount) Undo the decision to destroy a pooled connection.
void	undoReservation(int recommendation, java.util.concurrent.atomic.AtomicInteger poolCount) Undo what we had decided to do before.
protected static int	unpackInUse(byte[] data)
protected static int	unpackTarget(byte[] data)
void	updateMaxActiveConnections(int maxActiveConnections) Update the maximum number of active connections.
int	waitConnectionAvailable(java.util.concurrent.atomic.AtomicInteger poolCount, IBreakCheck breakCheck) Wait for a connection to become available, in the context of an existing connection pool.

Methods inherited from class java.lang.Object

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

Field Detail

isAlive

protected boolean isAlive

True if this bin is alive still

binName

protected final java.lang.String binName

This is the bin name which this connection pool belongs to

serviceTypeName

protected final java.lang.String serviceTypeName

Service type name

serviceName

protected final java.lang.String serviceName

The (anonymous) service name

targetCalcLockName

protected final java.lang.String targetCalcLockName

The target calculation lock name

maxActiveConnections

protected int maxActiveConnections

This is the maximum number of active connections allowed for this bin

localMax

protected int localMax

This is the local maximum number of active connections allowed for this bin

reservedConnections

protected int reservedConnections

This is the number of connections in this bin that have been reserved - that is, they are promised to various callers, but those callers have not yet committed to obtaining them.

inUseConnections

protected int inUseConnections

This is the number of connections in this bin that are connected; immaterial whether they are in use or in a pool somewhere.

referencingPools

protected int referencingPools

This is the number of active referring connection pools. We increment this number whenever a poolCount goes from zero to 1, and we decrement it whenever a poolCount goes from one to zero.

serviceTypePrefix

protected static final java.lang.String serviceTypePrefix

The service type prefix for connection bins

See Also:

Constant Field Values

targetCalcLockPrefix

protected static final java.lang.String targetCalcLockPrefix

The target calculation lock prefix

See Also:

Constant Field Values

randomNumberGenerator

protected static final java.util.Random randomNumberGenerator

Random number

CONNECTION_DESTROY

public static final int CONNECTION_DESTROY

See Also:

Constant Field Values

CONNECTION_POOLEMPTY

public static final int CONNECTION_POOLEMPTY

See Also:

Constant Field Values

CONNECTION_WITHINBOUNDS

public static final int CONNECTION_WITHINBOUNDS

See Also:

Constant Field Values

Constructor Detail

ConnectionBin

public ConnectionBin(IThreadContext threadContext,
                     java.lang.String throttlingGroupName,
                     java.lang.String binName)
              throws ManifoldCFException

Constructor.

Throws:

ManifoldCFException

Method Detail

buildServiceTypeName

protected static java.lang.String buildServiceTypeName(java.lang.String throttlingGroupName,
                                                       java.lang.String binName)

buildTargetCalcLockName

protected static java.lang.String buildTargetCalcLockName(java.lang.String throttlingGroupName,
                                                          java.lang.String binName)

getBinName

public java.lang.String getBinName()

Get the bin name.

updateMaxActiveConnections

public void updateMaxActiveConnections(int maxActiveConnections)

Update the maximum number of active connections.

waitConnectionAvailable

public int waitConnectionAvailable(java.util.concurrent.atomic.AtomicInteger poolCount,
                                   IBreakCheck breakCheck)
                            throws java.lang.InterruptedException,
                                   BreakException

Wait for a connection to become available, in the context of an existing connection pool.

Parameters:

poolCount - is the number of connections in the pool times the number of bins per connection. This parameter is only ever changed in this class!!

Returns:

a recommendation as to how to proceed, using the IConnectionThrottler values. If the recommendation is to create a connection, a slot will be reserved for that purpose. A subsequent call to noteConnectionCreation() will be needed to confirm the reservation, or clearReservation() to release the reservation.

Throws:

java.lang.InterruptedException

BreakException

undoReservation

public void undoReservation(int recommendation,
                            java.util.concurrent.atomic.AtomicInteger poolCount)

Undo what we had decided to do before.

Parameters:

recommendation - is the decision returned by waitForConnection() above.

noteConnectionCreation

public void noteConnectionCreation()

Note the creation of an active connection that belongs to this bin. The connection MUST have been reserved prior to the connection being created.

shouldReturnedConnectionBeDestroyed

public boolean shouldReturnedConnectionBeDestroyed()

Figure out whether we are currently over target or not for this bin.

shouldPooledConnectionBeDestroyed

public int shouldPooledConnectionBeDestroyed(java.util.concurrent.atomic.AtomicInteger poolCount)

Figure out whether we are currently over target or not for this bin, and whether a connection should be pulled from the pool and destroyed. Note that this is tricky in conjunction with other bins, because those other bins may conclude that we can't destroy a connection. If so, we just return the stolen connection back to the pool.

Returns:

CONNECTION_DESTROY, CONNECTION_POOLEMPTY, or CONNECTION_WITHINBOUNDS.

hasPooledConnection

public boolean hasPooledConnection(java.util.concurrent.atomic.AtomicInteger poolCount)

Check only if there's a pooled connection, and make moves to take it from the pool.

undoPooledConnectionDecision

public void undoPooledConnectionDecision(java.util.concurrent.atomic.AtomicInteger poolCount)

Undo the decision to destroy a pooled connection.

noteConnectionReturnedToPool

public void noteConnectionReturnedToPool(java.util.concurrent.atomic.AtomicInteger poolCount)

Note a connection returned to the pool.

noteConnectionDestroyed

public void noteConnectionDestroyed()

Note the destruction of an active connection that belongs to this bin.

poll

public void poll(IThreadContext threadContext)
          throws ManifoldCFException

Poll this bin

Throws:

ManifoldCFException

shutDown

public void shutDown(IThreadContext threadContext)
              throws ManifoldCFException

Shut down the bin, and release everything that is waiting on it.

Throws:

ManifoldCFException

unpackTarget

protected static int unpackTarget(byte[] data)

unpackInUse

protected static int unpackInUse(byte[] data)

pack

protected static byte[] pack(int target,
                             int inUse)