ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166y/TransferQueue.java
(Generate patch)

Comparing jsr166/src/jsr166y/TransferQueue.java (file contents):
Revision 1.7 by jsr166, Thu Jul 30 22:45:39 2009 UTC vs.
Revision 1.10 by jsr166, Sun Aug 2 18:05:53 2009 UTC

# Line 23 | Line 23 | import java.util.concurrent.*;
23   * peek} operation.
24   *
25   * <p>Like other blocking queues, a {@code TransferQueue} may be
26 < * capacity bounded. If so, an attempted {@code transfer} operation
27 < * may initially block waiting for available space, and/or
28 < * subsequently block waiting for reception by a consumer.  Note that
29 < * in a queue with zero capacity, such as {@link SynchronousQueue},
30 < * {@code put} and {@code transfer} are effectively synonymous.
26 > * capacity bounded.  If so, an attempted transfer operation may
27 > * initially block waiting for available space, and/or subsequently
28 > * block waiting for reception by a consumer.  Note that in a queue
29 > * with zero capacity, such as {@link SynchronousQueue}, {@code put}
30 > * and {@code transfer} are effectively synonymous.
31   *
32   * <p>This interface is a member of the
33   * <a href="{@docRoot}/../technotes/guides/collections/index.html">
# Line 39 | Line 39 | import java.util.concurrent.*;
39   */
40   public interface TransferQueue<E> extends BlockingQueue<E> {
41      /**
42 <     * Transfers the specified element immediately if there exists a
43 <     * consumer already waiting to receive it (in {@link #take} or
44 <     * timed {@link #poll(Object,long,TimeUnit) poll}), otherwise
45 <     * returning {@code false} without enqueuing the element.
42 >     * Transfers the element to a waiting consumer immediately, if possible.
43 >     *
44 >     * <p>More precisely, transfers the specified element immediately
45 >     * if there exists a consumer already waiting to receive it (in
46 >     * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
47 >     * otherwise returning {@code false} without enqueuing the element.
48       *
49       * @param e the element to transfer
50       * @return {@code true} if the element was transferred, else
# Line 56 | Line 58 | public interface TransferQueue<E> extend
58      boolean tryTransfer(E e);
59  
60      /**
61 <     * Inserts the specified element into this queue, waiting if
62 <     * necessary for space to become available and the element to be
63 <     * received by a consumer invoking {@code take} or {@code poll}.
61 >     * Transfers the element to a consumer, waiting if necessary to do so.
62 >     *
63 >     * <p>More precisely, transfers the specified element immediately
64 >     * if there exists a consumer already waiting to receive it (in
65 >     * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
66 >     * else waits until the element is received by a consumer.
67       *
68       * @param e the element to transfer
69       * @throws InterruptedException if interrupted while waiting,
70 <     *         in which case the element is not enqueued
70 >     *         in which case the element is not left enqueued
71       * @throws ClassCastException if the class of the specified element
72       *         prevents it from being added to this queue
73       * @throws NullPointerException if the specified element is null
# Line 72 | Line 77 | public interface TransferQueue<E> extend
77      void transfer(E e) throws InterruptedException;
78  
79      /**
80 <     * Inserts the specified element into this queue, waiting up to
81 <     * the specified wait time if necessary for space to become
82 <     * available and the element to be received by a consumer invoking
83 <     * {@code take} or {@code poll}.
80 >     * Transfers the element to a consumer if it is possible to do so
81 >     * before the timeout elapses.
82 >     *
83 >     * <p>More precisely, transfers the specified element immediately
84 >     * if there exists a consumer already waiting to receive it (in
85 >     * {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
86 >     * else waits until the element is received by a consumer,
87 >     * returning {@code false} if the specified wait time elapses
88 >     * before the element can be transferred.
89       *
90       * @param e the element to transfer
91       * @param timeout how long to wait before giving up, in units of
# Line 84 | Line 94 | public interface TransferQueue<E> extend
94       *        {@code timeout} parameter
95       * @return {@code true} if successful, or {@code false} if
96       *         the specified waiting time elapses before completion,
97 <     *         in which case the element is not enqueued
97 >     *         in which case the element is not left enqueued
98       * @throws InterruptedException if interrupted while waiting,
99 <     *         in which case the element is not enqueued
99 >     *         in which case the element is not left enqueued
100       * @throws ClassCastException if the class of the specified element
101       *         prevents it from being added to this queue
102       * @throws NullPointerException if the specified element is null
# Line 99 | Line 109 | public interface TransferQueue<E> extend
109      /**
110       * Returns {@code true} if there is at least one consumer waiting
111       * to receive an element via {@link #take} or
112 <     * timed {@link #poll(Object,long,TimeUnit) poll}.
112 >     * timed {@link #poll(long,TimeUnit) poll}.
113       * The return value represents a momentary state of affairs.
114       *
115       * @return {@code true} if there is at least one waiting consumer
# Line 108 | Line 118 | public interface TransferQueue<E> extend
118  
119      /**
120       * Returns an estimate of the number of consumers waiting to
121 <     * receive elements via {@link #take} or
122 <     * timed {@link #poll(Object,long,TimeUnit) poll}. The return
123 <     * value is an approximation of a momentary state of affairs, that
124 <     * may be inaccurate if consumers have completed or given up
125 <     * waiting. The value may be useful for monitoring and heuristics,
126 <     * but not for synchronization control. Implementations of this
121 >     * receive elements via {@link #take} or timed
122 >     * {@link #poll(long,TimeUnit) poll}.  The return value is an
123 >     * approximation of a momentary state of affairs, that may be
124 >     * inaccurate if consumers have completed or given up waiting.
125 >     * The value may be useful for monitoring and heuristics, but
126 >     * not for synchronization control.  Implementations of this
127       * method are likely to be noticeably slower than those for
128       * {@link #hasWaitingConsumer}.
129       *

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines