--- jsr166/src/jsr166y/TransferQueue.java 2007/07/11 14:30:37 1.2
+++ jsr166/src/jsr166y/TransferQueue.java 2009/07/30 22:45:39 1.7
@@ -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,14 @@ 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 specified element immediately if there exists a
+ * consumer already waiting to receive it (in {@link #take} or
+ * timed {@link #poll(Object,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
@@ -55,11 +58,11 @@ public interface TransferQueue extend
/**
* 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.
+ * received by a consumer invoking {@code take} or {@code poll}.
*
* @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 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
@@ -71,47 +74,50 @@ public interface TransferQueue extend
/**
* 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.
+ * available and the element to be received by a consumer invoking
+ * {@code take} or {@code poll}.
*
* @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 enqueued
* @throws InterruptedException if interrupted while waiting,
- * in which case the element is not enqueued.
+ * in which case the element is not 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(Object,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
+ * receive elements via {@link #take} or
+ * timed {@link #poll(Object,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();
}