jaroslav@1890: /*
jaroslav@1890:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
jaroslav@1890:  *
jaroslav@1890:  * This code is free software; you can redistribute it and/or modify it
jaroslav@1890:  * under the terms of the GNU General Public License version 2 only, as
jaroslav@1890:  * published by the Free Software Foundation.  Oracle designates this
jaroslav@1890:  * particular file as subject to the "Classpath" exception as provided
jaroslav@1890:  * by Oracle in the LICENSE file that accompanied this code.
jaroslav@1890:  *
jaroslav@1890:  * This code is distributed in the hope that it will be useful, but WITHOUT
jaroslav@1890:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
jaroslav@1890:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
jaroslav@1890:  * version 2 for more details (a copy is included in the LICENSE file that
jaroslav@1890:  * accompanied this code).
jaroslav@1890:  *
jaroslav@1890:  * You should have received a copy of the GNU General Public License version
jaroslav@1890:  * 2 along with this work; if not, write to the Free Software Foundation,
jaroslav@1890:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
jaroslav@1890:  *
jaroslav@1890:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
jaroslav@1890:  * or visit www.oracle.com if you need additional information or have any
jaroslav@1890:  * questions.
jaroslav@1890:  */
jaroslav@1890: 
jaroslav@1890: /*
jaroslav@1890:  * This file is available under and governed by the GNU General Public
jaroslav@1890:  * License version 2 only, as published by the Free Software Foundation.
jaroslav@1890:  * However, the following notice accompanied the original version of this
jaroslav@1890:  * file:
jaroslav@1890:  *
jaroslav@1890:  * Written by Doug Lea with assistance from members of JCP JSR-166
jaroslav@1890:  * Expert Group and released to the public domain, as explained at
jaroslav@1890:  * http://creativecommons.org/publicdomain/zero/1.0/
jaroslav@1890:  */
jaroslav@1890: 
jaroslav@1890: package java.util.concurrent;
jaroslav@1890: 
jaroslav@1890: /**
jaroslav@1890:  * A {@link BlockingQueue} in which producers may wait for consumers
jaroslav@1890:  * to receive elements.  A {@code TransferQueue} may be useful for
jaroslav@1890:  * example in message passing applications in which producers
jaroslav@1890:  * sometimes (using method {@link #transfer}) await receipt of
jaroslav@1890:  * elements by consumers invoking {@code take} or {@code poll}, while
jaroslav@1890:  * at other times enqueue elements (via method {@code put}) without
jaroslav@1890:  * waiting for receipt.
jaroslav@1890:  * {@linkplain #tryTransfer(Object) Non-blocking} and
jaroslav@1890:  * {@linkplain #tryTransfer(Object,long,TimeUnit) time-out} versions of
jaroslav@1890:  * {@code tryTransfer} are also available.
jaroslav@1890:  * A {@code TransferQueue} may also be queried, via {@link
jaroslav@1890:  * #hasWaitingConsumer}, whether there are any threads waiting for
jaroslav@1890:  * items, which is a converse analogy to a {@code peek} operation.
jaroslav@1890:  *
jaroslav@1890:  * <p>Like other blocking queues, a {@code TransferQueue} may be
jaroslav@1890:  * capacity bounded.  If so, an attempted transfer operation may
jaroslav@1890:  * initially block waiting for available space, and/or subsequently
jaroslav@1890:  * block waiting for reception by a consumer.  Note that in a queue
jaroslav@1890:  * with zero capacity, such as {@link SynchronousQueue}, {@code put}
jaroslav@1890:  * and {@code transfer} are effectively synonymous.
jaroslav@1890:  *
jaroslav@1890:  * <p>This interface is a member of the
jaroslav@1890:  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
jaroslav@1890:  * Java Collections Framework</a>.
jaroslav@1890:  *
jaroslav@1890:  * @since 1.7
jaroslav@1890:  * @author Doug Lea
jaroslav@1890:  * @param <E> the type of elements held in this collection
jaroslav@1890:  */
jaroslav@1890: public interface TransferQueue<E> extends BlockingQueue<E> {
jaroslav@1890:     /**
jaroslav@1890:      * Transfers the element to a waiting consumer immediately, if possible.
jaroslav@1890:      *
jaroslav@1890:      * <p>More precisely, transfers the specified element immediately
jaroslav@1890:      * if there exists a consumer already waiting to receive it (in
jaroslav@1890:      * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
jaroslav@1890:      * otherwise returning {@code false} without enqueuing the element.
jaroslav@1890:      *
jaroslav@1890:      * @param e the element to transfer
jaroslav@1890:      * @return {@code true} if the element was transferred, else
jaroslav@1890:      *         {@code false}
jaroslav@1890:      * @throws ClassCastException if the class of the specified element
jaroslav@1890:      *         prevents it from being added to this queue
jaroslav@1890:      * @throws NullPointerException if the specified element is null
jaroslav@1890:      * @throws IllegalArgumentException if some property of the specified
jaroslav@1890:      *         element prevents it from being added to this queue
jaroslav@1890:      */
jaroslav@1890:     boolean tryTransfer(E e);
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Transfers the element to a consumer, waiting if necessary to do so.
jaroslav@1890:      *
jaroslav@1890:      * <p>More precisely, transfers the specified element immediately
jaroslav@1890:      * if there exists a consumer already waiting to receive it (in
jaroslav@1890:      * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
jaroslav@1890:      * else waits until the element is received by a consumer.
jaroslav@1890:      *
jaroslav@1890:      * @param e the element to transfer
jaroslav@1890:      * @throws InterruptedException if interrupted while waiting,
jaroslav@1890:      *         in which case the element is not left enqueued
jaroslav@1890:      * @throws ClassCastException if the class of the specified element
jaroslav@1890:      *         prevents it from being added to this queue
jaroslav@1890:      * @throws NullPointerException if the specified element is null
jaroslav@1890:      * @throws IllegalArgumentException if some property of the specified
jaroslav@1890:      *         element prevents it from being added to this queue
jaroslav@1890:      */
jaroslav@1890:     void transfer(E e) throws InterruptedException;
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Transfers the element to a consumer if it is possible to do so
jaroslav@1890:      * before the timeout elapses.
jaroslav@1890:      *
jaroslav@1890:      * <p>More precisely, transfers the specified element immediately
jaroslav@1890:      * if there exists a consumer already waiting to receive it (in
jaroslav@1890:      * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
jaroslav@1890:      * else waits until the element is received by a consumer,
jaroslav@1890:      * returning {@code false} if the specified wait time elapses
jaroslav@1890:      * before the element can be transferred.
jaroslav@1890:      *
jaroslav@1890:      * @param e the element to transfer
jaroslav@1890:      * @param timeout how long to wait before giving up, in units of
jaroslav@1890:      *        {@code unit}
jaroslav@1890:      * @param unit a {@code TimeUnit} determining how to interpret the
jaroslav@1890:      *        {@code timeout} parameter
jaroslav@1890:      * @return {@code true} if successful, or {@code false} if
jaroslav@1890:      *         the specified waiting time elapses before completion,
jaroslav@1890:      *         in which case the element is not left enqueued
jaroslav@1890:      * @throws InterruptedException if interrupted while waiting,
jaroslav@1890:      *         in which case the element is not left enqueued
jaroslav@1890:      * @throws ClassCastException if the class of the specified element
jaroslav@1890:      *         prevents it from being added to this queue
jaroslav@1890:      * @throws NullPointerException if the specified element is null
jaroslav@1890:      * @throws IllegalArgumentException if some property of the specified
jaroslav@1890:      *         element prevents it from being added to this queue
jaroslav@1890:      */
jaroslav@1890:     boolean tryTransfer(E e, long timeout, TimeUnit unit)
jaroslav@1890:         throws InterruptedException;
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Returns {@code true} if there is at least one consumer waiting
jaroslav@1890:      * to receive an element via {@link #take} or
jaroslav@1890:      * timed {@link #poll(long,TimeUnit) poll}.
jaroslav@1890:      * The return value represents a momentary state of affairs.
jaroslav@1890:      *
jaroslav@1890:      * @return {@code true} if there is at least one waiting consumer
jaroslav@1890:      */
jaroslav@1890:     boolean hasWaitingConsumer();
jaroslav@1890: 
jaroslav@1890:     /**
jaroslav@1890:      * Returns an estimate of the number of consumers waiting to
jaroslav@1890:      * receive elements via {@link #take} or timed
jaroslav@1890:      * {@link #poll(long,TimeUnit) poll}.  The return value is an
jaroslav@1890:      * approximation of a momentary state of affairs, that may be
jaroslav@1890:      * inaccurate if consumers have completed or given up waiting.
jaroslav@1890:      * The value may be useful for monitoring and heuristics, but
jaroslav@1890:      * not for synchronization control.  Implementations of this
jaroslav@1890:      * method are likely to be noticeably slower than those for
jaroslav@1890:      * {@link #hasWaitingConsumer}.
jaroslav@1890:      *
jaroslav@1890:      * @return the number of consumers waiting to receive elements
jaroslav@1890:      */
jaroslav@1890:     int getWaitingConsumerCount();
jaroslav@1890: }