Module stormpot
Package stormpot.internal

Class ReallocatingAdaptor<T extends Poolable>

java.lang.Object
stormpot.internal.ReallocatingAdaptor<T>
Type Parameters:
T - The concrete poolable type.
All Implemented Interfaces:
Allocator<T>, Reallocator<T>
public class ReallocatingAdaptor<T extends Poolable> extends Object implements Reallocator<T>
An adaptor that implements Reallocator in terms of a given Allocator.

  • Constructor Details

    • ReallocatingAdaptor

      public ReallocatingAdaptor(Allocator<T> allocator)
      Adapt the given Allocator into a Reallocator.
      Parameters:
      allocator - The allocator to adapt.

  • Method Details

    • reallocate

      public T reallocate(Slot slot, T poolable) throws Exception
      Description copied from interface: Reallocator
      Possibly reallocate the given instance of T for the given slot, and return it if the reallocation was successful, or a fresh replacement if the instance could not be reallocated.

      This method is effectively equivalent to the following: 

      deallocate(poolable);
return allocate(slot);
      With the only difference that it may, if possible, reuse the given expired Poolable, either wholly or in part.

      The state stored in the SlotInfo for the object is reset upon reallocation, just like it would be in the case of a normal deallocation-allocation cycle.

      Exceptions thrown by this method may propagate out through the claim method of a pool, in the form of being wrapped inside a PoolException. Pools must be able to handle these exceptions in a sane manner, and are guaranteed to return to a working state if a Reallocator stops throwing exceptions from its reallocate method.

      Be aware that if the reallocation of an object fails with an exception, then no attempts will be made to explicitly deallocate that object. This way, a failed reallocation is implicitly understood to effectively be a successful deallocation.

      Specified by:
      reallocate in interface Reallocator<T extends Poolable>
      Parameters:
      slot - The slot the pool wish to allocate an object for. Implementers do not need to concern themselves with the details of a pools slot objects. They just have to call release on them as the protocol demands.
      poolable - The non-null Poolable instance to be reallocated.
      Returns:
      A fresh or rejuvenated instance of T. Never null.
      Throws:
      Exception - If the allocation fails.
      See Also:

    • allocate

      public T allocate(Slot slot) throws Exception
      Description copied from interface: Allocator
      Create a fresh new instance of T for the given slot.

      The returned Poolable must obey the contract that, when Poolable.release() is called on it, it must delegate the call onto the Slot.release(Poolable) method of the here given slot object.

      Exceptions thrown by this method may propagate out through the claim method of a pool, in the form of being wrapped inside a PoolException. Pools must be able to handle these exceptions in a sane manner, and are guaranteed to return to a working state if an Allocator stops throwing exceptions from its allocate method.

      Specified by:
      allocate in interface Allocator<T extends Poolable>
      Parameters:
      slot - The slot the pool wish to allocate an object for. Implementers do not need to concern themselves with the details of a pools slot objects. They just have to call release on them as the protocol demands.
      Returns:
      A newly created instance of T. Never null.
      Throws:
      Exception - If the allocation fails.

    • deallocate

      public void deallocate(T poolable) throws Exception
      Description copied from interface: Allocator
      Deallocate, if applicable, the given Poolable and free any resources associated with it.

      This is an opportunity to close any connections or files, flush buffers, empty caches or what ever might need to be done to completely free any resources represented by this Poolable.

      Note that a Poolable must never touch its slot object after it has been deallocated.

      Pools, on the other hand, will guarantee that the same object is never deallocated more than once.

      Note that pools will always silently swallow exceptions thrown by the deallocate method. They do this because there is no knowing whether the deallocation of an object will be done synchronously by a thread calling release on a Poolable, or asynchronously by a clean-up thread inside the pool.

      Deallocation from the release of an expired object, and deallocation from the shutdown procedure of a Pool behave the same way in this regard. They will both silently swallow any exception thrown.

      On the other hand, pools are guaranteed to otherwise correctly deal with any exception that might be thrown. The shutdown procedure will still complete, and release will still maintain the internal data structures of the pool to make the slot available for new allocations.

      If you need to somehow specially deal with the exceptions thrown by the deallocation of objects, then you should do this in the allocator itself, or in a wrapper around your allocator.

      Specified by:
      deallocate in interface Allocator<T extends Poolable>
      Parameters:
      poolable - The non-null Poolable instance to be deallocated.
      Throws:
      Exception - if the deallocation encounters an error.

    • unwrap

      public Allocator<T> unwrap()
      Unwrap this adaptor to reveal the underlying Allocator.
      Returns:
      The allocator adapted by this reallocator.