stormpot.bpool
Class BlazePool<T extends Poolable>

java.lang.Object
  stormpot.bpool.BlazePool<T>

Type Parameters:

T - The type of Poolable managed by this pool.

All Implemented Interfaces:

LifecycledPool<T>, LifecycledResizablePool<T>, Pool<T>, ResizablePool<T>

public final class BlazePool<T extends Poolable>
extends Object
implements LifecycledResizablePool<T>

BlazePool is a highly optimised LifecycledResizablePool implementation that consists of a queues of Poolable instances, the access to which is made faster with clever use of ThreadLocals.

Object allocation always happens in a dedicated thread, off-loading the cost of allocating the pooled objects. This should lead to reduced deviation in the times it takes claim method to complete, provided the pool is not depleted.

Author:

Chris Vest <[email protected]>

Constructor Summary

BlazePool(Config<T> config)
Construct a new BlazePool instance based on the given Config.

Method Summary

T	claim(Timeout timeout) Claim the exclusive rights until released, to an object in the pool.
int	getTargetSize() Get the currently configured target size of the pool.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

BlazePool

public BlazePool(Config<T> config)

Construct a new BlazePool instance based on the given Config.

Parameters:

config - The pool configuration to use.

Method Detail

claim

public T claim(Timeout timeout)
                         throws PoolException,
                                InterruptedException

Description copied from interface: Pool

Claim 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.

Specified by:

claim in interface Pool<T extends Poolable>

Parameters:

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.

Returns:

An object of the Poolable subtype T to which the exclusive rights have been claimed, or null if the timeout period elapsed before an object became available.

Throws:

PoolException - If an object allocation failed because the Allocator threw an exception from its allocate method, or returned null.

InterruptedException - if the current thread is interrupted upon entry, or becomes interrupted while waiting.

shutdown

public Completion shutdown()

Description copied from interface: LifecycledPool

Initiate 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.

Specified by:

shutdown in interface LifecycledPool<T extends Poolable>

Returns:

A Completion instance that represents the shut down process.

setTargetSize

public void setTargetSize(int size)

Description copied from interface: ResizablePool

Set 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.

Specified by:

setTargetSize in interface ResizablePool<T extends Poolable>

Parameters:

size - The new target size of the pool

getTargetSize

public int getTargetSize()

Description copied from interface: ResizablePool

Get 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.

Specified by:

getTargetSize in interface ResizablePool<T extends Poolable>

Returns:

The current target size of this pool.