Package org.vibur.objectpool

Interface PoolService<T>

Type Parameters:
T - the type of objects held in this object pool
All Superinterfaces:
AutoCloseable, BasePool
All Known Implementing Classes:
ConcurrentPool
public interface PoolService<T> extends BasePool
Defines the object pool operations. These operations include the take and restore pool methods.

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 may lazily create an object upon take request; not all objects need to exist and be valid in the pool at all times. The restore 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 object pool implementation may support an optional fairness parameter (usually provided via the pool constructor) that defines the pool behaviour with regard to waiting takers threads, as well as an optional Listener interface which methods will be called when a take or restore pool method executes.

The pool cannot contain null objects.

Author:
Simeon Malchev

  • Method Details

    • take

      T take()
      A counterpart of take(long[]) that does not report back the time waited to obtain an object from the pool.
      Returns:
      an object taken from the object pool or null if was interrupted while waiting

    • take

      T take(long[] waitedNanos)
      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 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.
      Parameters:
      waitedNanos - used to report the time waited, see tryTake(long, TimeUnit, long[])
      Returns:
      an object taken from the object pool or null if it was interrupted while waiting

    • takeUninterruptibly

      T takeUninterruptibly()
      A counterpart of takeUninterruptibly(long[]) that does not report back the time waited to obtain an object from the pool.
      Returns:
      an object taken from the object pool

    • takeUninterruptibly

      T takeUninterruptibly(long[] waitedNanos)
      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 tryTake(long, TimeUnit, long[]).
      Parameters:
      waitedNanos - used to report the time waited, see tryTake(long, TimeUnit, long[])
      Returns:
      an object taken from the object pool

    • tryTake

      T tryTake(long timeout, TimeUnit unit)
      A counterpart of tryTake(long, TimeUnit, long[]) that does not report back the time waited to obtain an object from the pool.
      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

      T tryTake(long timeout, TimeUnit unit, long[] waitedNanos)
      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.
      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

      T tryTake()
      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 tryTake(long, TimeUnit, long[]). Returns null if no object is available in the pool at the time of the call.
      Returns:
      an object from the object pool or null if no object was available

    • restore

      void restore(T object)
      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).
      Parameters:
      object - the object to be restored / returned
      Throws:
      NullPointerException - if the given object is null

    • restore

      void restore(T object, boolean valid)
      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.
      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
      Throws:
      NullPointerException - if the given object is null

    • listener

      Listener<T> listener()
      Returns the Listener interface instance associated with this object pool, if any.
      Returns:
      see above; null means no Listener is associated with this object pool.

    • isFair

      boolean isFair()
      Returns the fairness setting of this object pool.
      Returns:
      true if the object pool is fair to waiting taker threads