package stormpot;

/**
 * An Allocator is responsible for the creation and destruction of Poolable
 * objects.
 * <p>
 * This is where the objects in the Pool comes from. Clients of the Stormpot
 * library needs to provide their own Allocator implementations.
 * <p>
 * Implementations of this interface must be thread-safe, because there is no
 * knowing whether pools will try to access it concurrently or not. Generally
 * they will probably not access it concurrently, but since no guarantee can
 * be provided one has expect that concurrent access might occur. The easiest
 * way to achieve this is to just make the
 * {@link Allocator#allocate(Slot) allocate}
 * and {@link Allocator#deallocate(Poolable) deallocate} methods synchronised.
 * @author Chris Vest <mr.chrisvest@gmail.com>
 *
 * @param <T> any type that implements Poolable.
 */
public interface Allocator<T extends Poolable> {

  /**
   * Create a fresh new instance of T for the given slot.
   * <p>
   * The returned {@link Poolable} must obey the contract that, when
   * {@link Poolable#release() release} is called on it, it must delegate
   * the call onto the {@link Slot#release() release} method of the here
   * given slot object.
   * @param slot The slot the pool wish to allocate an object for.
   * Implementors 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.
   * @return A newly created instance of T.
   */
  T allocate(Slot slot);

  /**
   * Deallocate, if applicable, the given Poolable and free any resources
   * associated with it.
   * <p>
   * 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.
   * <p>
   * Note that a Poolable must never touch its slot object after it has been
   * deallocated.
   * <p>
   * Pools, on the other hand, will guarantee that the same object is never
   * deallocated more than once.
   * @param poolable a non-null Poolable instance to be deallocated.
   */
  void deallocate(T poolable);
}
@@ -1204,16 +1204,406 @@
 object.%0A
+   * %3Cp%3E%0A   * RuntimeExceptions thrown by this method may propagate out through the%0A   * %7B@link Pool#claim() claim%7D method of a pool, in the form of being wrapped%0A   * inside a %7B@link PoolException%7D. Pools must be able to handle these%0A   * exceptions in a sane manner, and are guaranteed to return to a working%0A   * state if an Allocator stops throwing exceptions from its allocate method.%0A
    * @pa
@@ -2440,16 +2440,915 @@
 n once.%0A
+   * %3Cp%3E%0A   * Note that pools will always silently swallow exceptions thrown by the%0A   * deallocate method. They do this because there is no knowing whether the%0A   * deallocation of an object will be done synchronously by a thread calling%0A   * %7B@link Poolable#release() release%7D on a Poolable, or asynchronously by%0A   * a clean-up thread inside the pool.%0A   * %3Cp%3E%0A   * Deallocation from the release of an expired object, and deallocation from%0A   * the shut down procedure of a %7B@link LifecycledPool%7D behave the same way%0A   * in this regard. They will both silently swallow any exception thrown.%0A   * %3Cp%3E%0A   * On the other hand, pools are guaranteed to otherwise correctly deal with%0A   * any exception that might be thrown. The shut down procedure will still%0A   * complete, and release will still maintain the internal data structures of%0A   * the pool to make the slot available for new allocations.%0A
    * @pa

document what it means to throw an exception from an Allocator method.