harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hinde...@apache.org
Subject svn commit: r794678 [1/19] - in /harmony/enhanced/classlib/trunk/modules/concurrent/src: main/java/java/util/concurrent/ main/java/java/util/concurrent/atomic/ main/java/java/util/concurrent/locks/ test/java/
Date Thu, 16 Jul 2009 14:01:17 GMT
Author: hindessm
Date: Thu Jul 16 14:01:15 2009
New Revision: 794678

URL: http://svn.apache.org/viewvc?rev=794678&view=rev
Log:
Applying patch from "[#HARMONY-6262] Harmony's java.util.concurrent is
out of date".

Added:
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/Java6Arrays.java   (with props)
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/package-info.java   (with props)
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/AbstractOwnableSynchronizer.java   (with props)
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/package-info.java   (with props)
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/package-info.java   (with props)
Modified:
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/AbstractExecutorService.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ArrayBlockingQueue.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/BlockingQueue.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CompletionService.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ConcurrentHashMap.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ConcurrentLinkedQueue.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ConcurrentMap.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CopyOnWriteArrayList.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CopyOnWriteArraySet.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CountDownLatch.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CyclicBarrier.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/DelayQueue.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/Delayed.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/Exchanger.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ExecutionException.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/Executor.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ExecutorCompletionService.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ExecutorService.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/Executors.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/Future.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/FutureTask.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/LinkedBlockingQueue.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/PriorityBlockingQueue.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/RejectedExecutionException.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/RejectedExecutionHandler.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ScheduledExecutorService.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ScheduledThreadPoolExecutor.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/Semaphore.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/SynchronousQueue.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ThreadFactory.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ThreadPoolExecutor.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/TimeUnit.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicBoolean.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicInteger.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicIntegerArray.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicLong.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicLongArray.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicLongFieldUpdater.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicMarkableReference.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicReference.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicReferenceArray.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/AtomicStampedReference.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/atomic/package.html
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/AbstractQueuedSynchronizer.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/ReentrantLock.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/ReentrantReadWriteLock.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/package.html
    harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/package.html
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/AbstractQueuedSynchronizerTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/ArrayBlockingQueueTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/AtomicIntegerFieldUpdaterTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/AtomicIntegerTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/AtomicLongFieldUpdaterTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/AtomicLongTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/AtomicReferenceFieldUpdaterTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/AtomicReferenceTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/ConcurrentHashMapTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/CyclicBarrierTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/DelayQueueTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/ExecutorCompletionServiceTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/ExecutorsTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/JSR166TestCase.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/LinkedBlockingQueueTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/LockSupportTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/PriorityBlockingQueueTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/ReentrantLockTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/ReentrantReadWriteLockTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/SynchronousQueueTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/ThreadPoolExecutorTest.java
    harmony/enhanced/classlib/trunk/modules/concurrent/src/test/java/TimeUnitTest.java

Modified: harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/AbstractExecutorService.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/AbstractExecutorService.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/AbstractExecutorService.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/AbstractExecutorService.java Thu Jul 16 14:01:15 2009
@@ -5,11 +5,10 @@
  */
 
 package java.util.concurrent;
-
 import java.util.*;
 
 /**
- * Provides default implementation of {@link ExecutorService}
+ * Provides default implementations of {@link ExecutorService}
  * execution methods. This class implements the <tt>submit</tt>,
  * <tt>invokeAny</tt> and <tt>invokeAll</tt> methods using the default
  * {@link FutureTask} class provided in this package.  For example,
@@ -24,6 +23,10 @@
  */
 public abstract class AbstractExecutorService implements ExecutorService {
 
+    /**
+     * @throws RejectedExecutionException {@inheritDoc}
+     * @throws NullPointerException       {@inheritDoc}
+     */
     public Future<?> submit(Runnable task) {
         if (task == null) throw new NullPointerException();
         FutureTask<Object> ftask = new FutureTask<Object>(task, null);
@@ -31,6 +34,10 @@
         return ftask;
     }
 
+    /**
+     * @throws RejectedExecutionException {@inheritDoc}
+     * @throws NullPointerException       {@inheritDoc}
+     */
     public <T> Future<T> submit(Runnable task, T result) {
         if (task == null) throw new NullPointerException();
         FutureTask<T> ftask = new FutureTask<T>(task, result);
@@ -38,6 +45,10 @@
         return ftask;
     }
 
+    /**
+     * @throws RejectedExecutionException {@inheritDoc}
+     * @throws NullPointerException       {@inheritDoc}
+     */
     public <T> Future<T> submit(Callable<T> task) {
         if (task == null) throw new NullPointerException();
         FutureTask<T> ftask = new FutureTask<T>(task);
@@ -57,7 +68,7 @@
         if (ntasks == 0)
             throw new IllegalArgumentException();
         List<Future<T>> futures= new ArrayList<Future<T>>(ntasks);
-        ExecutorCompletionService<T> ecs = 
+        ExecutorCompletionService<T> ecs =
             new ExecutorCompletionService<T>(this);
 
         // For efficiency, especially in executors with limited
@@ -79,14 +90,14 @@
             int active = 1;
 
             for (;;) {
-                Future<T> f = ecs.poll(); 
+                Future<T> f = ecs.poll();
                 if (f == null) {
                     if (ntasks > 0) {
                         --ntasks;
                         futures.add(ecs.submit(it.next()));
                         ++active;
                     }
-                    else if (active == 0) 
+                    else if (active == 0)
                         break;
                     else if (timed) {
                         f = ecs.poll(nanos, TimeUnit.NANOSECONDS);
@@ -96,29 +107,29 @@
                         nanos -= now - lastTime;
                         lastTime = now;
                     }
-                    else 
+                    else
                         f = ecs.take();
                 }
                 if (f != null) {
                     --active;
                     try {
                         return f.get();
-                    } catch(InterruptedException ie) {
+                    } catch (InterruptedException ie) {
                         throw ie;
-                    } catch(ExecutionException eex) {
+                    } catch (ExecutionException eex) {
                         ee = eex;
-                    } catch(RuntimeException rex) {
+                    } catch (RuntimeException rex) {
                         ee = new ExecutionException(rex);
                     }
                 }
-            }    
+            }
 
             if (ee == null)
                 ee = new ExecutionException();
             throw ee;
 
         } finally {
-            for (Future<T> f : futures) 
+            for (Future<T> f : futures)
                 f.cancel(true);
         }
     }
@@ -133,8 +144,8 @@
         }
     }
 
-    public <T> T invokeAny(Collection<Callable<T>> tasks, 
-                           long timeout, TimeUnit unit) 
+    public <T> T invokeAny(Collection<Callable<T>> tasks,
+                           long timeout, TimeUnit unit)
         throws InterruptedException, ExecutionException, TimeoutException {
         return doInvokeAny(tasks, true, unit.toNanos(timeout));
     }
@@ -153,10 +164,10 @@
             }
             for (Future<T> f : futures) {
                 if (!f.isDone()) {
-                    try { 
-                        f.get(); 
-                    } catch(CancellationException ignore) {
-                    } catch(ExecutionException ignore) {
+                    try {
+                        f.get();
+                    } catch (CancellationException ignore) {
+                    } catch (ExecutionException ignore) {
                     }
                 }
             }
@@ -164,13 +175,13 @@
             return futures;
         } finally {
             if (!done)
-                for (Future<T> f : futures) 
+                for (Future<T> f : futures)
                     f.cancel(true);
         }
     }
 
-    public <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks, 
-                                         long timeout, TimeUnit unit) 
+    public <T> List<Future<T>> invokeAll(Collection<Callable<T>> tasks,
+                                         long timeout, TimeUnit unit)
         throws InterruptedException {
         if (tasks == null || unit == null)
             throw new NullPointerException();
@@ -178,7 +189,7 @@
         List<Future<T>> futures = new ArrayList<Future<T>>(tasks.size());
         boolean done = false;
         try {
-            for (Callable<T> t : tasks) 
+            for (Callable<T> t : tasks)
                 futures.add(new FutureTask<T>(t));
 
             long lastTime = System.nanoTime();
@@ -192,18 +203,18 @@
                 nanos -= now - lastTime;
                 lastTime = now;
                 if (nanos <= 0)
-                    return futures; 
+                    return futures;
             }
 
             for (Future<T> f : futures) {
                 if (!f.isDone()) {
-                    if (nanos <= 0) 
-                        return futures; 
-                    try { 
-                        f.get(nanos, TimeUnit.NANOSECONDS); 
-                    } catch(CancellationException ignore) {
-                    } catch(ExecutionException ignore) {
-                    } catch(TimeoutException toe) {
+                    if (nanos <= 0)
+                        return futures;
+                    try {
+                        f.get(nanos, TimeUnit.NANOSECONDS);
+                    } catch (CancellationException ignore) {
+                    } catch (ExecutionException ignore) {
+                    } catch (TimeoutException toe) {
                         return futures;
                     }
                     long now = System.nanoTime();
@@ -215,7 +226,7 @@
             return futures;
         } finally {
             if (!done)
-                for (Future<T> f : futures) 
+                for (Future<T> f : futures)
                     f.cancel(true);
         }
     }

Modified: harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ArrayBlockingQueue.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ArrayBlockingQueue.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ArrayBlockingQueue.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/ArrayBlockingQueue.java Thu Jul 16 14:01:15 2009
@@ -20,8 +20,8 @@
  * <p>This is a classic &quot;bounded buffer&quot;, in which a
  * fixed-sized array holds elements inserted by producers and
  * extracted by consumers.  Once created, the capacity cannot be
- * increased.  Attempts to offer an element to a full queue will
- * result in the offer operation blocking; attempts to retrieve an
+ * increased.  Attempts to <tt>put</tt> an element into a full queue
+ * will result in the operation blocking; attempts to <tt>take</tt> an
  * element from an empty queue will similarly block.
  *
  * <p> This class supports an optional fairness policy for ordering
@@ -31,11 +31,12 @@
  * generally decreases throughput but reduces variability and avoids
  * starvation.
  *
- * <p>This class implements all of the <em>optional</em> methods
- * of the {@link Collection} and {@link Iterator} interfaces.
+ * <p>This class and its iterator implement all of the
+ * <em>optional</em> methods of the {@link Collection} and {@link
+ * Iterator} interfaces.
  *
  * <p>This class is a member of the
- * <a href="{@docRoot}/../guide/collections/index.html">
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  * Java Collections Framework</a>.
  *
  * @since 1.5
@@ -56,9 +57,9 @@
     /** The queued items  */
     private final E[] items;
     /** items index for next take, poll or remove */
-    private transient int takeIndex;
+    private int takeIndex;
     /** items index for next put, offer, or add. */
-    private transient int putIndex;
+    private int putIndex;
     /** Number of items in the queue */
     private int count;
 
@@ -84,7 +85,7 @@
     }
 
     /**
-     * Insert element at current put position, advance, and signal.
+     * Inserts element at current put position, advances, and signals.
      * Call only when holding lock.
      */
     private void insert(E x) {
@@ -95,7 +96,7 @@
     }
 
     /**
-     * Extract element at current take position, advance, and signal.
+     * Extracts element at current take position, advances, and signals.
      * Call only when holding lock.
      */
     private E extract() {
@@ -139,6 +140,7 @@
     /**
      * Creates an <tt>ArrayBlockingQueue</tt> with the given (fixed)
      * capacity and default access policy.
+     *
      * @param capacity the capacity of this queue
      * @throws IllegalArgumentException if <tt>capacity</tt> is less than 1
      */
@@ -149,10 +151,11 @@
     /**
      * Creates an <tt>ArrayBlockingQueue</tt> with the given (fixed)
      * capacity and the specified access policy.
+     *
      * @param capacity the capacity of this queue
      * @param fair if <tt>true</tt> then queue accesses for threads blocked
-     * on insertion or removal, are processed in FIFO order; if <tt>false</tt>
-     * the access order is unspecified.
+     *        on insertion or removal, are processed in FIFO order;
+     *        if <tt>false</tt> the access order is unspecified.
      * @throws IllegalArgumentException if <tt>capacity</tt> is less than 1
      */
     public ArrayBlockingQueue(int capacity, boolean fair) {
@@ -169,15 +172,16 @@
      * capacity, the specified access policy and initially containing the
      * elements of the given collection,
      * added in traversal order of the collection's iterator.
+     *
      * @param capacity the capacity of this queue
      * @param fair if <tt>true</tt> then queue accesses for threads blocked
-     * on insertion or removal, are processed in FIFO order; if <tt>false</tt>
-     * the access order is unspecified.
+     *        on insertion or removal, are processed in FIFO order;
+     *        if <tt>false</tt> the access order is unspecified.
      * @param c the collection of elements to initially contain
      * @throws IllegalArgumentException if <tt>capacity</tt> is less than
-     * <tt>c.size()</tt>, or less than 1.
-     * @throws NullPointerException if <tt>c</tt> or any element within it
-     * is <tt>null</tt>
+     *         <tt>c.size()</tt>, or less than 1.
+     * @throws NullPointerException if the specified collection or any
+     *         of its elements are null
      */
     public ArrayBlockingQueue(int capacity, boolean fair,
                               Collection<? extends E> c) {
@@ -190,23 +194,38 @@
     }
 
     /**
-     * Inserts the specified element at the tail of this queue if possible,
-     * returning immediately if this queue is full.
+     * Inserts the specified element at the tail of this queue if it is
+     * possible to do so immediately without exceeding the queue's capacity,
+     * returning <tt>true</tt> upon success and throwing an
+     * <tt>IllegalStateException</tt> if this queue is full.
+     *
+     * @param e the element to add
+     * @return <tt>true</tt> (as specified by {@link Collection#add})
+     * @throws IllegalStateException if this queue is full
+     * @throws NullPointerException if the specified element is null
+     */
+    public boolean add(E e) {
+        return super.add(e);
+    }
+
+    /**
+     * Inserts the specified element at the tail of this queue if it is
+     * possible to do so immediately without exceeding the queue's capacity,
+     * returning <tt>true</tt> upon success and <tt>false</tt> if this queue
+     * is full.  This method is generally preferable to method {@link #add},
+     * which can fail to insert an element only by throwing an exception.
      *
-     * @param o the element to add.
-     * @return <tt>true</tt> if it was possible to add the element to
-     *         this queue, else <tt>false</tt>
-     * @throws NullPointerException if the specified element is <tt>null</tt>
+     * @throws NullPointerException if the specified element is null
      */
-    public boolean offer(E o) {
-        if (o == null) throw new NullPointerException();
+    public boolean offer(E e) {
+        if (e == null) throw new NullPointerException();
         final ReentrantLock lock = this.lock;
         lock.lock();
         try {
             if (count == items.length)
                 return false;
             else {
-                insert(o);
+                insert(e);
                 return true;
             }
         } finally {
@@ -215,29 +234,50 @@
     }
 
     /**
-     * Inserts the specified element at the tail of this queue, waiting if
-     * necessary up to the specified wait time for space to become available.
-     * @param o the element to add
-     * @param timeout how long to wait before giving up, in units of
-     * <tt>unit</tt>
-     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
-     * <tt>timeout</tt> parameter
-     * @return <tt>true</tt> if successful, or <tt>false</tt> if
-     * the specified waiting time elapses before space is available.
-     * @throws InterruptedException if interrupted while waiting.
-     * @throws NullPointerException if the specified element is <tt>null</tt>.
+     * Inserts the specified element at the tail of this queue, waiting
+     * for space to become available if the queue is full.
+     *
+     * @throws InterruptedException {@inheritDoc}
+     * @throws NullPointerException {@inheritDoc}
+     */
+    public void put(E e) throws InterruptedException {
+        if (e == null) throw new NullPointerException();
+        final E[] items = this.items;
+        final ReentrantLock lock = this.lock;
+        lock.lockInterruptibly();
+        try {
+            try {
+                while (count == items.length)
+                    notFull.await();
+            } catch (InterruptedException ie) {
+                notFull.signal(); // propagate to non-interrupted thread
+                throw ie;
+            }
+            insert(e);
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    /**
+     * Inserts the specified element at the tail of this queue, waiting
+     * up to the specified wait time for space to become available if
+     * the queue is full.
+     *
+     * @throws InterruptedException {@inheritDoc}
+     * @throws NullPointerException {@inheritDoc}
      */
-    public boolean offer(E o, long timeout, TimeUnit unit)
+    public boolean offer(E e, long timeout, TimeUnit unit)
         throws InterruptedException {
 
-        if (o == null) throw new NullPointerException();
+        if (e == null) throw new NullPointerException();
+        long nanos = unit.toNanos(timeout);
         final ReentrantLock lock = this.lock;
         lock.lockInterruptibly();
         try {
-            long nanos = unit.toNanos(timeout);
             for (;;) {
                 if (count != items.length) {
-                    insert(o);
+                    insert(e);
                     return true;
                 }
                 if (nanos <= 0)
@@ -254,7 +294,6 @@
         }
     }
 
-
     public E poll() {
         final ReentrantLock lock = this.lock;
         lock.lock();
@@ -268,11 +307,29 @@
         }
     }
 
+    public E take() throws InterruptedException {
+        final ReentrantLock lock = this.lock;
+        lock.lockInterruptibly();
+        try {
+            try {
+                while (count == 0)
+                    notEmpty.await();
+            } catch (InterruptedException ie) {
+                notEmpty.signal(); // propagate to non-interrupted thread
+                throw ie;
+            }
+            E x = extract();
+            return x;
+        } finally {
+            lock.unlock();
+        }
+    }
+
     public E poll(long timeout, TimeUnit unit) throws InterruptedException {
+        long nanos = unit.toNanos(timeout);
         final ReentrantLock lock = this.lock;
         lock.lockInterruptibly();
         try {
-            long nanos = unit.toNanos(timeout);
             for (;;) {
                 if (count != 0) {
                     E x = extract();
@@ -293,30 +350,6 @@
         }
     }
 
-
-    public boolean remove(Object o) {
-        if (o == null) return false;
-        final E[] items = this.items;
-        final ReentrantLock lock = this.lock;
-        lock.lock();
-        try {
-            int i = takeIndex;
-            int k = 0;
-            for (;;) {
-                if (k++ >= count)
-                    return false;
-                if (o.equals(items[i])) {
-                    removeAt(i);
-                    return true;
-                }
-                i = inc(i);
-            }
-
-        } finally {
-            lock.unlock();
-        }
-    }
-
     public E peek() {
         final ReentrantLock lock = this.lock;
         lock.lock();
@@ -327,56 +360,12 @@
         }
     }
 
-    public E take() throws InterruptedException {
-        final ReentrantLock lock = this.lock;
-        lock.lockInterruptibly();
-        try {
-            try {
-                while (count == 0)
-                    notEmpty.await();
-            } catch (InterruptedException ie) {
-                notEmpty.signal(); // propagate to non-interrupted thread
-                throw ie;
-            }
-            E x = extract();
-            return x;
-        } finally {
-            lock.unlock();
-        }
-    }
-
-    /**
-     * Adds the specified element to the tail of this queue, waiting if
-     * necessary for space to become available.
-     * @param o the element to add
-     * @throws InterruptedException if interrupted while waiting.
-     * @throws NullPointerException if the specified element is <tt>null</tt>.
-     */
-    public void put(E o) throws InterruptedException {
-        if (o == null) throw new NullPointerException();
-        final E[] items = this.items;
-        final ReentrantLock lock = this.lock;
-        lock.lockInterruptibly();
-        try {
-            try {
-                while (count == items.length)
-                    notFull.await();
-            } catch (InterruptedException ie) {
-                notFull.signal(); // propagate to non-interrupted thread
-                throw ie;
-            }
-            insert(o);
-        } finally {
-            lock.unlock();
-        }
-    }
-
     // this doc comment is overridden to remove the reference to collections
     // greater in size than Integer.MAX_VALUE
     /**
      * Returns the number of elements in this queue.
      *
-     * @return  the number of elements in this queue.
+     * @return the number of elements in this queue
      */
     public int size() {
         final ReentrantLock lock = this.lock;
@@ -391,15 +380,15 @@
     // this doc comment is a modified copy of the inherited doc comment,
     // without the reference to unlimited queues.
     /**
-     * Returns the number of elements that this queue can ideally (in
-     * the absence of memory or resource constraints) accept without
+     * Returns the number of additional elements that this queue can ideally
+     * (in the absence of memory or resource constraints) accept without
      * blocking. This is always equal to the initial capacity of this queue
      * less the current <tt>size</tt> of this queue.
-     * <p>Note that you <em>cannot</em> always tell if
-     * an attempt to <tt>add</tt> an element will succeed by
-     * inspecting <tt>remainingCapacity</tt> because it may be the
-     * case that a waiting consumer is ready to <tt>take</tt> an
-     * element out of an otherwise full queue.
+     *
+     * <p>Note that you <em>cannot</em> always tell if an attempt to insert
+     * an element will succeed by inspecting <tt>remainingCapacity</tt>
+     * because it may be the case that another thread is about to
+     * insert or remove an element.
      */
     public int remainingCapacity() {
         final ReentrantLock lock = this.lock;
@@ -411,7 +400,48 @@
         }
     }
 
+    /**
+     * Removes a single instance of the specified element from this queue,
+     * if it is present.  More formally, removes an element <tt>e</tt> such
+     * that <tt>o.equals(e)</tt>, if this queue contains one or more such
+     * elements.
+     * Returns <tt>true</tt> if this queue contained the specified element
+     * (or equivalently, if this queue changed as a result of the call).
+     *
+     * @param o element to be removed from this queue, if present
+     * @return <tt>true</tt> if this queue changed as a result of the call
+     */
+    public boolean remove(Object o) {
+        if (o == null) return false;
+        final E[] items = this.items;
+        final ReentrantLock lock = this.lock;
+        lock.lock();
+        try {
+            int i = takeIndex;
+            int k = 0;
+            for (;;) {
+                if (k++ >= count)
+                    return false;
+                if (o.equals(items[i])) {
+                    removeAt(i);
+                    return true;
+                }
+                i = inc(i);
+            }
+
+        } finally {
+            lock.unlock();
+        }
+    }
 
+    /**
+     * Returns <tt>true</tt> if this queue contains the specified element.
+     * More formally, returns <tt>true</tt> if and only if this queue contains
+     * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
+     *
+     * @param o object to be checked for containment in this queue
+     * @return <tt>true</tt> if this queue contains the specified element
+     */
     public boolean contains(Object o) {
         if (o == null) return false;
         final E[] items = this.items;
@@ -431,6 +461,19 @@
         }
     }
 
+    /**
+     * Returns an array containing all of the elements in this queue, in
+     * proper sequence.
+     *
+     * <p>The returned array will be "safe" in that no references to it are
+     * maintained by this queue.  (In other words, this method must allocate
+     * a new array).  The caller is thus free to modify the returned array.
+     *
+     * <p>This method acts as bridge between array-based and collection-based
+     * APIs.
+     *
+     * @return an array containing all of the elements in this queue
+     */
     public Object[] toArray() {
         final E[] items = this.items;
         final ReentrantLock lock = this.lock;
@@ -449,6 +492,42 @@
         }
     }
 
+    /**
+     * Returns an array containing all of the elements in this queue, in
+     * proper sequence; the runtime type of the returned array is that of
+     * the specified array.  If the queue fits in the specified array, it
+     * is returned therein.  Otherwise, a new array is allocated with the
+     * runtime type of the specified array and the size of this queue.
+     *
+     * <p>If this queue fits in the specified array with room to spare
+     * (i.e., the array has more elements than this queue), the element in
+     * the array immediately following the end of the queue is set to
+     * <tt>null</tt>.
+     *
+     * <p>Like the {@link #toArray()} method, this method acts as bridge between
+     * array-based and collection-based APIs.  Further, this method allows
+     * precise control over the runtime type of the output array, and may,
+     * under certain circumstances, be used to save allocation costs.
+     *
+     * <p>Suppose <tt>x</tt> is a queue known to contain only strings.
+     * The following code can be used to dump the queue into a newly
+     * allocated array of <tt>String</tt>:
+     *
+     * <pre>
+     *     String[] y = x.toArray(new String[0]);</pre>
+     *
+     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
+     * <tt>toArray()</tt>.
+     *
+     * @param a the array into which the elements of the queue are to
+     *          be stored, if it is big enough; otherwise, a new array of the
+     *          same runtime type is allocated for this purpose
+     * @return an array containing all of the elements in this queue
+     * @throws ArrayStoreException if the runtime type of the specified array
+     *         is not a supertype of the runtime type of every element in
+     *         this queue
+     * @throws NullPointerException if the specified array is null
+     */
     public <T> T[] toArray(T[] a) {
         final E[] items = this.items;
         final ReentrantLock lock = this.lock;
@@ -484,7 +563,10 @@
         }
     }
 
-
+    /**
+     * Atomically removes all of the elements from this queue.
+     * The queue will be empty after this call returns.
+     */
     public void clear() {
         final E[] items = this.items;
         final ReentrantLock lock = this.lock;
@@ -505,6 +587,12 @@
         }
     }
 
+    /**
+     * @throws UnsupportedOperationException {@inheritDoc}
+     * @throws ClassCastException            {@inheritDoc}
+     * @throws NullPointerException          {@inheritDoc}
+     * @throws IllegalArgumentException      {@inheritDoc}
+     */
     public int drainTo(Collection<? super E> c) {
         if (c == null)
             throw new NullPointerException();
@@ -535,7 +623,12 @@
         }
     }
 
-
+    /**
+     * @throws UnsupportedOperationException {@inheritDoc}
+     * @throws ClassCastException            {@inheritDoc}
+     * @throws NullPointerException          {@inheritDoc}
+     * @throws IllegalArgumentException      {@inheritDoc}
+     */
     public int drainTo(Collection<? super E> c, int maxElements) {
         if (c == null)
             throw new NullPointerException();
@@ -572,12 +665,12 @@
     /**
      * Returns an iterator over the elements in this queue in proper sequence.
      * The returned <tt>Iterator</tt> is a "weakly consistent" iterator that
-     * will never throw {@link java.util.ConcurrentModificationException},
+     * will never throw {@link ConcurrentModificationException},
      * and guarantees to traverse elements as they existed upon
      * construction of the iterator, and may (but is not guaranteed to)
      * reflect any modifications subsequent to construction.
      *
-     * @return an iterator over the elements in this queue in proper sequence.
+     * @return an iterator over the elements in this queue in proper sequence
      */
     public Iterator<E> iterator() {
         final ReentrantLock lock = this.lock;
@@ -604,7 +697,7 @@
          * that an element exists in hasNext(), we must return it in
          * the following next() call even if it was in the process of
          * being removed when hasNext() was called.
-         **/
+         */
         private E nextItem;
 
         /**
@@ -633,7 +726,7 @@
         }
 
         /**
-         * Check whether nextIndex is valid; if so setting nextItem.
+         * Checks whether nextIndex is valid; if so setting nextItem.
          * Stops iterator when either hits putIndex or sees null item.
          */
         private void checkNext() {

Modified: harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/BlockingQueue.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/BlockingQueue.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/BlockingQueue.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/BlockingQueue.java Thu Jul 16 14:01:15 2009
@@ -11,9 +11,50 @@
 
 /**
  * A {@link java.util.Queue} that additionally supports operations
- * that wait for the queue to become non-empty when retrieving an element,
- * and wait for space to become available in the queue when storing an 
- * element.
+ * that wait for the queue to become non-empty when retrieving an
+ * element, and wait for space to become available in the queue when
+ * storing an element.
+ *
+ * <p><tt>BlockingQueue</tt> methods come in four forms, with different ways
+ * of handling operations that cannot be satisfied immediately, but may be
+ * satisfied at some point in the future:
+ * one throws an exception, the second returns a special value (either
+ * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
+ * blocks the current thread indefinitely until the operation can succeed,
+ * and the fourth blocks for only a given maximum time limit before giving
+ * up.  These methods are summarized in the following table:
+ *
+ * <p>
+ * <table BORDER CELLPADDING=3 CELLSPACING=1>
+ *  <tr>
+ *    <td></td>
+ *    <td ALIGN=CENTER><em>Throws exception</em></td>
+ *    <td ALIGN=CENTER><em>Special value</em></td>
+ *    <td ALIGN=CENTER><em>Blocks</em></td>
+ *    <td ALIGN=CENTER><em>Times out</em></td>
+ *  </tr>
+ *  <tr>
+ *    <td><b>Insert</b></td>
+ *    <td>{@link #add add(e)}</td>
+ *    <td>{@link #offer offer(e)}</td>
+ *    <td>{@link #put put(e)}</td>
+ *    <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
+ *  </tr>
+ *  <tr>
+ *    <td><b>Remove</b></td>
+ *    <td>{@link #remove remove()}</td>
+ *    <td>{@link #poll poll()}</td>
+ *    <td>{@link #take take()}</td>
+ *    <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
+ *  </tr>
+ *  <tr>
+ *    <td><b>Examine</b></td>
+ *    <td>{@link #element element()}</td>
+ *    <td>{@link #peek peek()}</td>
+ *    <td><em>not applicable</em></td>
+ *    <td><em>not applicable</em></td>
+ *  </tr>
+ * </table>
  *
  * <p>A <tt>BlockingQueue</tt> does not accept <tt>null</tt> elements.
  * Implementations throw <tt>NullPointerException</tt> on attempts
@@ -27,16 +68,22 @@
  * A <tt>BlockingQueue</tt> without any intrinsic capacity constraints always
  * reports a remaining capacity of <tt>Integer.MAX_VALUE</tt>.
  *
- * <p> While <tt>BlockingQueue</tt> is designed to be used primarily
- * for producer-consumer queues, it additionally supports the {@link
- * java.util.Collection} interface.  So, for example, it is possible
- * to remove an arbitrary element from a queue using
+ * <p> <tt>BlockingQueue</tt> implementations are designed to be used
+ * primarily for producer-consumer queues, but additionally support
+ * the {@link java.util.Collection} interface.  So, for example, it is
+ * possible to remove an arbitrary element from a queue using
  * <tt>remove(x)</tt>. However, such operations are in general
  * <em>not</em> performed very efficiently, and are intended for only
- * occasional use, such as when a queued message is cancelled.  Also,
- * the bulk Collection operations, most notably <tt>addAll</tt>, are
- * <em>not</em> necessarily performed atomically, so it is possible
- * for <tt>addAll(c)</tt> to fail (throwing an exception) after adding
+ * occasional use, such as when a queued message is cancelled.
+ *
+ * <p> <tt>BlockingQueue</tt> implementations are thread-safe.  All
+ * queuing methods achieve their effects atomically using internal
+ * locks or other forms of concurrency control. However, the
+ * <em>bulk</em> Collection operations <tt>addAll</tt>,
+ * <tt>containsAll</tt>, <tt>retainAll</tt> and <tt>removeAll</tt> are
+ * <em>not</em> necessarily performed atomically unless specified
+ * otherwise in an implementation. So it is possible, for example, for
+ * <tt>addAll(c)</tt> to fail (throwing an exception) after adding
  * only some of the elements in <tt>c</tt>.
  *
  * <p>A <tt>BlockingQueue</tt> does <em>not</em> intrinsically support
@@ -57,7 +104,7 @@
  *   Producer(BlockingQueue q) { queue = q; }
  *   public void run() {
  *     try {
- *       while(true) { queue.put(produce()); }
+ *       while (true) { queue.put(produce()); }
  *     } catch (InterruptedException ex) { ... handle ...}
  *   }
  *   Object produce() { ... }
@@ -68,7 +115,7 @@
  *   Consumer(BlockingQueue q) { queue = q; }
  *   public void run() {
  *     try {
- *       while(true) { consume(queue.take()); }
+ *       while (true) { consume(queue.take()); }
  *     } catch (InterruptedException ex) { ... handle ...}
  *   }
  *   void consume(Object x) { ... }
@@ -87,141 +134,211 @@
  * }
  * </pre>
  *
+ * <p>Memory consistency effects: As with other concurrent
+ * collections, actions in a thread prior to placing an object into a
+ * {@code BlockingQueue}
+ * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
+ * actions subsequent to the access or removal of that element from
+ * the {@code BlockingQueue} in another thread.
+ *
  * <p>This interface is a member of the
- * <a href="{@docRoot}/../guide/collections/index.html">
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  * Java Collections Framework</a>.
- *  
+ *
  * @since 1.5
  * @author Doug Lea
  * @param <E> the type of elements held in this collection
  */
 public interface BlockingQueue<E> extends Queue<E> {
+    /**
+     * Inserts the specified element into this queue if it is possible to do
+     * so immediately without violating capacity restrictions, returning
+     * <tt>true</tt> upon success and throwing an
+     * <tt>IllegalStateException</tt> if no space is currently available.
+     * When using a capacity-restricted queue, it is generally preferable to
+     * use {@link #offer(Object) offer}.
+     *
+     * @param e the element to add
+     * @return <tt>true</tt> (as specified by {@link Collection#add})
+     * @throws IllegalStateException if the element cannot be added at this
+     *         time due to capacity restrictions
+     * @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 add(E e);
 
     /**
-     * Inserts the specified element into this queue, if possible.  When
-     * using queues that may impose insertion restrictions (for
-     * example capacity bounds), method <tt>offer</tt> is generally
-     * preferable to method {@link Collection#add}, which can fail to
-     * insert an element only by throwing an exception.
-     *
-     * @param o the element to add.
-     * @return <tt>true</tt> if it was possible to add the element to
-     *         this queue, else <tt>false</tt>
-     * @throws NullPointerException if the specified element is <tt>null</tt>
+     * Inserts the specified element into this queue if it is possible to do
+     * so immediately without violating capacity restrictions, returning
+     * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
+     * available.  When using a capacity-restricted queue, this method is
+     * generally preferable to {@link #add}, which can fail to insert an
+     * element only by throwing an exception.
+     *
+     * @param e the element to add
+     * @return <tt>true</tt> if the element was added to this queue, else
+     *         <tt>false</tt>
+     * @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 offer(E o);
-    
+    boolean offer(E e);
+
     /**
      * Inserts the specified element into this queue, waiting if necessary
-     * up to the specified wait time for space to become available.
-     * @param o the element to add
+     * for space to become available.
+     *
+     * @param e the element to add
+     * @throws InterruptedException if interrupted while waiting
+     * @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
+     */
+    void put(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.
+     *
+     * @param e the element to add
      * @param timeout how long to wait before giving up, in units of
-     * <tt>unit</tt>
+     *        <tt>unit</tt>
      * @param unit a <tt>TimeUnit</tt> determining how to interpret the
-     * <tt>timeout</tt> parameter
+     *        <tt>timeout</tt> parameter
      * @return <tt>true</tt> if successful, or <tt>false</tt> if
-     * the specified waiting time elapses before space is available.
-     * @throws InterruptedException if interrupted while waiting.
-     * @throws NullPointerException if the specified element is <tt>null</tt>.
+     *         the specified waiting time elapses before space is available
+     * @throws InterruptedException if interrupted while waiting
+     * @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 offer(E o, long timeout, TimeUnit unit)
+    boolean offer(E e, long timeout, TimeUnit unit)
         throws InterruptedException;
 
     /**
-     * Retrieves and removes the head of this queue, waiting
-     * if necessary up to the specified wait time if no elements are
-     * present on this queue.
+     * Retrieves and removes the head of this queue, waiting if necessary
+     * until an element becomes available.
+     *
+     * @return the head of this queue
+     * @throws InterruptedException if interrupted while waiting
+     */
+    E take() throws InterruptedException;
+
+    /**
+     * Retrieves and removes the head of this queue, waiting up to the
+     * specified wait time if necessary for an element to become available.
+     *
      * @param timeout how long to wait before giving up, in units of
-     * <tt>unit</tt>
+     *        <tt>unit</tt>
      * @param unit a <tt>TimeUnit</tt> determining how to interpret the
-     * <tt>timeout</tt> parameter
+     *        <tt>timeout</tt> parameter
      * @return the head of this queue, or <tt>null</tt> if the
-     * specified waiting time elapses before an element is present.
-     * @throws InterruptedException if interrupted while waiting.
+     *         specified waiting time elapses before an element is available
+     * @throws InterruptedException if interrupted while waiting
      */
     E poll(long timeout, TimeUnit unit)
         throws InterruptedException;
 
     /**
-     * Retrieves and removes the head of this queue, waiting
-     * if no elements are present on this queue.
-     * @return the head of this queue
-     * @throws InterruptedException if interrupted while waiting.
+     * Returns the number of additional elements that this queue can ideally
+     * (in the absence of memory or resource constraints) accept without
+     * blocking, or <tt>Integer.MAX_VALUE</tt> if there is no intrinsic
+     * limit.
+     *
+     * <p>Note that you <em>cannot</em> always tell if an attempt to insert
+     * an element will succeed by inspecting <tt>remainingCapacity</tt>
+     * because it may be the case that another thread is about to
+     * insert or remove an element.
+     *
+     * @return the remaining capacity
      */
-    E take() throws InterruptedException;
+    int remainingCapacity();
 
     /**
-     * Adds the specified element to this queue, waiting if necessary for
-     * space to become available.
-     * @param o the element to add
-     * @throws InterruptedException if interrupted while waiting.
-     * @throws NullPointerException if the specified element is <tt>null</tt>.
-     */
-    void put(E o) throws InterruptedException;
-
-    /**
-     * Returns the number of elements that this queue can ideally (in
-     * the absence of memory or resource constraints) accept without
-     * blocking, or <tt>Integer.MAX_VALUE</tt> if there is no
-     * intrinsic limit.
-     * <p>Note that you <em>cannot</em> always tell if
-     * an attempt to <tt>add</tt> an element will succeed by
-     * inspecting <tt>remainingCapacity</tt> because it may be the
-     * case that a waiting consumer is ready to <tt>take</tt> an
-     * element out of an otherwise full queue.
-     * @return the remaining capacity
+     * Removes a single instance of the specified element from this queue,
+     * if it is present.  More formally, removes an element <tt>e</tt> such
+     * that <tt>o.equals(e)</tt>, if this queue contains one or more such
+     * elements.
+     * Returns <tt>true</tt> if this queue contained the specified element
+     * (or equivalently, if this queue changed as a result of the call).
+     *
+     * @param o element to be removed from this queue, if present
+     * @return <tt>true</tt> if this queue changed as a result of the call
+     * @throws ClassCastException if the class of the specified element
+     *         is incompatible with this queue (optional)
+     * @throws NullPointerException if the specified element is null (optional)
      */
-    int remainingCapacity();
+    boolean remove(Object o);
 
     /**
-     * Adds the specified element to this queue if it is possible to
-     * do so immediately, returning <tt>true</tt> upon success, else
-     * throwing an IllegalStateException.  
-     * @param o the element
-     * @return <tt>true</tt> (as per the general contract of
-     *         <tt>Collection.add</tt>).
+     * Returns <tt>true</tt> if this queue contains the specified element.
+     * More formally, returns <tt>true</tt> if and only if this queue contains
+     * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
      *
-     * @throws NullPointerException if the specified element is <tt>null</tt>
-     * @throws IllegalStateException if element cannot be added
+     * @param o object to be checked for containment in this queue
+     * @return <tt>true</tt> if this queue contains the specified element
+     * @throws ClassCastException if the class of the specified element
+     *         is incompatible with this queue (optional)
+     * @throws NullPointerException if the specified element is null (optional)
      */
-    boolean add(E o);
+    public boolean contains(Object o);
 
     /**
      * Removes all available elements from this queue and adds them
-     * into the given collection.  This operation may be more
+     * to the given collection.  This operation may be more
      * efficient than repeatedly polling this queue.  A failure
-     * encountered while attempting to <tt>add</tt> elements to
+     * encountered while attempting to add elements to
      * collection <tt>c</tt> may result in elements being in neither,
      * either or both collections when the associated exception is
-     * thrown. Attempts to drain a queue to itself result in
+     * thrown.  Attempts to drain a queue to itself result in
      * <tt>IllegalArgumentException</tt>. Further, the behavior of
      * this operation is undefined if the specified collection is
      * modified while the operation is in progress.
      *
      * @param c the collection to transfer elements into
-     * @return the number of elements transferred.
-     * @throws NullPointerException if c is null
-     * @throws IllegalArgumentException if c is this queue
-     * 
+     * @return the number of elements transferred
+     * @throws UnsupportedOperationException if addition of elements
+     *         is not supported by the specified collection
+     * @throws ClassCastException if the class of an element of this queue
+     *         prevents it from being added to the specified collection
+     * @throws NullPointerException if the specified collection is null
+     * @throws IllegalArgumentException if the specified collection is this
+     *         queue, or some property of an element of this queue prevents
+     *         it from being added to the specified collection
      */
     int drainTo(Collection<? super E> c);
-    
+
     /**
      * Removes at most the given number of available elements from
-     * this queue and adds them into the given collection.  A failure
-     * encountered while attempting to <tt>add</tt> elements to
+     * this queue and adds them to the given collection.  A failure
+     * encountered while attempting to add elements to
      * collection <tt>c</tt> may result in elements being in neither,
      * either or both collections when the associated exception is
-     * thrown. Attempts to drain a queue to itself result in
+     * thrown.  Attempts to drain a queue to itself result in
      * <tt>IllegalArgumentException</tt>. Further, the behavior of
      * this operation is undefined if the specified collection is
      * modified while the operation is in progress.
      *
      * @param c the collection to transfer elements into
      * @param maxElements the maximum number of elements to transfer
-     * @return the number of elements transferred.
-     * @throws NullPointerException if c is null
-     * @throws IllegalArgumentException if c is this queue
+     * @return the number of elements transferred
+     * @throws UnsupportedOperationException if addition of elements
+     *         is not supported by the specified collection
+     * @throws ClassCastException if the class of an element of this queue
+     *         prevents it from being added to the specified collection
+     * @throws NullPointerException if the specified collection is null
+     * @throws IllegalArgumentException if the specified collection is this
+     *         queue, or some property of an element of this queue prevents
+     *         it from being added to the specified collection
      */
     int drainTo(Collection<? super E> c, int maxElements);
 }

Modified: harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CompletionService.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CompletionService.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CompletionService.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/CompletionService.java Thu Jul 16 14:01:15 2009
@@ -16,52 +16,56 @@
  * submitted in one part of a program or system, and then acted upon
  * in a different part of the program when the reads complete,
  * possibly in a different order than they were requested.
-
- * <p>
  *
- * Typically, a <tt>CompletionService</tt> relies on a separate {@link
- * Executor} to actually execute the tasks, in which case the
+ * <p>Typically, a <tt>CompletionService</tt> relies on a separate
+ * {@link Executor} to actually execute the tasks, in which case the
  * <tt>CompletionService</tt> only manages an internal completion
  * queue. The {@link ExecutorCompletionService} class provides an
  * implementation of this approach.
  *
+ * <p>Memory consistency effects: Actions in a thread prior to
+ * submitting a task to a {@code CompletionService}
+ * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
+ * actions taken by that task, which in turn <i>happen-before</i>
+ * actions following a successful return from the corresponding {@code take()}.
+ *
  */
 public interface CompletionService<V> {
     /**
      * Submits a value-returning task for execution and returns a Future
-     * representing the pending results of the task. Upon completion,
+     * representing the pending results of the task.  Upon completion,
      * this task may be taken or polled.
      *
      * @param task the task to submit
      * @return a Future representing pending completion of the task
-     * @throws RejectedExecutionException if task cannot be scheduled
-     * for execution
-     * @throws NullPointerException if task null     
+     * @throws RejectedExecutionException if the task cannot be
+     *         scheduled for execution
+     * @throws NullPointerException if the task is null
      */
     Future<V> submit(Callable<V> task);
 
-
     /**
-     * Submits a Runnable task for execution and returns a Future 
-     * representing that task. Upon completion,
-     * this task may be taken or polled.
+     * Submits a Runnable task for execution and returns a Future
+     * representing that task.  Upon completion, this task may be
+     * taken or polled.
      *
      * @param task the task to submit
      * @param result the result to return upon successful completion
      * @return a Future representing pending completion of the task,
-     * and whose <tt>get()</tt> method will return the given result value 
-     * upon completion
-     * @throws RejectedExecutionException if task cannot be scheduled
-     * for execution
-     * @throws NullPointerException if task null     
+     *         and whose <tt>get()</tt> method will return the given
+     *         result value upon completion
+     * @throws RejectedExecutionException if the task cannot be
+     *         scheduled for execution
+     * @throws NullPointerException if the task is null
      */
     Future<V> submit(Runnable task, V result);
 
     /**
      * Retrieves and removes the Future representing the next
      * completed task, waiting if none are yet present.
+     *
      * @return the Future representing the next completed task
-     * @throws InterruptedException if interrupted while waiting.
+     * @throws InterruptedException if interrupted while waiting
      */
     Future<V> take() throws InterruptedException;
 
@@ -71,7 +75,7 @@
      * completed task or <tt>null</tt> if none are present.
      *
      * @return the Future representing the next completed task, or
-     * <tt>null</tt> if none are present.
+     *         <tt>null</tt> if none are present
      */
     Future<V> poll();
 
@@ -79,14 +83,15 @@
      * Retrieves and removes the Future representing the next
      * completed task, waiting if necessary up to the specified wait
      * time if none are yet present.
+     *
      * @param timeout how long to wait before giving up, in units of
-     * <tt>unit</tt>
+     *        <tt>unit</tt>
      * @param unit a <tt>TimeUnit</tt> determining how to interpret the
-     * <tt>timeout</tt> parameter
+     *        <tt>timeout</tt> parameter
      * @return the Future representing the next completed task or
-     * <tt>null</tt> if the specified waiting time elapses before one
-     * is present.
-     * @throws InterruptedException if interrupted while waiting.
+     *         <tt>null</tt> if the specified waiting time elapses
+     *         before one is present
+     * @throws InterruptedException if interrupted while waiting
      */
     Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException;
 }



Mime
View raw message