/**
 * Generic object {@link Pool}.
 *
 * @param <O> the type of objects <i>this</i> {@link Pool} can hold
 */
public interface BlockingPool<O> extends Iterable<O> {

  /**
   * @return the next available {@link O} object from <i>this</i> {@link Pool}
   * or {@code null} if currently there is no available objects
   */
  O poll();

  /**
   * @return the next available {@link O} object from <i>this</i>
   * {@link BlockingPool}
   *
   * @throws InterruptedException if the thread waiting to take the next
   * available {@link O} object gets interrupted
   */
  O take() throws InterruptedException;

  /**
   * @param timeout the maximum time to wait for being able to take the next
   * available {@link O} object from <i>this</i> {@link BlockingPool}
   * @param unit the unit of {@code timeout}
   *
   * @return the next available {@link O} object from <i>this</i>
   * {@link BlockingPool}
   *
   * @throws InterruptedException if the thread waiting to take the next
   * available {@link O} object gets interrupted
   */
  O take(long timeout, TimeUnit unit) throws InterruptedException;

  /**
   * @param object the {@link O} object (previously taken from here) to be
   * returned to <i>this</i> {@link Pool}
   *
   * @throws IllegalStateException if {@code element} wasn't taken from
   * <i>this</i> {@link Pool}
   */
  void put(O object);

  /**
   * @param object the {@link O} object (previously taken from here) to be
   * discarded from <i>this</i> {@link Pool}
   *
   * @throws IllegalStateException if {@code element} wasn't taken from
   * <i>this</i> {@link Pool}
   */
  void discard(O object);

  /**
   * @return an unmodifiable {@link Iterator} over the {@link O} objects of
   * <i>this</i> {@link Pool} (whether those are currently taken or not)
   */
  @Override
  Iterator<O> iterator();
}