stormpot 3.1 · stormpot.Pool

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 claim(Timeout) methods can be called concurrently from multiple threads. This is a strictly stronger guarantee than PoolTap 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 eventually releasing that object again. By far the most common idiom to achieve this is with a `try-finally` clause: [source,java] ---- include::../src/test/java/examples/Examples.java[tag=poolClaimExample] ---- 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. [NOTE] -- Pools created with Pool#of(Object[]) are _not_ resizable, and calling Pool#setTargetSize(int) or ManagedPool#setTargetSize(int) will cause an UnsupportedOperationException 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.

Access	Constructor and Description
pack-priv	Pool()

Method Summary

Modifier and Type	Method and Description
public static < The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. T extends Poolable> PoolBuilder<T>	Returns: A `PoolBuilder` that admits additional configurations, before the pool instance is built. from(Allocator<T> The allocator we want our pools to use. This cannot be `null`. allocator) Get a `PoolBuilder` based on the given `Allocator` or `Reallocator`, which can then in turn be used to build a `Pool` instance with the desired configuration.
public static < The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. T extends Poolable> PoolBuilder<T>	Returns: A `PoolBuilder` that admits additional configurations, before the pool instance is built. fromInline(Allocator<T> The allcoator we want our pools to use. This cannot be `null`. allocator) Get a `PoolBuilder` based on the given `Allocator` or `Reallocator`, which can then in turn be used to build a `Pool` operating in the inline mode, with the desired configuration.
public static < The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. T extends Poolable> PoolBuilder<T>	Returns: A `PoolBuilder` that admits additional configurations, before the pool instance is built. fromThreaded(Allocator<T> The allocator we want our pools to use. This cannot be `null`. allocator) Get a `PoolBuilder` based on the given `Allocator` or `Reallocator`, which can then in turn be used to build a threaded `Pool` instance with the desired configuration.
public abstract ManagedPool	Returns: The `ManagedPool` instance for this pool. getManagedPool() Get the `ManagedPool` instance that represents this pool.
public abstract int	Returns: The current target size of this pool. getTargetSize() Get the currently configured target size of the pool.
public abstract PoolTap<T>	Returns: A thread-local `PoolTap`. getThreadLocalTap() Get a `PoolTap` that only support access by one thread at a time.
public final PoolTap<T>	Returns: A thread-safe `PoolTap`. getThreadSafeTap() Get a thread-safe `PoolTap` implementation for this pool, which can be freely shared among multiple threads.
public static < The type of objects being pooled. T> Pool<Pooled<T>>	Returns: A pool of the given objects. of(T... The objects the pool should contain. objects) Build a `Pool` instance that pools the given set of objects.
public abstract void	setTargetSize(int The new target size of the pool size) Set the target size for this pool.
public abstract Completion	Returns: A `Completion` instance that represents the shut down process. shutdown() Initiate the shut down process on this pool, and return a `Completion` instance representing the shut down procedure.

Inherited from stormpot.PoolTap:: apply claim supply

Constructor Detail

Pool	back to summary
pack-priv Pool()

Method Detail

from back to summary

from	back to summary
public static <T extends Poolable> PoolBuilder<T> from(Allocator<T> allocator) Get a `PoolBuilder` based on the given `Allocator` or `Reallocator`, which can then in turn be used to build a `Pool` instance with the desired configuration. This method is synonymous for `fromThreaded(Allocator)`. Parameters <T> The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. allocator:Allocator<T> The allocator we want our pools to use. This cannot be `null`. Returns:PoolBuilder<T> A `PoolBuilder` that admits additional configurations, before the pool instance is built. See Also `fromThreaded(Allocator)`

public static <T extends Poolable> PoolBuilder<T> from(Allocator<T> allocator)

Get a PoolBuilder based on the given Allocator or Reallocator, which can then in turn be used to build a Pool instance with the desired configuration. This method is synonymous for fromThreaded(Allocator).

Parameters

<T>: The type of Poolable that is created by the allocator, and the type of objects that the configured pools will contain.
allocator:Allocator<T>: The allocator we want our pools to use. This cannot be `null`.

Returns:PoolBuilder<T>

A PoolBuilder that admits additional configurations, before the pool instance is built.

See Also

fromThreaded(Allocator)

fromInline back to summary

fromInline	back to summary
public static <T extends Poolable> PoolBuilder<T> fromInline(Allocator<T> allocator) Get a `PoolBuilder` based on the given `Allocator` or `Reallocator`, which can then in turn be used to build a `Pool` operating in the inline 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. Parameters <T> The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. allocator:Allocator<T> The allcoator we want our pools to use. This cannot be `null`. Returns:PoolBuilder<T> A `PoolBuilder` that admits additional configurations, before the pool instance is built.

public static <T extends Poolable> PoolBuilder<T> fromInline(Allocator<T> allocator)

Get a PoolBuilder based on the given Allocator or Reallocator, which can then in turn be used to build a Pool operating in the inline 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.

Parameters

<T>: The type of Poolable that is created by the allocator, and the type of objects that the configured pools will contain.
allocator:Allocator<T>: The allcoator we want our pools to use. This cannot be `null`.

Returns:PoolBuilder<T>

A PoolBuilder that admits additional configurations, before the pool instance is built.

fromThreaded back to summary

fromThreaded	back to summary
public static <T extends Poolable> PoolBuilder<T> fromThreaded(Allocator<T> allocator) Get a `PoolBuilder` based on the given `Allocator` or `Reallocator`, which can then in turn be used to build a threaded `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 a `claim` call beyond its intended timeout. Parameters <T> The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. allocator:Allocator<T> The allocator we want our pools to use. This cannot be `null`. Returns:PoolBuilder<T> A `PoolBuilder` that admits additional configurations, before the pool instance is built.

public static <T extends Poolable> PoolBuilder<T> fromThreaded(Allocator<T> allocator)

Get a PoolBuilder based on the given Allocator or Reallocator, which can then in turn be used to build a threaded 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 a claim call beyond its intended timeout.

Parameters

<T>: The type of Poolable that is created by the allocator, and the type of objects that the configured pools will contain.
allocator:Allocator<T>: The allocator we want our pools to use. This cannot be `null`.

Returns:PoolBuilder<T>

A PoolBuilder that admits additional configurations, before the pool instance is built.

getManagedPool back to summary

getManagedPool	back to summary
public abstract ManagedPool getManagedPool() Get the `ManagedPool` instance that represents this pool. Returns:ManagedPool The `ManagedPool` instance for this pool.

public abstract ManagedPool getManagedPool()

Get the ManagedPool instance that represents this pool.

Returns:ManagedPool: The ManagedPool instance for this pool.

getTargetSize	back to summary
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:int The current target size of this pool.

getTargetSize

back to summary

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:int: The current target size of this pool.

getThreadLocalTap back to summary

getThreadLocalTap	back to summary
public abstract PoolTap<T> getThreadLocalTap() Get a `PoolTap` that only support access by one thread at a time. In other words, where `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:PoolTap<T> A thread-local `PoolTap`.

public abstract PoolTap<T> getThreadLocalTap()

Get a PoolTap that only support access by one thread at a time. In other words, where 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:PoolTap<T>: A thread-local PoolTap.

getThreadSafeTap back to summary

getThreadSafeTap	back to summary
public final PoolTap<T> getThreadSafeTap() Get a thread-safe `PoolTap` implementation for this pool, which can be freely shared among multiple threads. Returns:PoolTap<T> A thread-safe `PoolTap`.

public final PoolTap<T> getThreadSafeTap()

Get a thread-safe PoolTap implementation for this pool, which can be freely shared among multiple threads.

Returns:PoolTap<T>: A thread-safe PoolTap.

of back to summary

of	back to summary
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 the `Poolable` 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. [NOTE] -- Passing 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. -- Parameters <T> The type of objects being pooled. objects:T[] The objects the pool should contain. Returns:Pool<Pooled<T>> A pool of the given objects. Annotations @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 the Poolable 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. [NOTE] -- Passing 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. --

Parameters

<T>: The type of objects being pooled.
objects:T[]: The objects the pool should contain.

Returns:Pool<Pooled<T>>

A pool of the given objects.

Annotations

@SafeVarargs

setTargetSize back to summary

setTargetSize	back to summary
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:int The new target size of the pool

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:int: The new target size of the pool

shutdown back to summary

shutdown	back to summary
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 `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. Returns:Completion A `Completion` instance that represents the shut down process.

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

Returns:Completion: A Completion instance that represents the shut down process.

public abstract Class Pool<T extends Poolable>

Constructor Summary

Method Summary

Constructor Detail

Method Detail