public class QueuePool<T extends Poolable> extends Object implements LifecycledResizablePool<T>, ManagedPool
QueuePool is a fairly simple LifecycledResizablePool implementation
that basically consists of a queue of Poolable instances, and a Thread to
allocate them.
This means that the object allocation always happens in a dedicated thread. This means that no thread that calls any of the claim methods, will incur the overhead of allocating Poolables. This should lead to reduced deviation in the times it takes claim method to complete, provided the pool is not depleted.
The design is simple and straight forward, and exhibits a reasonable
base-line performance in all cases. If, however, the same threads are going
to claim and release objects from the pool over and over again — for
instance in the case of a typical Java web application — then
BlazePool is likely going to yield better
performance.
| Constructor and Description |
|---|
QueuePool(Config<T> config)
Construct a new QueuePool instance based on the given
Config. |
| Modifier and Type | Method and Description |
|---|---|
T |
claim(Timeout timeout)
Claim the exclusive rights until released, to an object in the pool.
|
long |
getAllocationCount()
Return the number of objects the pool has allocated since it was created.
|
double |
getAllocationFailureLatencyPercentile(double percentile) |
double |
getAllocationLatencyPercentile(double percentile) |
double |
getDeallocationLatencyPercentile(double percentile) |
long |
getFailedAllocationCount()
Return the number of allocations that has failed, either because the
allocator threw an exception or because it returned null, since the pool
was created.
|
long |
getLeakedObjectsCount()
If the pool is capable of precise object leak detection, this method will
return the number of object leaks that have been detected, and prevented,
since the pool was created.
|
double |
getObjectLifetimePercentile(double percentile) |
double |
getReallocationFailureLatencyPercentile(double percentile) |
double |
getReallocationLatencyPercentile(double percentile) |
int |
getTargetSize()
Get the currently configured target size of the pool.
|
boolean |
isShutDown()
Returns 'true' if the shut down process has been started on this pool,
'false' otherwise.
|
void |
setTargetSize(int size)
Set the target size for this pool.
|
Completion |
shutdown()
Initiate the shut down process on this pool, and return a
Completion instance representing the shut down procedure. |
public T claim(Timeout timeout) throws PoolException, InterruptedException
PoolClaim the exclusive rights until released, to an object in the pool.
Possibly waiting up to the specified amount of time, as given by the
provided Timeout instance, for one to become available if the
pool has been depleted. If the timeout elapses before an object can be
claimed, then null is returned instead. The timeout will be
honoured even if the Allocators allocate
methods blocks forever. If the given timeout has a zero or negative value,
then the method will not wait.
If the current thread has already one or more objects currently claimed, then a distinct object will be returned, if one is or becomes available. This means that it is possible for a single thread to deplete the pool, if it so desires.
This method may throw a PoolException if the pool have trouble allocating
objects. That is, if its assigned Allocator throws exceptions from its
allocate method, or returns null.
An InterruptedException will be thrown if the thread has its
interrupted flag set upon entry to this method, or is interrupted while
waiting. The interrupted flag on the thread will be cleared after
this, as per the general contract of interruptible methods.
If the pool is a LifecycledPool and has been shut down, then an
IllegalStateException will be thrown when this method is called.
Likewise if we are waiting for an object to become available, and someone
shuts the pool down.
Memory effects:
The release of an object happens-before
any subsequent claim or deallocation of that object, and,
The allocation of an object
happens-before any claim of that object.
claim in interface Pool<T extends Poolable>timeout - The timeout of the maximum permitted time-slice to wait for
an object to become available. A timeout with a value of zero or less
means that the call will do no waiting, preferring instead to return early
if no objects are available.null if the timeout period elapsed
before an object became available.PoolException - If an object allocation failed because the Allocator
threw an exception from its allocate method, or returned
null, or the
expiration check threw an
exception.InterruptedException - if the current thread is
interrupted upon entry, or becomes interrupted
while waiting.public Completion shutdown()
LifecycledPoolInitiate the shut down process on this pool, and return a
Completion instance representing the shut down procedure.
The shut down process is asynchronous, and the shutdown method is
guaranteed to not wait for any claimed Poolables to
be released.
The shut down process cannot complete before all Poolables are released
back into the pool and deallocated,
and all internal resources (such as threads, for instance) have been
released as well. Only when all of these things have been taken care of,
does the await methods of the Completion return.
Once the shut down process has been initiated, that is, as soon as this
method is called, the pool can no longer be used and all calls to
Pool.claim(Timeout) will throw an IllegalStateException.
Threads that are already waiting for objects in the claim method, will
also wake up and receive an IllegalStateException.
All objects that are already claimed when this method is called,
will continue to function until they are
released.
The shut down process is guaranteed to never deallocate objects that are currently claimed. Their deallocation will wait until they are released.
shutdown in interface LifecycledPool<T extends Poolable>Completion instance that represents the shut down
process.public void setTargetSize(int size)
ResizablePoolSet the target size for this pool. The pool will strive to keep this many objects allocated at any one time.
If the new target size is greater than the old one, the pool will allocate more objects until it reaches the target size. If, on the other hand, the new target size is less than the old one, the pool will deallocate more and allocate less, until the new target size is reached.
No guarantees are made about when the pool actually reaches the target size. In fact, it may never happen as the target size can be changed as often as one sees fit.
Pools that do not support a size less than 1 (which would deviate from the
standard configuration space) will throw an
IllegalArgumentException if passed 0 or less.
setTargetSize in interface ManagedPoolsetTargetSize in interface ResizablePool<T extends Poolable>size - The new target size of the poolResizablePool.setTargetSize(int)public int getTargetSize()
ResizablePoolGet the currently configured target size of the pool. Note that this is not the number of objects currently allocated by the pool - only the number of allocations the pool strives to keep alive.
getTargetSize in interface ManagedPoolgetTargetSize in interface ResizablePool<T extends Poolable>ResizablePool.getTargetSize()public long getAllocationCount()
ManagedPoolReturn the number of objects the pool has allocated since it was created.
getAllocationCount in interface ManagedPoolpublic long getFailedAllocationCount()
ManagedPoolReturn the number of allocations that has failed, either because the allocator threw an exception or because it returned null, since the pool was created.
getFailedAllocationCount in interface ManagedPoolpublic boolean isShutDown()
ManagedPoolReturns 'true' if the shut down process has been started on this pool, 'false' otherwise. This method does not reveal whether or not the shut down process has completed.
isShutDown in interface ManagedPoolLifecycledPool.shutdown() has been called on
this pool.public double getObjectLifetimePercentile(double percentile)
getObjectLifetimePercentile in interface ManagedPoolpercentile - The percentile to get, as a decimal, e.g. a number
between 0.0 and 1.0.MetricsRecorder has been
configured for the pool.MetricsRecorder.getObjectLifetimePercentile(double)public double getAllocationLatencyPercentile(double percentile)
getAllocationLatencyPercentile in interface ManagedPoolpercentile - The percentile to get, as a decimal, e.g. a number
between 0.0 and 1.0.MetricsRecorder
has been configured for the pool.MetricsRecorder.getAllocationLatencyPercentile(double)public double getAllocationFailureLatencyPercentile(double percentile)
getAllocationFailureLatencyPercentile in interface ManagedPoolpercentile - The percentile to get, as a decimal, e.g. a number
between 0.0 and 1.0.MetricsRecorder has been configured for the pool.MetricsRecorder.getAllocationFailureLatencyPercentile(double)public double getReallocationLatencyPercentile(double percentile)
getReallocationLatencyPercentile in interface ManagedPoolpercentile - The percentile to get, as a decimal, e.g. a number
between 0.0 and 1.0.MetricsRecorder has been configured for the pool.MetricsRecorder.getReallocationLatencyPercentile(double)public double getReallocationFailureLatencyPercentile(double percentile)
getReallocationFailureLatencyPercentile in interface ManagedPoolpercentile - The percentile to get, as a decimal, e.g. a number
between 0.0 and 1.0.MetricsRecorder has been configured for the pool.MetricsRecorder.getReallocationFailurePercentile(double)public double getDeallocationLatencyPercentile(double percentile)
getDeallocationLatencyPercentile in interface ManagedPoolpercentile - The percentile to get, as a decimal, e.g. a number
between 0.0 and 1.0.MetricsRecorder has been configured for
the pool.MetricsRecorder.getDeallocationLatencyPercentile(double)public long getLeakedObjectsCount()
ManagedPoolIf the pool is capable of precise object leak detection, this method will return the number of object leaks that have been detected, and prevented, since the pool was created. If the pool does not support precise object leak detection, then this method returns -1.
There are two kinds of leaks: One where the application forgets to release an object back to the pool, but keeps a strong reference to the object, and another where the application not only forgets to release the object, but also looses the reference to the object, making it eligible for garbage collection. The precise leak detector will only count leaks of the latter kind, where the leaked object has been garbage collected.
getLeakedObjectsCount in interface ManagedPoolCopyright © 2011-2014–2016. All rights reserved.