ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/SynchronousQueue.java
(Generate patch)

Comparing jsr166/src/main/java/util/concurrent/SynchronousQueue.java (file contents):
Revision 1.17 by dl, Fri Aug 29 22:38:12 2003 UTC vs.
Revision 1.18 by dl, Fri Sep 12 15:40:10 2003 UTC

# Line 9 | Line 9 | import java.util.concurrent.locks.*;
9   import java.util.*;
10  
11   /**
12 < * A {@linkplain BlockingQueue blocking queue} in which each <tt>put</tt>
13 < * must wait for a <tt>take</tt>, and vice versa.  
14 < * A synchronous queue does not have any internal capacity - in particular
15 < * it does not have a capacity of one. You cannot <tt>peek</tt> at a
16 < * synchronous queue because an element is only present when you try to take
17 < * it; you cannot add an element (using any method) unless another thread is
18 < * trying to remove it; you cannot iterate as there is nothing to iterate.
19 < * The <em>head</em> of the queue is the element that the first queued thread
20 < * is trying to add to the queue; if there are no queued threads then no
21 < * element is being added and the head is <tt>null</tt>.
22 < * Many of the <tt>Collection</tt> methods make little or no sense for a
23 < * synchronous queue.
24 < * This queue does not permit <tt>null</tt> elements.
25 < * <p>Synchronous queues are similar to rendezvous channels used
26 < * in CSP and Ada. They are well suited for handoff designs, in which
27 < * an object running in one thread must synch up with an object
28 < * running in another thread in order to hand it some information,
29 < * event, or task.
12 > * A {@linkplain BlockingQueue blocking queue} in which each
13 > * <tt>put</tt> must wait for a <tt>take</tt>, and vice versa.  A
14 > * synchronous queue does not have any internal capacity - in
15 > * particular it does not have a capacity of one. You cannot
16 > * <tt>peek</tt> at a synchronous queue because an element is only
17 > * present when you try to take it; you cannot add an element (using
18 > * any method) unless another thread is trying to remove it; you
19 > * cannot iterate as there is nothing to iterate.  The <em>head</em>
20 > * of the queue is the element that the first queued thread is trying
21 > * to add to the queue; if there are no queued threads then no element
22 > * is being added and the head is <tt>null</tt>.  For purposes of
23 > * other <tt>Collection</tt> methods (for example <tt>contains</tt>),
24 > * a <tt>SynchronousQueue<//t> acts as an empty collection.  This
25 > * queue does not permit <tt>null</tt> elements.
26 > *
27 > * <p>Synchronous queues are similar to rendezvous channels used in
28 > * CSP and Ada. They are well suited for handoff designs, in which an
29 > * object running in one thread must synch up with an object running
30 > * in another thread in order to hand it some information, event, or
31 > * task.
32   * @since 1.5
33   * @author Doug Lea
34   **/
# Line 300 | Line 302 | public class SynchronousQueue<E> extends
302      /**
303       * Adds the specified element to this queue, waiting if necessary for
304       * another thread to receive it.
305 <     * @throws NullPointerException {@inheritDoc}
305 >     * @param o the element to add
306 >     * @throws InterruptedException if interrupted while waiting.
307 >     * @throws NullPointerException if the specified element is <tt>null</tt>.
308       */
309      public void put(E o) throws InterruptedException {
310          doPut(o, false, 0);
311      }
312  
313      /**
314 <     * Adds the specified element to this queue, waiting if necessary up to the
315 <     * specified wait time for another thread to receive it.
314 >     * Adds the specified element to this queue, waiting if necessary
315 >     * up to the specified wait time for another thread to receive it.
316 >     * @param o the element to add
317 >     * @param timeout how long to wait before giving up, in units of
318 >     * <tt>unit</tt>
319 >     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
320 >     * <tt>timeout</tt> parameter
321       * @return <tt>true</tt> if successful, or <tt>false</tt> if
322       * the specified waiting time elapses before a taker appears.
323 <     * @throws NullPointerException {@inheritDoc}
323 >     * @throws InterruptedException if interrupted while waiting.
324 >     * @throws NullPointerException if the specified element is <tt>null</tt>.
325       */
326 <    public boolean offer(E x, long timeout, TimeUnit unit) throws InterruptedException {
327 <        return doPut(x, true, unit.toNanos(timeout));
326 >    public boolean offer(E o, long timeout, TimeUnit unit) throws InterruptedException {
327 >        return doPut(o, true, unit.toNanos(timeout));
328      }
329  
330  
# Line 331 | Line 341 | public class SynchronousQueue<E> extends
341       * Retrieves and removes the head of this queue, waiting
342       * if necessary up to the specified wait time, for another thread
343       * to insert it.
344 +     * @param timeout how long to wait before giving up, in units of
345 +     * <tt>unit</tt>
346 +     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
347 +     * <tt>timeout</tt> parameter
348 +     * @return the head of this queue, or <tt>null</tt> if the
349 +     * specified waiting time elapses before an element is present.
350 +     * @throws InterruptedException if interrupted while waiting.
351       */
352      public E poll(long timeout, TimeUnit unit) throws InterruptedException {
353          return doTake(true, unit.toNanos(timeout));
# Line 338 | Line 355 | public class SynchronousQueue<E> extends
355  
356      // Untimed nonblocking versions
357  
358 <    /**
359 <     * Adds the specified element to this queue, if another thread is
360 <     * waiting to receive it.
361 <     *
362 <     * @throws NullpointerException {@inheritDoc}
363 <     */
358 >   /**
359 >    * Adds the specified element to this queue, if another thread is
360 >    * waiting to receive it.
361 >    *
362 >    * @param o the element to add.
363 >    * @return <tt>true</tt> if it was possible to add the element to
364 >    *         this queue, else <tt>false</tt>
365 >    * @throws NullPointerException if the specified element is <tt>null</tt>
366 >    */
367      public boolean offer(E o) {
368          if (o == null) throw new NullPointerException();
369  
# Line 364 | Line 384 | public class SynchronousQueue<E> extends
384          }
385      }
386  
387 <
387 >    /**
388 >     * Retrieves and removes the head of this queue, if another thread
389 >     * is currently making an element available.
390 >     *
391 >     * @return the head of this queue, or <tt>null</tt> if no
392 >     *         element is available.
393 >     */
394      public E poll() {
395          for (;;) {
396              Node node;
# Line 386 | Line 412 | public class SynchronousQueue<E> extends
412          }
413      }
414  
389 –
390 –    /**
391 –     * Adds the specified element to this queue.
392 –     * @return <tt>true</tt> (as per the general contract of
393 –     * <tt>Collection.add</tt>).
394 –     *
395 –     * @throws NullPointerException {@inheritDoc}
396 –     * @throws IllegalStateException if no thread is waiting to receive the
397 –     * element being added
398 –     */
399 –    public boolean add(E o) {
400 –        return super.add(o);
401 –    }
402 –
403 –
404 –    /**
405 –     * Adds all of the elements in the specified collection to this queue.
406 –     * The behavior of this operation is undefined if
407 –     * the specified collection is modified while the operation is in
408 –     * progress.  (This implies that the behavior of this call is undefined if
409 –     * the specified collection is this queue, and this queue is nonempty.)
410 –     * <p>
411 –     * This implementation iterates over the specified collection, and adds
412 –     * each object returned by the iterator to this collection, in turn.
413 –     * @throws NullPointerException {@inheritDoc}
414 –     * @throws IllegalStateException if no thread is waiting to receive the
415 –     * element being added
416 –     */
417 –    public boolean addAll(Collection<? extends E> c) {
418 –        return super.addAll(c);
419 –    }
420 –
415      /**
416       * Always returns <tt>true</tt>.
417       * A <tt>SynchronousQueue</tt> has no internal capacity.
# Line 454 | Line 448 | public class SynchronousQueue<E> extends
448      /**
449       * Always returns <tt>false</tt>.
450       * A <tt>SynchronousQueue</tt> has no internal capacity.
451 +     * @param o the element
452       * @return <tt>false</tt>
453       */
454      public boolean contains(Object o) {
# Line 461 | Line 456 | public class SynchronousQueue<E> extends
456      }
457  
458      /**
459 +     * Always returns <tt>false</tt>.
460 +     * A <tt>SynchronousQueue</tt> has no internal capacity.
461 +     *
462 +     * @param o the element to remove
463 +     * @return <tt>false</tt>
464 +     */
465 +    public boolean remove(Object o) {
466 +        return false;
467 +    }
468 +
469 +    /**
470       * Returns <tt>false</tt> unless given collection is empty.
471       * A <tt>SynchronousQueue</tt> has no internal capacity.
472 +     * @param c the collection
473       * @return <tt>false</tt> unless given collection is empty
474       */
475      public boolean containsAll(Collection<?> c) {
# Line 472 | Line 479 | public class SynchronousQueue<E> extends
479      /**
480       * Always returns <tt>false</tt>.
481       * A <tt>SynchronousQueue</tt> has no internal capacity.
482 +     * @param c the collection
483       * @return <tt>false</tt>
484       */
485      public boolean removeAll(Collection<?> c) {
# Line 481 | Line 489 | public class SynchronousQueue<E> extends
489      /**
490       * Always returns <tt>false</tt>.
491       * A <tt>SynchronousQueue</tt> has no internal capacity.
492 +     * @param c the collection
493       * @return <tt>false</tt>
494       */
495      public boolean retainAll(Collection<?> c) {
# Line 511 | Line 520 | public class SynchronousQueue<E> extends
520      }
521  
522      /**
523 <     * Returns an empty iterator: <tt>hasNext</tt> always returns
523 >     * Returns an empty iterator in which <tt>hasNext</tt> always returns
524       * <tt>false</tt>.
525       *
526       * @return an empty iterator

Diff Legend

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