1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file: 30 * 31 * Written by Doug Lea with assistance from members of JCP JSR-166 32 * Expert Group and released to the public domain, as explained at 33 * http://creativecommons.org/publicdomain/zero/1.0/ 34 */ 35 36 package java.util.concurrent; 37 38 // BEGIN android-note 39 // removed link to collections framework docs 40 // END android-note 41 42 /** 43 * A {@link BlockingQueue} in which producers may wait for consumers 44 * to receive elements. A {@code TransferQueue} may be useful for 45 * example in message passing applications in which producers 46 * sometimes (using method {@link #transfer}) await receipt of 47 * elements by consumers invoking {@code take} or {@code poll}, while 48 * at other times enqueue elements (via method {@code put}) without 49 * waiting for receipt. 50 * {@linkplain #tryTransfer(Object) Non-blocking} and 51 * {@linkplain #tryTransfer(Object,long,TimeUnit) time-out} versions of 52 * {@code tryTransfer} are also available. 53 * A {@code TransferQueue} may also be queried, via {@link 54 * #hasWaitingConsumer}, whether there are any threads waiting for 55 * items, which is a converse analogy to a {@code peek} operation. 56 * 57 * <p>Like other blocking queues, a {@code TransferQueue} may be 58 * capacity bounded. If so, an attempted transfer operation may 59 * initially block waiting for available space, and/or subsequently 60 * block waiting for reception by a consumer. Note that in a queue 61 * with zero capacity, such as {@link SynchronousQueue}, {@code put} 62 * and {@code transfer} are effectively synonymous. 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 82 * @throws NullPointerException if the specified element is null 83 * @throws IllegalArgumentException if some property of the specified 84 * element prevents it from being added to this queue 85 */ tryTransfer(E e)86 boolean tryTransfer(E e); 87 88 /** 89 * Transfers the element to a consumer, waiting if necessary to do so. 90 * 91 * <p>More precisely, transfers the specified element immediately 92 * if there exists a consumer already waiting to receive it (in 93 * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), 94 * else waits until the element is received by a consumer. 95 * 96 * @param e the element to transfer 97 * @throws InterruptedException if interrupted while waiting, 98 * in which case the element is not left enqueued 99 * @throws ClassCastException if the class of the specified element 100 * prevents it from being added to this queue 101 * @throws NullPointerException if the specified element is null 102 * @throws IllegalArgumentException if some property of the specified 103 * element prevents it from being added to this queue 104 */ transfer(E e)105 void transfer(E e) throws InterruptedException; 106 107 /** 108 * Transfers the element to a consumer if it is possible to do so 109 * before the timeout elapses. 110 * 111 * <p>More precisely, transfers the specified element immediately 112 * if there exists a consumer already waiting to receive it (in 113 * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), 114 * else waits until the element is received by a consumer, 115 * returning {@code false} if the specified wait time elapses 116 * before the element can be transferred. 117 * 118 * @param e the element to transfer 119 * @param timeout how long to wait before giving up, in units of 120 * {@code unit} 121 * @param unit a {@code TimeUnit} determining how to interpret the 122 * {@code timeout} parameter 123 * @return {@code true} if successful, or {@code false} if 124 * the specified waiting time elapses before completion, 125 * in which case the element is not left enqueued 126 * @throws InterruptedException if interrupted while waiting, 127 * in which case the element is not left enqueued 128 * @throws ClassCastException if the class of the specified element 129 * prevents it from being added to this queue 130 * @throws NullPointerException if the specified element is null 131 * @throws IllegalArgumentException if some property of the specified 132 * element prevents it from being added to this queue 133 */ tryTransfer(E e, long timeout, TimeUnit unit)134 boolean tryTransfer(E e, long timeout, TimeUnit unit) 135 throws InterruptedException; 136 137 /** 138 * Returns {@code true} if there is at least one consumer waiting 139 * to receive an element via {@link #take} or 140 * timed {@link #poll(long,TimeUnit) poll}. 141 * The return value represents a momentary state of affairs. 142 * 143 * @return {@code true} if there is at least one waiting consumer 144 */ hasWaitingConsumer()145 boolean hasWaitingConsumer(); 146 147 /** 148 * Returns an estimate of the number of consumers waiting to 149 * receive elements via {@link #take} or timed 150 * {@link #poll(long,TimeUnit) poll}. The return value is an 151 * approximation of a momentary state of affairs, that may be 152 * inaccurate if consumers have completed or given up waiting. 153 * The value may be useful for monitoring and heuristics, but 154 * not for synchronization control. Implementations of this 155 * method are likely to be noticeably slower than those for 156 * {@link #hasWaitingConsumer}. 157 * 158 * @return the number of consumers waiting to receive elements 159 */ getWaitingConsumerCount()160 int getWaitingConsumerCount(); 161 } 162