/*

  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

  *

  * This code is free software; you can redistribute it and/or modify it

  * under the terms of the GNU General Public License version 2 only, as

  * published by the Free Software Foundation.  Oracle designates this

  * particular file as subject to the "Classpath" exception as provided

  * by Oracle in the LICENSE file that accompanied this code.

  *

  * This code is distributed in the hope that it will be useful, but WITHOUT

  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

  * version 2 for more details (a copy is included in the LICENSE file that

  * accompanied this code).

  *

  * You should have received a copy of the GNU General Public License version

  * 2 along with this work; if not, write to the Free Software Foundation,

  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  *

  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

  * or visit www.oracle.com if you need additional information or have any

  * questions.

  */

 /*

  * This file is available under and governed by the GNU General Public

  * License version 2 only, as published by the Free Software Foundation.

  * However, the following notice accompanied the original version of this

  * file:

  *

  * Written by Doug Lea with assistance from members of JCP JSR-166

  * Expert Group and released to the public domain, as explained at

  * http://creativecommons.org/publicdomain/zero/1.0/

  */

 package java.util.concurrent;

 import java.util.Collection;

 import java.util.Queue;

 /**

  * A {@link java.util.Queue} that additionally supports operations

  * that wait for the queue to become non-empty when retrieving an

  * element, and wait for space to become available in the queue when

  * storing an element.

  *

  * <p><tt>BlockingQueue</tt> methods come in four forms, with different ways

  * of handling operations that cannot be satisfied immediately, but may be

  * satisfied at some point in the future:

  * one throws an exception, the second returns a special value (either

  * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third

  * blocks the current thread indefinitely until the operation can succeed,

  * and the fourth blocks for only a given maximum time limit before giving

  * up.  These methods are summarized in the following table:

  *

  * <p>

  * <table BORDER CELLPADDING=3 CELLSPACING=1>

  *  <tr>

  *    <td></td>

  *    <td ALIGN=CENTER><em>Throws exception</em></td>

  *    <td ALIGN=CENTER><em>Special value</em></td>

  *    <td ALIGN=CENTER><em>Blocks</em></td>

  *    <td ALIGN=CENTER><em>Times out</em></td>

  *  </tr>

  *  <tr>

  *    <td><b>Insert</b></td>

  *    <td>{@link #add add(e)}</td>

  *    <td>{@link #offer offer(e)}</td>

  *    <td>{@link #put put(e)}</td>

  *    <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>

  *  </tr>

  *  <tr>

  *    <td><b>Remove</b></td>

  *    <td>{@link #remove remove()}</td>

  *    <td>{@link #poll poll()}</td>

  *    <td>{@link #take take()}</td>

  *    <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>

  *  </tr>

  *  <tr>

  *    <td><b>Examine</b></td>

  *    <td>{@link #element element()}</td>

  *    <td>{@link #peek peek()}</td>

  *    <td><em>not applicable</em></td>

  *    <td><em>not applicable</em></td>

  *  </tr>

  * </table>

  *

  * <p>A <tt>BlockingQueue</tt> does not accept <tt>null</tt> elements.

  * Implementations throw <tt>NullPointerException</tt> on attempts

  * to <tt>add</tt>, <tt>put</tt> or <tt>offer</tt> a <tt>null</tt>.  A

  * <tt>null</tt> is used as a sentinel value to indicate failure of

  * <tt>poll</tt> operations.

  *

  * <p>A <tt>BlockingQueue</tt> may be capacity bounded. At any given

  * time it may have a <tt>remainingCapacity</tt> beyond which no

  * additional elements can be <tt>put</tt> without blocking.

  * A <tt>BlockingQueue</tt> without any intrinsic capacity constraints always

  * reports a remaining capacity of <tt>Integer.MAX_VALUE</tt>.

  *

  * <p> <tt>BlockingQueue</tt> implementations are designed to be used

  * primarily for producer-consumer queues, but additionally support

  * the {@link java.util.Collection} interface.  So, for example, it is

  * possible to remove an arbitrary element from a queue using

  * <tt>remove(x)</tt>. However, such operations are in general

  * <em>not</em> performed very efficiently, and are intended for only

  * occasional use, such as when a queued message is cancelled.

  *

  * <p> <tt>BlockingQueue</tt> implementations are thread-safe.  All

  * queuing methods achieve their effects atomically using internal

  * locks or other forms of concurrency control. However, the

  * <em>bulk</em> Collection operations <tt>addAll</tt>,

  * <tt>containsAll</tt>, <tt>retainAll</tt> and <tt>removeAll</tt> are

  * <em>not</em> necessarily performed atomically unless specified

  * otherwise in an implementation. So it is possible, for example, for

  * <tt>addAll(c)</tt> to fail (throwing an exception) after adding

  * only some of the elements in <tt>c</tt>.

  *

  * <p>A <tt>BlockingQueue</tt> does <em>not</em> intrinsically support

  * any kind of "close" or "shutdown" operation to

  * indicate that no more items will be added.  The needs and usage of

  * such features tend to be implementation-dependent. For example, a

  * common tactic is for producers to insert special

  * <em>end-of-stream</em> or <em>poison</em> objects, that are

  * interpreted accordingly when taken by consumers.

  *

  * <p>

  * Usage example, based on a typical producer-consumer scenario.

  * Note that a <tt>BlockingQueue</tt> can safely be used with multiple

  * producers and multiple consumers.

  * <pre>

  * class Producer implements Runnable {

  *   private final BlockingQueue queue;

  *   Producer(BlockingQueue q) { queue = q; }

  *   public void run() {

  *     try {

  *       while (true) { queue.put(produce()); }

  *     } catch (InterruptedException ex) { ... handle ...}

  *   }

  *   Object produce() { ... }

  * }

  *

  * class Consumer implements Runnable {

  *   private final BlockingQueue queue;

  *   Consumer(BlockingQueue q) { queue = q; }

  *   public void run() {

  *     try {

  *       while (true) { consume(queue.take()); }

  *     } catch (InterruptedException ex) { ... handle ...}

  *   }

  *   void consume(Object x) { ... }

  * }

  *

  * class Setup {

  *   void main() {

  *     BlockingQueue q = new SomeQueueImplementation();

  *     Producer p = new Producer(q);

  *     Consumer c1 = new Consumer(q);

  *     Consumer c2 = new Consumer(q);

  *     new Thread(p).start();

  *     new Thread(c1).start();

  *     new Thread(c2).start();

  *   }

  * }

  * </pre>

  *

  * <p>Memory consistency effects: As with other concurrent

  * collections, actions in a thread prior to placing an object into a

  * {@code BlockingQueue}

  * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>

  * actions subsequent to the access or removal of that element from

  * the {@code BlockingQueue} in another thread.

  *

  * <p>This interface is a member of the

  * <a href="{@docRoot}/../technotes/guides/collections/index.html">

  * Java Collections Framework</a>.

  *

  * @since 1.5

  * @author Doug Lea

  * @param <E> the type of elements held in this collection

  */

 public interface BlockingQueue<E> extends Queue<E> {

     /**

      * Inserts the specified element into this queue if it is possible to do

      * so immediately without violating capacity restrictions, returning

      * <tt>true</tt> upon success and throwing an

      * <tt>IllegalStateException</tt> if no space is currently available.

      * When using a capacity-restricted queue, it is generally preferable to

      * use {@link #offer(Object) offer}.

      *

      * @param e the element to add

      * @return <tt>true</tt> (as specified by {@link Collection#add})

      * @throws IllegalStateException if the element cannot be added at this

      *         time due to capacity restrictions

      * @throws ClassCastException if the class of the specified element

      *         prevents it from being added to this queue

      * @throws NullPointerException if the specified element is null

      * @throws IllegalArgumentException if some property of the specified

      *         element prevents it from being added to this queue

      */

     boolean add(E e);

     /**

      * Inserts the specified element into this queue if it is possible to do

      * so immediately without violating capacity restrictions, returning

      * <tt>true</tt> upon success and <tt>false</tt> if no space is currently

      * available.  When using a capacity-restricted queue, this method is

      * generally preferable to {@link #add}, which can fail to insert an

      * element only by throwing an exception.

      *

      * @param e the element to add

      * @return <tt>true</tt> if the element was added to this queue, else

      *         <tt>false</tt>

      * @throws ClassCastException if the class of the specified element

      *         prevents it from being added to this queue

      * @throws NullPointerException if the specified element is null

      * @throws IllegalArgumentException if some property of the specified

      *         element prevents it from being added to this queue

      */

     boolean offer(E e);

     /**

      * Inserts the specified element into this queue, waiting if necessary

      * for space to become available.

      *

      * @param e the element to add

      * @throws InterruptedException if interrupted while waiting

      * @throws ClassCastException if the class of the specified element

      *         prevents it from being added to this queue

      * @throws NullPointerException if the specified element is null

      * @throws IllegalArgumentException if some property of the specified

      *         element prevents it from being added to this queue

      */

     void put(E e) throws InterruptedException;

     /**

      * Inserts the specified element into this queue, waiting up to the

      * specified wait time if necessary for space to become available.

      *

      * @param e the element to add

      * @param timeout how long to wait before giving up, in units of

      *        <tt>unit</tt>

      * @param unit a <tt>TimeUnit</tt> determining how to interpret the

      *        <tt>timeout</tt> parameter

      * @return <tt>true</tt> if successful, or <tt>false</tt> if

      *         the specified waiting time elapses before space is available

      * @throws InterruptedException if interrupted while waiting

      * @throws ClassCastException if the class of the specified element

      *         prevents it from being added to this queue

      * @throws NullPointerException if the specified element is null

      * @throws IllegalArgumentException if some property of the specified

      *         element prevents it from being added to this queue

      */

     boolean offer(E e, long timeout, TimeUnit unit)

         throws InterruptedException;

     /**

      * Retrieves and removes the head of this queue, waiting if necessary

      * until an element becomes available.

      *

      * @return the head of this queue

      * @throws InterruptedException if interrupted while waiting

      */

     E take() throws InterruptedException;

     /**

      * Retrieves and removes the head of this queue, waiting up to the

      * specified wait time if necessary for an element to become available.

      *

      * @param timeout how long to wait before giving up, in units of

      *        <tt>unit</tt>

      * @param unit a <tt>TimeUnit</tt> determining how to interpret the

      *        <tt>timeout</tt> parameter

      * @return the head of this queue, or <tt>null</tt> if the

      *         specified waiting time elapses before an element is available

      * @throws InterruptedException if interrupted while waiting

      */

     E poll(long timeout, TimeUnit unit)

         throws InterruptedException;

     /**

      * Returns the number of additional elements that this queue can ideally

      * (in the absence of memory or resource constraints) accept without

      * blocking, or <tt>Integer.MAX_VALUE</tt> if there is no intrinsic

      * limit.

      *

      * <p>Note that you <em>cannot</em> always tell if an attempt to insert

      * an element will succeed by inspecting <tt>remainingCapacity</tt>

      * because it may be the case that another thread is about to

      * insert or remove an element.

      *

      * @return the remaining capacity

      */

     int remainingCapacity();

     /**

      * Removes a single instance of the specified element from this queue,

      * if it is present.  More formally, removes an element <tt>e</tt> such

      * that <tt>o.equals(e)</tt>, if this queue contains one or more such

      * elements.

      * Returns <tt>true</tt> if this queue contained the specified element

      * (or equivalently, if this queue changed as a result of the call).

      *

      * @param o element to be removed from this queue, if present

      * @return <tt>true</tt> if this queue changed as a result of the call

      * @throws ClassCastException if the class of the specified element

      *         is incompatible with this queue

      *         (<a href="../Collection.html#optional-restrictions">optional</a>)

      * @throws NullPointerException if the specified element is null

      *         (<a href="../Collection.html#optional-restrictions">optional</a>)

      */

     boolean remove(Object o);

     /**

      * Returns <tt>true</tt> if this queue contains the specified element.

      * More formally, returns <tt>true</tt> if and only if this queue contains

      * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.

      *

      * @param o object to be checked for containment in this queue

      * @return <tt>true</tt> if this queue contains the specified element

      * @throws ClassCastException if the class of the specified element

      *         is incompatible with this queue

      *         (<a href="../Collection.html#optional-restrictions">optional</a>)

      * @throws NullPointerException if the specified element is null

      *         (<a href="../Collection.html#optional-restrictions">optional</a>)

      */

     public boolean contains(Object o);

     /**

      * Removes all available elements from this queue and adds them

      * to the given collection.  This operation may be more

      * efficient than repeatedly polling this queue.  A failure

      * encountered while attempting to add elements to

      * collection <tt>c</tt> may result in elements being in neither,

      * either or both collections when the associated exception is

      * thrown.  Attempts to drain a queue to itself result in

      * <tt>IllegalArgumentException</tt>. Further, the behavior of

      * this operation is undefined if the specified collection is

      * modified while the operation is in progress.

      *

      * @param c the collection to transfer elements into

      * @return the number of elements transferred

      * @throws UnsupportedOperationException if addition of elements

      *         is not supported by the specified collection

      * @throws ClassCastException if the class of an element of this queue

      *         prevents it from being added to the specified collection

      * @throws NullPointerException if the specified collection is null

      * @throws IllegalArgumentException if the specified collection is this

      *         queue, or some property of an element of this queue prevents

      *         it from being added to the specified collection

      */

     int drainTo(Collection<? super E> c);

     /**

      * Removes at most the given number of available elements from

      * this queue and adds them to the given collection.  A failure

      * encountered while attempting to add elements to

      * collection <tt>c</tt> may result in elements being in neither,

      * either or both collections when the associated exception is

      * thrown.  Attempts to drain a queue to itself result in

      * <tt>IllegalArgumentException</tt>. Further, the behavior of

      * this operation is undefined if the specified collection is

      * modified while the operation is in progress.

      *

      * @param c the collection to transfer elements into

      * @param maxElements the maximum number of elements to transfer

      * @return the number of elements transferred

      * @throws UnsupportedOperationException if addition of elements

      *         is not supported by the specified collection

      * @throws ClassCastException if the class of an element of this queue

      *         prevents it from being added to the specified collection

      * @throws NullPointerException if the specified collection is null

      * @throws IllegalArgumentException if the specified collection is this

      *         queue, or some property of an element of this queue prevents

      *         it from being added to the specified collection

      */

     int drainTo(Collection<? super E> c, int maxElements);

 }