1a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson/* 2a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * Written by Doug Lea with assistance from members of JCP JSR-166 3a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * Expert Group and released to the public domain, as explained at 4a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * http://creativecommons.org/publicdomain/zero/1.0/ 5a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson */ 6a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 7a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilsonpackage java.util.concurrent; 8a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 9a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson// BEGIN android-note 10a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson// removed link to collections framework docs 11a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson// END android-note 12a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 13a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson/** 14a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * A {@link BlockingQueue} in which producers may wait for consumers 15a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * to receive elements. A {@code TransferQueue} may be useful for 16a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * example in message passing applications in which producers 17a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * sometimes (using method {@link #transfer}) await receipt of 18a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * elements by consumers invoking {@code take} or {@code poll}, while 19a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * at other times enqueue elements (via method {@code put}) without 20a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * waiting for receipt. 21a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@linkplain #tryTransfer(Object) Non-blocking} and 22a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@linkplain #tryTransfer(Object,long,TimeUnit) time-out} versions of 23a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@code tryTransfer} are also available. 24a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * A {@code TransferQueue} may also be queried, via {@link 25a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * #hasWaitingConsumer}, whether there are any threads waiting for 26a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * items, which is a converse analogy to a {@code peek} operation. 27a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 28a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <p>Like other blocking queues, a {@code TransferQueue} may be 29a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * capacity bounded. If so, an attempted transfer operation may 30a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * initially block waiting for available space, and/or subsequently 31a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * block waiting for reception by a consumer. Note that in a queue 32a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * with zero capacity, such as {@link SynchronousQueue}, {@code put} 33a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * and {@code transfer} are effectively synonymous. 34a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 35a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @since 1.7 36a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @hide 37a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @author Doug Lea 38a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @param <E> the type of elements held in this collection 39a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson */ 40a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilsonpublic interface TransferQueue<E> extends BlockingQueue<E> { 41a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson /** 42a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * Transfers the element to a waiting consumer immediately, if possible. 43a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 44a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <p>More precisely, transfers the specified element immediately 45a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * if there exists a consumer already waiting to receive it (in 46a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), 47a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * otherwise returning {@code false} without enqueuing the element. 48a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 49a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @param e the element to transfer 50a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @return {@code true} if the element was transferred, else 51a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@code false} 52a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws ClassCastException if the class of the specified element 53a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * prevents it from being added to this queue 54a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws NullPointerException if the specified element is null 55a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws IllegalArgumentException if some property of the specified 56a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * element prevents it from being added to this queue 57a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson */ 58a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson boolean tryTransfer(E e); 59a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 60a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson /** 61a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * Transfers the element to a consumer, waiting if necessary to do so. 62a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 63a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <p>More precisely, transfers the specified element immediately 64a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * if there exists a consumer already waiting to receive it (in 65a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), 66a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * else waits until the element is received by a consumer. 67a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 68a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @param e the element to transfer 69a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws InterruptedException if interrupted while waiting, 70a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * in which case the element is not left enqueued 71a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws ClassCastException if the class of the specified element 72a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * prevents it from being added to this queue 73a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws NullPointerException if the specified element is null 74a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws IllegalArgumentException if some property of the specified 75a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * element prevents it from being added to this queue 76a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson */ 77a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson void transfer(E e) throws InterruptedException; 78a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 79a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson /** 80a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * Transfers the element to a consumer if it is possible to do so 81a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * before the timeout elapses. 82a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 83a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * <p>More precisely, transfers the specified element immediately 84a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * if there exists a consumer already waiting to receive it (in 85a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), 86a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * else waits until the element is received by a consumer, 87a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * returning {@code false} if the specified wait time elapses 88a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * before the element can be transferred. 89a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 90a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @param e the element to transfer 91a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @param timeout how long to wait before giving up, in units of 92a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@code unit} 93a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @param unit a {@code TimeUnit} determining how to interpret the 94a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@code timeout} parameter 95a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @return {@code true} if successful, or {@code false} if 96a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * the specified waiting time elapses before completion, 97a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * in which case the element is not left enqueued 98a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws InterruptedException if interrupted while waiting, 99a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * in which case the element is not left enqueued 100a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws ClassCastException if the class of the specified element 101a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * prevents it from being added to this queue 102a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws NullPointerException if the specified element is null 103a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @throws IllegalArgumentException if some property of the specified 104a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * element prevents it from being added to this queue 105a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson */ 106a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson boolean tryTransfer(E e, long timeout, TimeUnit unit) 107a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson throws InterruptedException; 108a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 109a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson /** 110a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * Returns {@code true} if there is at least one consumer waiting 111a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * to receive an element via {@link #take} or 112a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * timed {@link #poll(long,TimeUnit) poll}. 113a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * The return value represents a momentary state of affairs. 114a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 115a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @return {@code true} if there is at least one waiting consumer 116a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson */ 117a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson boolean hasWaitingConsumer(); 118a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson 119a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson /** 120a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * Returns an estimate of the number of consumers waiting to 121a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * receive elements via {@link #take} or timed 122a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@link #poll(long,TimeUnit) poll}. The return value is an 123a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * approximation of a momentary state of affairs, that may be 124a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * inaccurate if consumers have completed or given up waiting. 125a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * The value may be useful for monitoring and heuristics, but 126a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * not for synchronization control. Implementations of this 127a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * method are likely to be noticeably slower than those for 128a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * {@link #hasWaitingConsumer}. 129a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * 130a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson * @return the number of consumers waiting to receive elements 131a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson */ 132a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson int getWaitingConsumerCount(); 133a807b4d808d2591894daf13aab179b2e9c46a2f5Jesse Wilson} 134