Package org.vibur.objectpool

Class ConcurrentPool<T>

java.lang.Object
org.vibur.objectpool.ConcurrentPool<T>
Type Parameters:
T - the type of objects held in the pool
All Implemented Interfaces:
AutoCloseable, BasePool, PoolService<T>
public class ConcurrentPool<T> extends Object implements PoolService<T>
An object pool based on a ConcurrentCollection guarded by a Semaphore. If the injected in the pool ConcurrentCollection has native implementation for offerFirst() then this pool will operate in LIFO mode, otherwise in FIFO mode.

This pool enforces a maximum limit on the number of objects that can be contained or taken out of it at any time. The pool will lazily create an object upon take request if no ready and valid object exists in it at the time of the call; not all objects need to exist and be valid in the pool at all times. The restore(T) methods do not provide any validation whether the currently restored object has been taken before that from the pool or whether it is in taken state. Correct usage of the restore operations is established by programming convention in the application.

The pool provides support for fairness with regard to the waiting takers threads. The creation of new objects and their lifecycle are controlled by the supplied during the pool creation time PoolObjectFactory. If a Listener instance has been supplied when instantiating the pool, its methods will be called when the pool executes take or restore operations.

This pool also provides support for shrinking (reduction) of the number of allocated in it objects. Note that the shrinking may reduce the createdTotal() to less than the pool initialSize().

The pool cannot contain null objects.

Author:
Simeon Malchev

  • Constructor Details

    • ConcurrentPool

      public ConcurrentPool(ConcurrentCollection<T> available, PoolObjectFactory<T> poolObjectFactory, int initialSize, int maxSize, boolean fair)
      Creates a new ConcurrentPool with the given PoolObjectFactory, initial and max sizes, and fairness setting.
      Parameters:
      available - the concurrent collection that will store the pooled objects; it must be an empty collection or a collection pre-initialized with initialSize objects
      poolObjectFactory - the factory which will be used to create new objects in this object pool as well as to control their lifecycle
      initialSize - the object pool initial size, i.e. the initial number of allocated in the object pool objects; this parameter never changes
      maxSize - the object pool max size, i.e. the max number of allocated in the object pool objects; this parameter never changes
      fair - the object pool fairness setting with regard to waiting threads
      Throws:
      IllegalArgumentException - if one of the following holds:
      initialSize < 0 || maxSize < 1 || maxSize < initialSize
      NullPointerException - if available or poolObjectFactory are null

    • ConcurrentPool

      public ConcurrentPool(ConcurrentCollection<T> available, PoolObjectFactory<T> poolObjectFactory, int initialSize, int maxSize, boolean fair, Listener<T> listener)
      Creates a new ConcurrentPool with the given PoolObjectFactory, initial and max sizes, and fairness setting.
      Parameters:
      available - the concurrent collection that will store the pooled objects; it must be an empty collection or a collection pre-initialized with initialSize objects
      poolObjectFactory - the factory which will be used to create new objects in this object pool as well as to control their lifecycle
      initialSize - the object pool initial size, i.e. the initial number of allocated in the object pool objects; this parameter never changes
      maxSize - the object pool max size, i.e. the max number of allocated in the object pool objects; this parameter never changes
      fair - the object pool fairness setting with regard to waiting threads
      listener - if not null, this listener instance methods will be called when the pool executes take or restore operations
      Throws:
      IllegalArgumentException - if one of the following holds:
      initialSize < 0 || maxSize < 1 || maxSize < initialSize
      NullPointerException - if available or poolObjectFactory are null

  • Method Details

    • take

      public T take()
      Description copied from interface: PoolService
      A counterpart of PoolService.take(long[]) that does not report back the time waited to obtain an object from the pool.
      Specified by:
      take in interface PoolService<T>
      Returns:
      an object taken from the object pool or null if was interrupted while waiting

    • take

      public T take(long[] waitedNanos)
      Description copied from interface: PoolService
      Takes an object from the object pool if there is such available. This is a blocking call that waits indefinitely until an object becomes available; the object may need to be created as described in PoolService.tryTake(long, TimeUnit, long[]). If the calling thread is interrupted while waiting this call will return null and the thread's interrupted status will be set to true.
      Specified by:
      take in interface PoolService<T>
      Parameters:
      waitedNanos - used to report the time waited, see PoolService.tryTake(long, TimeUnit, long[])
      Returns:
      an object taken from the object pool or null if it was interrupted while waiting

    • takeUninterruptibly

      public T takeUninterruptibly()
      Description copied from interface: PoolService
      A counterpart of PoolService.takeUninterruptibly(long[]) that does not report back the time waited to obtain an object from the pool.
      Specified by:
      takeUninterruptibly in interface PoolService<T>
      Returns:
      an object taken from the object pool

    • takeUninterruptibly

      public T takeUninterruptibly(long[] waitedNanos)
      Description copied from interface: PoolService
      Takes an object from the object pool if there is such available. This is a blocking call that waits indefinitely until an object becomes available; the object may need to be created as described in PoolService.tryTake(long, TimeUnit, long[]).
      Specified by:
      takeUninterruptibly in interface PoolService<T>
      Parameters:
      waitedNanos - used to report the time waited, see PoolService.tryTake(long, TimeUnit, long[])
      Returns:
      an object taken from the object pool

    • tryTake

      public T tryTake(long timeout, TimeUnit unit)
      Description copied from interface: PoolService
      A counterpart of PoolService.tryTake(long, TimeUnit, long[]) that does not report back the time waited to obtain an object from the pool.
      Specified by:
      tryTake in interface PoolService<T>
      Parameters:
      timeout - the maximum time to wait for an object to become available in the object pool; this timeout does not include the object creation time, see above
      unit - the time unit of the timeout argument
      Returns:
      an object taken from the object pool or null if the specified timeout expires or if it was interrupted while waiting

    • tryTake

      public T tryTake(long timeout, TimeUnit unit, long[] waitedNanos)
      Description copied from interface: PoolService
      Tries to take an object from the object pool if there is one available. This is a blocking call that waits for an object to become available up to the specified timeout. The real time spent waiting is reported back via the waitedNanos parameter. The total method execution time may also include the object creation time - an object can be (lazily) created in the pool when the pool capacity is not reached yet but no ready and valid object existed in the pool. If the calling thread is interrupted while waiting this call will return null and the thread's interrupted status will be set to true.
      Specified by:
      tryTake in interface PoolService<T>
      Parameters:
      timeout - the maximum time to wait for an object to become available in the object pool; this timeout does not include the object creation time
      unit - the time unit of the timeout argument
      waitedNanos - this parameter is used to report the nanoseconds time waited for an object to become available in the pool, excluding any object creation time; the time waited will be stored at index 0 of this array; the array must be of size of at least one
      Returns:
      an object taken from the object pool or null if the specified timeout expires or if it was interrupted while waiting

    • tryTake

      public T tryTake()
      Description copied from interface: PoolService
      Tries to take an object from the object pool if there is one that is immediately available; the object may need to be created as described in PoolService.tryTake(long, TimeUnit, long[]). Returns null if no object is available in the pool at the time of the call.
      Specified by:
      tryTake in interface PoolService<T>
      Returns:
      an object from the object pool or null if no object was available

    • restore

      public void restore(T object)
      Description copied from interface: PoolService
      Restores (returns) an object to the object pool. The object pool does not verify whether the currently restored object has been taken before that from this object pool or whether it is currently in taken state. Equivalent to calling restore(object, true).
      Specified by:
      restore in interface PoolService<T>
      Parameters:
      object - the object to be restored / returned

    • restore

      public void restore(T object, boolean valid)
      Description copied from interface: PoolService
      Restores (returns) an object to the object pool. The object pool does not verify whether the currently restored object has been taken before that from this object pool or whether it is currently in taken state.
      Specified by:
      restore in interface PoolService<T>
      Parameters:
      object - the object to be restored / returned
      valid - if false, the object is treated as invalid; otherwise a secondary validation on the object will be performed

    • listener

      public Listener<T> listener()
      Description copied from interface: PoolService
      Returns the Listener interface instance associated with this object pool, if any.
      Specified by:
      listener in interface PoolService<T>
      Returns:
      see above; null means no Listener is associated with this object pool.

    • taken

      public int taken()
      Description copied from interface: BasePool
      Returns the number of objects taken from this object pool. This number is less than or equal to the object pool BasePool.createdTotal(). Typically used for testing and debugging purposes.
      Specified by:
      taken in interface BasePool
      Returns:
      the number of objects taken from this object pool

    • remainingCreated

      public int remainingCreated()
      Description copied from interface: BasePool
      Returns the number of remaining created objects which are currently available in this object pool. This number is less than or equal to the object pool BasePool.remainingCapacity(). Typically used for testing and debugging purposes.
      Specified by:
      remainingCreated in interface BasePool
      Returns:
      the number of remaining created objects in this object pool

    • drainCreated

      public int drainCreated()
      Description copied from interface: BasePool
      Tries to remove (and destroy) as many created objects from this object pool as possible. May bring the object pool BasePool.createdTotal() to a number less than its BasePool.initialSize().
      Specified by:
      drainCreated in interface BasePool
      Returns:
      the actual amount of objects removed (and destroyed)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • createdTotal

      public int createdTotal()
      Description copied from interface: BasePool
      Returns the total number of created objects which currently exist for this object pool. This number is equal to BasePool.taken() + BasePool.remainingCreated(). Typically used for testing and debugging purposes.
      Specified by:
      createdTotal in interface BasePool
      Returns:
      the total number of created objects for this object pool

    • remainingCapacity

      public int remainingCapacity()
      Description copied from interface: BasePool
      Returns the remaining capacity of this object pool, i.e. the number of objects which could be taken from this object pool without blocking. It is not guaranteed that all these objects exist at the time of the call (i.e. are already created) in the object pool - some of them might be created on demand upon take requests. Also see BasePool.remainingCreated(). Typically used for testing and debugging purposes.
      Specified by:
      remainingCapacity in interface BasePool
      Returns:
      the object pool remaining capacity

    • initialSize

      public int initialSize()
      Description copied from interface: BasePool
      Returns the initialSize of this object pool at construction time. This parameter never changes.
      Specified by:
      initialSize in interface BasePool
      Returns:
      the object pool initialSize

    • maxSize

      public int maxSize()
      Description copied from interface: BasePool
      Returns the maxSize of this object pool. This parameter never changes.
      Specified by:
      maxSize in interface BasePool
      Returns:
      the object pool maxSize

    • reduceCreatedBy

      public int reduceCreatedBy(int reduceBy, boolean ignoreInitialSize)
      Description copied from interface: BasePool
      Tries to remove (and destroy) up to reduceBy objects from the object pool. This method may bring the object pool BasePool.createdTotal() to a number less than its BasePool.initialSize().
      Specified by:
      reduceCreatedBy in interface BasePool
      Parameters:
      reduceBy - the desired amount of objects to be removed
      ignoreInitialSize - specifies whether the BasePool.createdTotal() may be reduced to less than BasePool.initialSize()
      Returns:
      the actual amount of objects removed

    • reduceCreatedTo

      public int reduceCreatedTo(int reduceTo, boolean ignoreInitialSize)
      Description copied from interface: BasePool
      Tries to remove (and destroy) such number of objects from the object pool that the number of BasePool.createdTotal() objects in the pool to become equal of reduceTo. This method may bring the object pool BasePool.createdTotal() to a number smaller than its BasePool.initialSize().
      Specified by:
      reduceCreatedTo in interface BasePool
      Parameters:
      reduceTo - the desired amount of created objects to remain in the pool
      ignoreInitialSize - specifies whether the BasePool.createdTotal() may be reduced to less than BasePool.initialSize()
      Returns:
      the actual amount of objects removed

    • terminate

      public void terminate()
      Description copied from interface: BasePool
      Terminates this object pool. Once terminated the object pool cannot be more revived. All take and restore operations called on a terminated object pool should throw an exception or be ignored. This method can be invoked multiple times.
      Specified by:
      terminate in interface BasePool

    • close

      public void close()
      Description copied from interface: BasePool
      A synonym for BasePool.terminate(). Overrides the AutoCloseable's method in order to overrule the throwing of a checked Exception.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface BasePool

    • isTerminated

      public boolean isTerminated()
      Description copied from interface: BasePool
      Returns the current terminated state of this object pool.
      Specified by:
      isTerminated in interface BasePool
      Returns:
      true if the object pool is terminated; false otherwise

    • isFair

      public boolean isFair()
      Description copied from interface: PoolService
      Returns the fairness setting of this object pool.
      Specified by:
      isFair in interface PoolService<T>
      Returns:
      true if the object pool is fair to waiting taker threads