--- jsr166/src/jsr166y/TransferQueue.java	2009/07/27 00:01:47	1.6
+++ jsr166/src/jsr166y/TransferQueue.java	2009/08/02 22:58:50	1.11
@@ -14,20 +14,20 @@ import java.util.concurrent.*;
  * 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.
+ * 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.
  *
  * <p>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},
- * {@code put} and {@code transfer} are effectively synonymous.
+ * capacity bounded.  If so, an attempted 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}, {@code put}
+ * and {@code transfer} are effectively synonymous.
  *
  * <p>This interface is a member of the
  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
@@ -39,9 +39,12 @@ import java.util.concurrent.*;
  */
 public interface TransferQueue<E> extends BlockingQueue<E> {
     /**
-     * Transfers the specified element if there exists a consumer
-     * already waiting to receive it, otherwise returning {@code false}
-     * without enqueuing the element.
+     * Transfers the element to a waiting consumer immediately, if possible.
+     *
+     * <p>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 {@code true} if the element was transferred, else
@@ -55,13 +58,16 @@ public interface TransferQueue<E> 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 {@code take} or {@code poll}.
+     * Transfers the element to a consumer, waiting if necessary to do so.
+     *
+     * <p>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
@@ -71,10 +77,15 @@ public interface TransferQueue<E> 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
-     * {@code take} or {@code poll}.
+     * Transfers the element to a consumer if it is possible to do so
+     * before the timeout elapses.
+     *
+     * <p>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
@@ -83,9 +94,9 @@ public interface TransferQueue<E> extend
      *        {@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
@@ -97,7 +108,8 @@ public interface TransferQueue<E> extend
 
     /**
      * Returns {@code true} if there is at least one consumer waiting
-     * to dequeue an element via {@code take} or {@code poll}.
+     * 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
@@ -106,15 +118,16 @@ public interface TransferQueue<E> extend
 
     /**
      * Returns an estimate of the number of consumers waiting to
-     * dequeue elements via {@code take} or {@code 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
      * {@link #hasWaitingConsumer}.
      *
-     * @return the number of consumers waiting to dequeue elements
+     * @return the number of consumers waiting to receive elements
      */
     int getWaitingConsumerCount();
 }