Timeout timeout = new Timeout(1, SECONDS);
MyPoolable obj = pool.claim(timeout);
try {
// Do useful things with 'obj'.
// Note that 'obj' will be 'null' if 'claim' timed out.
} finally {
if (obj != null) {
obj.release();
}
}
- java.lang.Object
-
- stormpot.PoolTap<T>
-
- stormpot.Pool<T>
-
- Type Parameters:
T
- the type ofPoolable
contained in the pool, as determined
public abstract class Pool<T extends Poolable> extends PoolTap<T>
A Pool is a self-renewable set of objects from which one can claim exclusive access to elements, until they are released back into the pool.
Pools are thread-safe, and their
PoolTap.claim(Timeout)
methods can be called concurrently from multiple threads. This is a strictly stronger guarantee thanPoolTap
provides.Pools extend the
PoolTap
class, which provides the API for accessing the objects contained in the pool.Pools contain
Poolable
objects. When you claim an object in a pool, you also take upon yourself the responsibility of eventuallyreleasing
that object again. By far the most common idiom to achieve this is with atry-finally
clause:The pools are resizable, and can have their capacity changed at any time after they have been created.
All pools are configured with a certain size, the number of objects that the pool will have allocated at any one time, and they can change this number on the fly using the
setTargetSize(int)
method. The change does not take effect immediately, but instead moves the "goal post" and leaves the pool to move towards it at its own pace.No guarantees can be made about when the pool will actually reach the target size, because it might depend on how long it takes for a certain number of objects to be released back into the pool.
NotePools created with
of(Object[])
are not resizable, and callingsetTargetSize(int)
orManagedPool.setTargetSize(int)
will cause anUnsupportedOperationException
to be thrown.Pools are themselves life-cycled, and should be
shut down
when they are no longer needed.Note that Pools are not guaranteed to have overwritten the
Object#finalize()
method. Pools are expected to rely on explicit clean-up for releasing their resources.- Author:
- Chris Vest <mr.chrisvest@gmail.com>
- See Also:
PoolTap
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static <T extends Poolable>
PoolBuilder<T>from(Allocator<T> allocator)
Get aPoolBuilder
based on the givenAllocator
orReallocator
, which can then in turn be used to build aPool
instance with the desired configuration.static <T extends Poolable>
PoolBuilder<T>fromInline(Allocator<T> allocator)
Get aPoolBuilder
based on the givenAllocator
orReallocator
, which can then in turn be used to build aPool
operating in the <em>inline</em> mode, with the desired configuration.static <T extends Poolable>
PoolBuilder<T>fromThreaded(Allocator<T> allocator)
Get aPoolBuilder
based on the givenAllocator
orReallocator
, which can then in turn be used to build a <em>threaded</em>Pool
instance with the desired configuration.abstract ManagedPool
getManagedPool()
Get theManagedPool
instance that represents this pool.abstract int
getTargetSize()
Get the currently configured target size of the pool.abstract PoolTap<T>
getThreadLocalTap()
Get aPoolTap
that only support access by one thread at a time.PoolTap<T>
getThreadSafeTap()
Get a thread-safePoolTap
implementation for this pool, which can be freely shared among multiple threads.static <T> Pool<Pooled<T>>
of(T... objects)
Build aPool
instance that pools the given set of objects.abstract void
setTargetSize(int size)
Set the target size for this pool.abstract Completion
shutdown()
Initiate the shut down process on this pool, and return aCompletion
instance representing the shut down procedure.
-
-
-
Method Detail
-
from
public static <T extends Poolable> PoolBuilder<T> from(Allocator<T> allocator)
Get a
PoolBuilder
based on the givenAllocator
orReallocator
, which can then in turn be used to build aPool
instance with the desired configuration.This method is synonymous for
fromThreaded(Allocator)
.- Type Parameters:
T
- The type ofPoolable
that is created by the allocator,- Parameters:
allocator
- The allocator we want our pools to use. This cannot benull
.- Returns:
- A
PoolBuilder
that admits additional configurations, before the pool instance is built. - See Also:
fromThreaded(Allocator)
-
fromThreaded
public static <T extends Poolable> PoolBuilder<T> fromThreaded(Allocator<T> allocator)
Get a
PoolBuilder
based on the givenAllocator
orReallocator
, which can then in turn be used to build a <em>threaded</em>Pool
instance with the desired configuration.The returned
PoolBuilder
will build pools that allocate and deallocate objects in a background thread. Hence the "threaded" in the name; the objects are created and destroyed by the background thread, out of band with the threads that call into the pool to claim objects.By moving the allocation of objects to a background thread, it can be guaranteed that the timeouts given to
claim
will always be honoured. In other words, a slow allocation cannot block aclaim
call beyond its intended timeout.- Type Parameters:
T
- The type ofPoolable
that is created by the allocator,- Parameters:
allocator
- The allocator we want our pools to use. This cannot benull
.- Returns:
- A
PoolBuilder
that admits additional configurations, before the pool instance is built.
-
fromInline
public static <T extends Poolable> PoolBuilder<T> fromInline(Allocator<T> allocator)
Get a
PoolBuilder
based on the givenAllocator
orReallocator
, which can then in turn be used to build aPool
operating in the <em>inline</em> mode, with the desired configuration.The returned
PoolBuilder
will build pools that allocate and deallocate objects in-line with, and as part of, the claim calls. Hence the "inline" in the name.This way, pools operating in the inline mode do not need a background thread. This means that it is harder for claim to honour the given
Timeout
. It also means that the background services, such as background expiration checking, and automatically replacing failed allocations, are not available. On the other hand, inline pool consumes fewer memory and CPU resources.- Type Parameters:
T
- The type ofPoolable
that is created by the allocator,- Parameters:
allocator
- The allcoator we want our pools to use. This cannot benull
.- Returns:
- A
PoolBuilder
that admits additional configurations, before the pool instance is built.
-
of
@SafeVarargs public static <T> Pool<Pooled<T>> of(T... objects)
Build a
Pool
instance that pools the given set of objects.The objects in the pool are never expired, and never deallocated. Explicitly expired objects simply return to the pool.
This means that the returned pool has no background allocation thread, and has no expiration checking overhead when claiming objects.
The given objects are wrapped in
Pooled
objects, which implement thePoolable
interface.Shutting down the returned pool will not cause the given objects to be deallocated. The shut down process will complete as soon as the last claimed object is released back to the pool.
NotePassing duplicate objects to this method is not supported. The behaviour of the pool is unspecified if there are duplicates among the objects passed as arguments to this method.
- Type Parameters:
T
- The type of objects being pooled.- Parameters:
objects
- The objects the pool should contain.- Returns:
- A pool of the given objects.
-
shutdown
public abstract Completion shutdown()
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
PoolTap.claim(Timeout)
will throw anIllegalStateException
. Threads that are already waiting for objects in the claim method, will also wake up and receive anIllegalStateException
.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.
- Returns:
- A
Completion
instance that represents the shut down process.
-
setTargetSize
public abstract void setTargetSize(int size)
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 0 (which would deviate from the standard configuration space) will throw an
IllegalArgumentException
if passed -1 or less.Pools that do not support online resizing will throw an
UnsupportedOperationException
.- Parameters:
size
- The new target size of the pool
-
getTargetSize
public abstract int getTargetSize()
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.
- Returns:
- The current target size of this pool.
-
getManagedPool
public abstract ManagedPool getManagedPool()
Get the
ManagedPool
instance that represents this pool.- Returns:
- The
ManagedPool
instance for this pool.
-
getThreadSafeTap
public final PoolTap<T> getThreadSafeTap()
Get a thread-safe
PoolTap
implementation for this pool, which can be freely shared among multiple threads.- Returns:
- A thread-safe
PoolTap
.
-
getThreadLocalTap
public abstract PoolTap<T> getThreadLocalTap()
Get a
PoolTap
that only support access by one thread at a time. In other words, wherePoolTap.claim(Timeout)
cannot be called concurrently in multiple threads on the same tap.The pool itself will still be thread-safe, but each thread that wishes to access the pool via a thread-local tap, must have their own tap instance.
It is a use error to access these pool taps concurrently from multiple threads, or to transfer them from one thread to another without safe publication.
- Returns:
- A thread-local
PoolTap
.
-
-