Module stormpot
Package stormpot

Class Pool<T extends Poolable>

  • Type Parameters:
    T - the type of Poolable 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 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:

        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();
      }
    }

    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 of(Object[]) are not resizable, and calling 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.

    Author:
    Chris Vest <mr.chrisvest@gmail.com>
    See Also:
    PoolTap

    • Method Detail

      • fromThreaded

        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 <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 a claim call beyond its intended timeout.

        Type Parameters:
        T - The type of Poolable that is created by the allocator,
        Parameters:
        allocator - The allocator we want our pools to use. This cannot be null.
        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 given Allocator or Reallocator, which can then in turn be used to build a Pool 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 of Poolable that is created by the allocator,
        Parameters:
        allocator - The allcoator we want our pools to use. This cannot be null.
        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 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.
        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 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:
        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, where PoolTap.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.