/*

 * 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.

 * 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();

 *   }

 *

 * <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);

}