41  * example in message passing applications in which producers
  42  * sometimes (using method {@link #transfer}) await receipt of
  43  * elements by consumers invoking {@code take} or {@code poll}, while
  44  * at other times enqueue elements (via method {@code put}) without
  45  * waiting for receipt.
  46  * {@linkplain #tryTransfer(Object) Non-blocking} and
  47  * {@linkplain #tryTransfer(Object,long,TimeUnit) time-out} versions of
  48  * {@code tryTransfer} are also available.
  49  * A {@code TransferQueue} may also be queried, via {@link
  50  * #hasWaitingConsumer}, whether there are any threads waiting for
  51  * items, which is a converse analogy to a {@code peek} operation.
  52  *
  53  * <p>Like other blocking queues, a {@code TransferQueue} may be
  54  * capacity bounded.  If so, an attempted transfer operation may
  55  * initially block waiting for available space, and/or subsequently
  56  * block waiting for reception by a consumer.  Note that in a queue
  57  * with zero capacity, such as {@link SynchronousQueue}, {@code put}
  58  * and {@code transfer} are effectively synonymous.
  59  *
  60  * <p>This interface is a member of the
  61  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
  62  * Java Collections Framework</a>.
  63  *
  64  * @since 1.7
  65  * @author Doug Lea
  66  * @param <E> the type of elements held in this queue
  67  */
  68 public interface TransferQueue<E> extends BlockingQueue<E> {
  69     /**
  70      * Transfers the element to a waiting consumer immediately, if possible.
  71      *
  72      * <p>More precisely, transfers the specified element immediately
  73      * if there exists a consumer already waiting to receive it (in
  74      * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
  75      * otherwise returning {@code false} without enqueuing the element.
  76      *
  77      * @param e the element to transfer
  78      * @return {@code true} if the element was transferred, else
  79      *         {@code false}
  80      * @throws ClassCastException if the class of the specified element
  81      *         prevents it from being added to this queue

  41  * example in message passing applications in which producers
  42  * sometimes (using method {@link #transfer}) await receipt of
  43  * elements by consumers invoking {@code take} or {@code poll}, while
  44  * at other times enqueue elements (via method {@code put}) without
  45  * waiting for receipt.
  46  * {@linkplain #tryTransfer(Object) Non-blocking} and
  47  * {@linkplain #tryTransfer(Object,long,TimeUnit) time-out} versions of
  48  * {@code tryTransfer} are also available.
  49  * A {@code TransferQueue} may also be queried, via {@link
  50  * #hasWaitingConsumer}, whether there are any threads waiting for
  51  * items, which is a converse analogy to a {@code peek} operation.
  52  *
  53  * <p>Like other blocking queues, a {@code TransferQueue} may be
  54  * capacity bounded.  If so, an attempted transfer operation may
  55  * initially block waiting for available space, and/or subsequently
  56  * block waiting for reception by a consumer.  Note that in a queue
  57  * with zero capacity, such as {@link SynchronousQueue}, {@code put}
  58  * and {@code transfer} are effectively synonymous.
  59  *
  60  * <p>This interface is a member of the
  61  * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
  62  * Java Collections Framework</a>.
  63  *
  64  * @since 1.7
  65  * @author Doug Lea
  66  * @param <E> the type of elements held in this queue
  67  */
  68 public interface TransferQueue<E> extends BlockingQueue<E> {
  69     /**
  70      * Transfers the element to a waiting consumer immediately, if possible.
  71      *
  72      * <p>More precisely, transfers the specified element immediately
  73      * if there exists a consumer already waiting to receive it (in
  74      * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
  75      * otherwise returning {@code false} without enqueuing the element.
  76      *
  77      * @param e the element to transfer
  78      * @return {@code true} if the element was transferred, else
  79      *         {@code false}
  80      * @throws ClassCastException if the class of the specified element
  81      *         prevents it from being added to this queue