--- jsr166/src/jsr166y/TransferQueue.java 2007/07/11 14:30:37 1.2 +++ jsr166/src/jsr166y/TransferQueue.java 2009/08/01 20:26:50 1.9 @@ -9,23 +9,25 @@ import java.util.concurrent.*; /** * A {@link BlockingQueue} in which producers may wait for consumers - * to receive elements. A TransferQueue may be useful for + * to receive elements. A {@code TransferQueue} may be useful for * example in message passing applications in which producers - * sometimes (using method transfer) await receipt of - * elements by consumers invoking take or poll, - * while at other times enqueue elements (via method put) - * without waiting for receipt. Non-blocking and time-out versions of - * tryTransfer are also available. A TransferQueue may also - * be queried via hasWaitingConsumer whether there are any - * threads waiting for items, which is a converse analogy to a - * peek operation + * sometimes (using method {@link #transfer}) await receipt of + * elements by consumers invoking {@code take} or {@code poll}, while + * at other times enqueue elements (via method {@code put}) without + * waiting for receipt. {@linkplain + * #tryTransfer(Object) Non-blocking} and {@linkplain + * #tryTransfer(Object,long,TimeUnit) time-out} versions of {@code + * tryTransfer} are also available. A {@code TransferQueue} may also + * be queried, via {@link #hasWaitingConsumer}, whether there are any + * threads waiting for items, which is a converse analogy to a {@code + * peek} operation. * - *

Like any BlockingQueue, a TransferQueue may be - * capacity bounded. If so, an attempted transfer operation + *

Like other blocking queues, a {@code TransferQueue} may be + * capacity bounded. If so, an attempted {@code transfer} operation * may initially block waiting for available space, and/or * subsequently block waiting for reception by a consumer. Note that * in a queue with zero capacity, such as {@link SynchronousQueue}, - * put and transfer are effectively synonymous. + * {@code put} and {@code transfer} are effectively synonymous. * *

This interface is a member of the * @@ -37,13 +39,16 @@ import java.util.concurrent.*; */ public interface TransferQueue extends BlockingQueue { /** - * Transfers the specified element if there exists a consumer - * already waiting to receive it, otherwise returning false - * without enqueuing the element. + * Transfers the element to a waiting consumer immediately, if possible. + * + *

More precisely, transfers the specified element immediately + * if there exists a consumer already waiting to receive it (in + * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), + * otherwise returning {@code false} without enqueuing the element. * * @param e the element to transfer - * @return true if the element was transferred, else - * false + * @return {@code true} if the element was transferred, else + * {@code false} * @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 @@ -53,13 +58,16 @@ public interface TransferQueue extend boolean tryTransfer(E e); /** - * Inserts the specified element into this queue, waiting if - * necessary for space to become available and the element to be - * dequeued by a consumer invoking take or poll. + * Transfers the element to a consumer, waiting if necessary to do so. + * + *

More precisely, transfers the specified element immediately + * if there exists a consumer already waiting to receive it (in + * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), + * else waits until the element is received by a consumer. * * @param e the element to transfer * @throws InterruptedException if interrupted while waiting, - * in which case the element is not enqueued. + * in which case the element is not left enqueued * @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 @@ -69,49 +77,57 @@ public interface TransferQueue extend void transfer(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 and the element to be dequeued by a consumer invoking - * take or poll. + * Transfers the element to a consumer if it is possible to do so + * before the timeout elapses. + * + *

More precisely, transfers the specified element immediately + * if there exists a consumer already waiting to receive it (in + * {@link #take} or timed {@link #poll(long,TimeUnit) poll}), + * else waits until the element is received by a consumer, + * returning {@code false} if the specified wait time elapses + * before the element can be transferred. * * @param e the element to transfer * @param timeout how long to wait before giving up, in units of - * unit - * @param unit a TimeUnit determining how to interpret the - * timeout parameter - * @return true if successful, or false if + * {@code unit} + * @param unit a {@code TimeUnit} determining how to interpret the + * {@code timeout} parameter + * @return {@code true} if successful, or {@code false} if * the specified waiting time elapses before completion, - * in which case the element is not enqueued. + * in which case the element is not left enqueued * @throws InterruptedException if interrupted while waiting, - * in which case the element is not enqueued. + * in which case the element is not left enqueued * @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 tryTransfer(E e, long timeout, TimeUnit unit) + boolean tryTransfer(E e, long timeout, TimeUnit unit) throws InterruptedException; /** - * Returns true if there is at least one consumer waiting to - * dequeue an element via take or poll. The - * return value represents a momentary state of affairs. - * @return true if there is at least one waiting consumer. + * Returns {@code true} if there is at least one consumer waiting + * to receive an element via {@link #take} or + * timed {@link #poll(long,TimeUnit) poll}. + * The return value represents a momentary state of affairs. + * + * @return {@code true} if there is at least one waiting consumer */ boolean hasWaitingConsumer(); - /** * Returns an estimate of the number of consumers waiting to - * dequeue elements via take or poll. The return - * value is an approximation of a momentary state of affairs, that - * may be inaccurate if consumers have completed or given up - * waiting. The value may be useful for monitoring and heuristics, - * but not for synchronization control. Implementations of this + * receive elements via {@link #take} or timed + * {@link #poll(long,TimeUnit) poll}. The return value is an + * approximation of a momentary state of affairs, that may be + * inaccurate if consumers have completed or given up waiting. + * The value may be useful for monitoring and heuristics, but + * not for synchronization control. Implementations of this * method are likely to be noticeably slower than those for - * hasWaitingConsumer. - * @return the number of consumers waiting to dequeue elements + * {@link #hasWaitingConsumer}. + * + * @return the number of consumers waiting to receive elements */ int getWaitingConsumerCount(); }