harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hinde...@apache.org
Subject svn commit: r798469 [18/28] - in /harmony/enhanced/classlib/branches/java6: ./ depends/build/platform/ depends/files/ depends/jars/ depends/manifests/icu4j_4.0/ depends/manifests/icu4j_4.2.1/ depends/manifests/icu4j_4.2.1/META-INF/ make/ modules/access...
Date Tue, 28 Jul 2009 09:30:48 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java?rev=798469&r1=798468&r2=798469&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java Tue Jul 28 09:30:33 2009
@@ -9,13 +9,13 @@
 import java.util.Date;
 
 /**
- * <tt>Condition</tt> factors out the <tt>Object</tt> monitor
+ * {@code Condition} factors out the {@code Object} monitor
  * methods ({@link Object#wait() wait}, {@link Object#notify notify}
  * and {@link Object#notifyAll notifyAll}) into distinct objects to
  * give the effect of having multiple wait-sets per object, by
  * combining them with the use of arbitrary {@link Lock} implementations.
- * Where a <tt>Lock</tt> replaces the use of <tt>synchronized</tt> methods
- * and statements, a <tt>Condition</tt> replaces the use of the Object
+ * Where a {@code Lock} replaces the use of {@code synchronized} methods
+ * and statements, a {@code Condition} replaces the use of the Object
  * monitor methods.
  *
  * <p>Conditions (also known as <em>condition queues</em> or
@@ -26,37 +26,37 @@
  * must be protected, so a lock of some form is associated with the
  * condition. The key property that waiting for a condition provides
  * is that it <em>atomically</em> releases the associated lock and
- * suspends the current thread, just like <tt>Object.wait</tt>.
+ * suspends the current thread, just like {@code Object.wait}.
  *
- * <p>A <tt>Condition</tt> instance is intrinsically bound to a lock.
- * To obtain a <tt>Condition</tt> instance for a particular {@link Lock} 
+ * <p>A {@code Condition} instance is intrinsically bound to a lock.
+ * To obtain a {@code Condition} instance for a particular {@link Lock}
  * instance use its {@link Lock#newCondition newCondition()} method.
  *
  * <p>As an example, suppose we have a bounded buffer which supports
- * <tt>put</tt> and <tt>take</tt> methods.  If a
- * <tt>take</tt> is attempted on an empty buffer, then the thread will block
- * until an item becomes available; if a <tt>put</tt> is attempted on a
+ * {@code put} and {@code take} methods.  If a
+ * {@code take} is attempted on an empty buffer, then the thread will block
+ * until an item becomes available; if a {@code put} is attempted on a
  * full buffer, then the thread will block until a space becomes available.
- * We would like to keep waiting <tt>put</tt> threads and <tt>take</tt>
+ * We would like to keep waiting {@code put} threads and {@code take}
  * threads in separate wait-sets so that we can use the optimization of
  * only notifying a single thread at a time when items or spaces become
- * available in the buffer. This can be achieved using two 
+ * available in the buffer. This can be achieved using two
  * {@link Condition} instances.
  * <pre>
  * class BoundedBuffer {
- *   <b>Lock lock = new ReentrantLock();</b>
+ *   <b>final Lock lock = new ReentrantLock();</b>
  *   final Condition notFull  = <b>lock.newCondition(); </b>
  *   final Condition notEmpty = <b>lock.newCondition(); </b>
  *
- *   Object[] items = new Object[100];
+ *   final Object[] items = new Object[100];
  *   int putptr, takeptr, count;
  *
  *   public void put(Object x) throws InterruptedException {
  *     <b>lock.lock();
  *     try {</b>
- *       while (count == items.length) 
+ *       while (count == items.length)
  *         <b>notFull.await();</b>
- *       items[putptr] = x; 
+ *       items[putptr] = x;
  *       if (++putptr == items.length) putptr = 0;
  *       ++count;
  *       <b>notEmpty.signal();</b>
@@ -68,9 +68,9 @@
  *   public Object take() throws InterruptedException {
  *     <b>lock.lock();
  *     try {</b>
- *       while (count == 0) 
+ *       while (count == 0)
  *         <b>notEmpty.await();</b>
- *       Object x = items[takeptr]; 
+ *       Object x = items[takeptr];
  *       if (++takeptr == items.length) takeptr = 0;
  *       --count;
  *       <b>notFull.signal();</b>
@@ -78,7 +78,7 @@
  *     <b>} finally {
  *       lock.unlock();
  *     }</b>
- *   } 
+ *   }
  * }
  * </pre>
  *
@@ -86,61 +86,63 @@
  * this functionality, so there is no reason to implement this
  * sample usage class.)
  *
- * <p>A <tt>Condition</tt> implementation can provide behavior and semantics 
- * that is 
- * different from that of the <tt>Object</tt> monitor methods, such as 
- * guaranteed ordering for notifications, or not requiring a lock to be held 
+ * <p>A {@code Condition} implementation can provide behavior and semantics
+ * that is
+ * different from that of the {@code Object} monitor methods, such as
+ * guaranteed ordering for notifications, or not requiring a lock to be held
  * when performing notifications.
- * If an implementation provides such specialized semantics then the 
+ * If an implementation provides such specialized semantics then the
  * implementation must document those semantics.
  *
- * <p>Note that <tt>Condition</tt> instances are just normal objects and can 
- * themselves be used as the target in a <tt>synchronized</tt> statement,
+ * <p>Note that {@code Condition} instances are just normal objects and can
+ * themselves be used as the target in a {@code synchronized} statement,
  * and can have their own monitor {@link Object#wait wait} and
  * {@link Object#notify notification} methods invoked.
- * Acquiring the monitor lock of a <tt>Condition</tt> instance, or using its
+ * Acquiring the monitor lock of a {@code Condition} instance, or using its
  * monitor methods, has no specified relationship with acquiring the
- * {@link Lock} associated with that <tt>Condition</tt> or the use of its
- * {@link #await waiting} and {@link #signal signalling} methods.
- * It is recommended that to avoid confusion you never use <tt>Condition</tt>
+ * {@link Lock} associated with that {@code Condition} or the use of its
+ * {@linkplain #await waiting} and {@linkplain #signal signalling} methods.
+ * It is recommended that to avoid confusion you never use {@code Condition}
  * instances in this way, except perhaps within their own implementation.
  *
- * <p>Except where noted, passing a <tt>null</tt> value for any parameter 
+ * <p>Except where noted, passing a {@code null} value for any parameter
  * will result in a {@link NullPointerException} being thrown.
  *
  * <h3>Implementation Considerations</h3>
  *
- * <p>When waiting upon a <tt>Condition</tt>, a &quot;<em>spurious
- * wakeup</em>&quot; is permitted to occur, in 
+ * <p>When waiting upon a {@code Condition}, a &quot;<em>spurious
+ * wakeup</em>&quot; is permitted to occur, in
  * general, as a concession to the underlying platform semantics.
  * This has little practical impact on most application programs as a
- * <tt>Condition</tt> should always be waited upon in a loop, testing
+ * {@code Condition} should always be waited upon in a loop, testing
  * the state predicate that is being waited for.  An implementation is
- * free to remove the possibility of spurious wakeups but it is 
+ * free to remove the possibility of spurious wakeups but it is
  * recommended that applications programmers always assume that they can
  * occur and so always wait in a loop.
  *
- * <p>The three forms of condition waiting 
- * (interruptible, non-interruptible, and timed) may differ in their ease of 
+ * <p>The three forms of condition waiting
+ * (interruptible, non-interruptible, and timed) may differ in their ease of
  * implementation on some platforms and in their performance characteristics.
- * In particular, it may be difficult to provide these features and maintain 
- * specific semantics such as ordering guarantees. 
- * Further, the ability to interrupt the actual suspension of the thread may 
+ * In particular, it may be difficult to provide these features and maintain
+ * specific semantics such as ordering guarantees.
+ * Further, the ability to interrupt the actual suspension of the thread may
  * not always be feasible to implement on all platforms.
- * <p>Consequently, an implementation is not required to define exactly the 
- * same guarantees or semantics for all three forms of waiting, nor is it 
+ *
+ * <p>Consequently, an implementation is not required to define exactly the
+ * same guarantees or semantics for all three forms of waiting, nor is it
  * required to support interruption of the actual suspension of the thread.
+ *
  * <p>An implementation is required to
- * clearly document the semantics and guarantees provided by each of the 
- * waiting methods, and when an implementation does support interruption of 
- * thread suspension then it must obey the interruption semantics as defined 
+ * clearly document the semantics and guarantees provided by each of the
+ * waiting methods, and when an implementation does support interruption of
+ * thread suspension then it must obey the interruption semantics as defined
  * in this interface.
- * <p>As interruption generally implies cancellation, and checks for 
+ *
+ * <p>As interruption generally implies cancellation, and checks for
  * interruption are often infrequent, an implementation can favor responding
  * to an interrupt over normal method return. This is true even if it can be
- * shown that the interrupt occurred after another action may have unblocked
- * the thread. An implementation should document this behavior. 
- *
+ * shown that the interrupt occurred after another action that may have
+ * unblocked the thread. An implementation should document this behavior.
  *
  * @since 1.5
  * @author Doug Lea
@@ -148,21 +150,21 @@
 public interface Condition {
 
     /**
-     * Causes the current thread to wait until it is signalled or 
-     * {@link Thread#interrupt interrupted}.
+     * Causes the current thread to wait until it is signalled or
+     * {@linkplain Thread#interrupt interrupted}.
      *
-     * <p>The lock associated with this <tt>Condition</tt> is atomically 
-     * released and the current thread becomes disabled for thread scheduling 
+     * <p>The lock associated with this {@code Condition} is atomically
+     * released and the current thread becomes disabled for thread scheduling
      * purposes and lies dormant until <em>one</em> of four things happens:
      * <ul>
-     * <li>Some other thread invokes the {@link #signal} method for this 
-     * <tt>Condition</tt> and the current thread happens to be chosen as the 
+     * <li>Some other thread invokes the {@link #signal} method for this
+     * {@code Condition} and the current thread happens to be chosen as the
      * thread to be awakened; or
-     * <li>Some other thread invokes the {@link #signalAll} method for this 
-     * <tt>Condition</tt>; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread, and interruption of thread suspension is supported; or
-     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs
+     * <li>Some other thread invokes the {@link #signalAll} method for this
+     * {@code Condition}; or
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
+     * current thread, and interruption of thread suspension is supported; or
+     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
      * </ul>
      *
      * <p>In all cases, before this method can return the current thread must
@@ -171,20 +173,21 @@
      *
      * <p>If the current thread:
      * <ul>
-     * <li>has its interrupted status set on entry to this method; or 
-     * <li>is {@link Thread#interrupt interrupted} while waiting 
-     * and interruption of thread suspension is supported, 
+     * <li>has its interrupted status set on entry to this method; or
+     * <li>is {@linkplain Thread#interrupt interrupted} while waiting
+     * and interruption of thread suspension is supported,
      * </ul>
-     * then {@link InterruptedException} is thrown and the current thread's 
+     * then {@link InterruptedException} is thrown and the current thread's
      * interrupted status is cleared. It is not specified, in the first
      * case, whether or not the test for interruption occurs before the lock
      * is released.
-     * 
+     *
      * <p><b>Implementation Considerations</b>
+     *
      * <p>The current thread is assumed to hold the lock associated with this
-     * <tt>Condition</tt> when this method is called.
+     * {@code Condition} when this method is called.
      * It is up to the implementation to determine if this is
-     * the case and if not, how to respond. Typically, an exception will be 
+     * the case and if not, how to respond. Typically, an exception will be
      * thrown (such as {@link IllegalMonitorStateException}) and the
      * implementation must document that fact.
      *
@@ -193,62 +196,62 @@
      * must ensure that the signal is redirected to another waiting thread, if
      * there is one.
      *
-     * @throws InterruptedException if the current thread is interrupted (and
-     * interruption of thread suspension is supported).
-     **/
+     * @throws InterruptedException if the current thread is interrupted
+     *         (and interruption of thread suspension is supported)
+     */
     void await() throws InterruptedException;
 
     /**
      * Causes the current thread to wait until it is signalled.
      *
-     * <p>The lock associated with this condition is atomically 
-     * released and the current thread becomes disabled for thread scheduling 
+     * <p>The lock associated with this condition is atomically
+     * released and the current thread becomes disabled for thread scheduling
      * purposes and lies dormant until <em>one</em> of three things happens:
      * <ul>
-     * <li>Some other thread invokes the {@link #signal} method for this 
-     * <tt>Condition</tt> and the current thread happens to be chosen as the 
+     * <li>Some other thread invokes the {@link #signal} method for this
+     * {@code Condition} and the current thread happens to be chosen as the
      * thread to be awakened; or
-     * <li>Some other thread invokes the {@link #signalAll} method for this 
-     * <tt>Condition</tt>; or
-     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs
+     * <li>Some other thread invokes the {@link #signalAll} method for this
+     * {@code Condition}; or
+     * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
      * </ul>
      *
      * <p>In all cases, before this method can return the current thread must
      * re-acquire the lock associated with this condition. When the
      * thread returns it is <em>guaranteed</em> to hold this lock.
      *
-     * <p>If the current thread's interrupt status is set when it enters
-     * this method, or it is {@link Thread#interrupt interrupted} 
+     * <p>If the current thread's interrupted status is set when it enters
+     * this method, or it is {@linkplain Thread#interrupt interrupted}
      * while waiting, it will continue to wait until signalled. When it finally
-     * returns from this method its <em>interrupted status</em> will still
+     * returns from this method its interrupted status will still
      * be set.
-     * 
+     *
      * <p><b>Implementation Considerations</b>
+     *
      * <p>The current thread is assumed to hold the lock associated with this
-     * <tt>Condition</tt> when this method is called.
+     * {@code Condition} when this method is called.
      * It is up to the implementation to determine if this is
-     * the case and if not, how to respond. Typically, an exception will be 
+     * the case and if not, how to respond. Typically, an exception will be
      * thrown (such as {@link IllegalMonitorStateException}) and the
      * implementation must document that fact.
-     *
-     **/
+     */
     void awaitUninterruptibly();
 
     /**
      * Causes the current thread to wait until it is signalled or interrupted,
      * or the specified waiting time elapses.
      *
-     * <p>The lock associated with this condition is atomically 
-     * released and the current thread becomes disabled for thread scheduling 
+     * <p>The lock associated with this condition is atomically
+     * released and the current thread becomes disabled for thread scheduling
      * purposes and lies dormant until <em>one</em> of five things happens:
      * <ul>
-     * <li>Some other thread invokes the {@link #signal} method for this 
-     * <tt>Condition</tt> and the current thread happens to be chosen as the 
-     * thread to be awakened; or 
-     * <li>Some other thread invokes the {@link #signalAll} method for this 
-     * <tt>Condition</tt>; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread, and interruption of thread suspension is supported; or
+     * <li>Some other thread invokes the {@link #signal} method for this
+     * {@code Condition} and the current thread happens to be chosen as the
+     * thread to be awakened; or
+     * <li>Some other thread invokes the {@link #signalAll} method for this
+     * {@code Condition}; or
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
+     * current thread, and interruption of thread suspension is supported; or
      * <li>The specified waiting time elapses; or
      * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
      * </ul>
@@ -259,17 +262,17 @@
      *
      * <p>If the current thread:
      * <ul>
-     * <li>has its interrupted status set on entry to this method; or 
-     * <li>is {@link Thread#interrupt interrupted} while waiting 
-     * and interruption of thread suspension is supported, 
+     * <li>has its interrupted status set on entry to this method; or
+     * <li>is {@linkplain Thread#interrupt interrupted} while waiting
+     * and interruption of thread suspension is supported,
      * </ul>
-     * then {@link InterruptedException} is thrown and the current thread's 
+     * then {@link InterruptedException} is thrown and the current thread's
      * interrupted status is cleared. It is not specified, in the first
      * case, whether or not the test for interruption occurs before the lock
      * is released.
      *
      * <p>The method returns an estimate of the number of nanoseconds
-     * remaining to wait given the supplied <tt>nanosTimeout</tt>
+     * remaining to wait given the supplied {@code nanosTimeout}
      * value upon return, or a value less than or equal to zero if it
      * timed out. This value can be used to determine whether and how
      * long to re-wait in cases where the wait returns but an awaited
@@ -285,7 +288,7 @@
      *      else
      *        return false;
      *   }
-     *   // ... 
+     *   // ...
      * }
      * </pre>
      *
@@ -296,10 +299,11 @@
      * than specified when re-waits occur.
      *
      * <p><b>Implementation Considerations</b>
+     *
      * <p>The current thread is assumed to hold the lock associated with this
-     * <tt>Condition</tt> when this method is called.
+     * {@code Condition} when this method is called.
      * It is up to the implementation to determine if this is
-     * the case and if not, how to respond. Typically, an exception will be 
+     * the case and if not, how to respond. Typically, an exception will be
      * thrown (such as {@link IllegalMonitorStateException}) and the
      * implementation must document that fact.
      *
@@ -310,13 +314,14 @@
      * there is one.
      *
      * @param nanosTimeout the maximum time to wait, in nanoseconds
-     * @return A value less than or equal to zero if the wait has
-     * timed out; otherwise an estimate, that
-     * is strictly less than the <tt>nanosTimeout</tt> argument,
-     * of the time still remaining when this method returned.
-     *
-     * @throws InterruptedException if the current thread is interrupted (and
-     * interruption of thread suspension is supported).
+     * @return an estimate of the {@code nanosTimeout} value minus
+     *         the time spent waiting upon return from this method.
+     *         A positive value may be used as the argument to a
+     *         subsequent call to this method to finish waiting out
+     *         the desired time.  A value less than or equal to zero
+     *         indicates that no time remains.
+     * @throws InterruptedException if the current thread is interrupted
+     *         (and interruption of thread suspension is supported)
      */
     long awaitNanos(long nanosTimeout) throws InterruptedException;
 
@@ -328,29 +333,29 @@
      *   awaitNanos(unit.toNanos(time)) &gt; 0
      * </pre>
      * @param time the maximum time to wait
-     * @param unit the time unit of the <tt>time</tt> argument.
-     * @return <tt>false</tt> if the waiting time detectably elapsed
-     * before return from the method, else <tt>true</tt>.
-     * @throws InterruptedException if the current thread is interrupted (and
-     * interruption of thread suspension is supported).
+     * @param unit the time unit of the {@code time} argument
+     * @return {@code false} if the waiting time detectably elapsed
+     *         before return from the method, else {@code true}
+     * @throws InterruptedException if the current thread is interrupted
+     *         (and interruption of thread suspension is supported)
      */
     boolean await(long time, TimeUnit unit) throws InterruptedException;
-    
+
     /**
      * Causes the current thread to wait until it is signalled or interrupted,
      * or the specified deadline elapses.
      *
-     * <p>The lock associated with this condition is atomically 
-     * released and the current thread becomes disabled for thread scheduling 
+     * <p>The lock associated with this condition is atomically
+     * released and the current thread becomes disabled for thread scheduling
      * purposes and lies dormant until <em>one</em> of five things happens:
      * <ul>
-     * <li>Some other thread invokes the {@link #signal} method for this 
-     * <tt>Condition</tt> and the current thread happens to be chosen as the 
-     * thread to be awakened; or 
-     * <li>Some other thread invokes the {@link #signalAll} method for this 
-     * <tt>Condition</tt>; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread, and interruption of thread suspension is supported; or
+     * <li>Some other thread invokes the {@link #signal} method for this
+     * {@code Condition} and the current thread happens to be chosen as the
+     * thread to be awakened; or
+     * <li>Some other thread invokes the {@link #signalAll} method for this
+     * {@code Condition}; or
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
+     * current thread, and interruption of thread suspension is supported; or
      * <li>The specified deadline elapses; or
      * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
      * </ul>
@@ -362,11 +367,11 @@
      *
      * <p>If the current thread:
      * <ul>
-     * <li>has its interrupted status set on entry to this method; or 
-     * <li>is {@link Thread#interrupt interrupted} while waiting 
-     * and interruption of thread suspension is supported, 
+     * <li>has its interrupted status set on entry to this method; or
+     * <li>is {@linkplain Thread#interrupt interrupted} while waiting
+     * and interruption of thread suspension is supported,
      * </ul>
-     * then {@link InterruptedException} is thrown and the current thread's 
+     * then {@link InterruptedException} is thrown and the current thread's
      * interrupted status is cleared. It is not specified, in the first
      * case, whether or not the test for interruption occurs before the lock
      * is released.
@@ -378,20 +383,21 @@
      * synchronized boolean aMethod(Date deadline) {
      *   boolean stillWaiting = true;
      *   while (!conditionBeingWaitedFor) {
-     *     if (stillwaiting)
+     *     if (stillWaiting)
      *         stillWaiting = theCondition.awaitUntil(deadline);
      *      else
      *        return false;
      *   }
-     *   // ... 
+     *   // ...
      * }
      * </pre>
      *
      * <p><b>Implementation Considerations</b>
+     *
      * <p>The current thread is assumed to hold the lock associated with this
-     * <tt>Condition</tt> when this method is called.
+     * {@code Condition} when this method is called.
      * It is up to the implementation to determine if this is
-     * the case and if not, how to respond. Typically, an exception will be 
+     * the case and if not, how to respond. Typically, an exception will be
      * thrown (such as {@link IllegalMonitorStateException}) and the
      * implementation must document that fact.
      *
@@ -401,13 +407,11 @@
      * must ensure that the signal is redirected to another waiting thread, if
      * there is one.
      *
-     *
      * @param deadline the absolute time to wait until
-     * @return <tt>false</tt> if the deadline has
-     * elapsed upon return, else <tt>true</tt>.
-     *
-     * @throws InterruptedException if the current thread is interrupted (and
-     * interruption of thread suspension is supported).
+     * @return {@code false} if the deadline has elapsed upon return, else
+     *         {@code true}
+     * @throws InterruptedException if the current thread is interrupted
+     *         (and interruption of thread suspension is supported)
      */
     boolean awaitUntil(Date deadline) throws InterruptedException;
 
@@ -416,8 +420,8 @@
      *
      * <p>If any threads are waiting on this condition then one
      * is selected for waking up. That thread must then re-acquire the
-     * lock before returning from <tt>await</tt>.
-     **/
+     * lock before returning from {@code await}.
+     */
     void signal();
 
     /**
@@ -425,15 +429,7 @@
      *
      * <p>If any threads are waiting on this condition then they are
      * all woken up. Each thread must re-acquire the lock before it can
-     * return from <tt>await</tt>.
-     **/
+     * return from {@code await}.
+     */
     void signalAll();
-
 }
-
-
-
-
-
-
-

Modified: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java?rev=798469&r1=798468&r2=798469&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java Tue Jul 28 09:30:33 2009
@@ -8,8 +8,8 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * <tt>Lock</tt> implementations provide more extensive locking
- * operations than can be obtained using <tt>synchronized</tt> methods
+ * {@code Lock} implementations provide more extensive locking
+ * operations than can be obtained using {@code synchronized} methods
  * and statements.  They allow more flexible structuring, may have
  * quite different properties, and may support multiple associated
  * {@link Condition} objects.
@@ -19,17 +19,16 @@
  * shared resource: only one thread at a time can acquire the lock and
  * all access to the shared resource requires that the lock be
  * acquired first. However, some locks may allow concurrent access to
- * a shared resource, such as the read lock of a {@link
- * ReadWriteLock}.
+ * a shared resource, such as the read lock of a {@link ReadWriteLock}.
  *
- * <p>The use of <tt>synchronized</tt> methods or statements provides 
+ * <p>The use of {@code synchronized} methods or statements provides
  * access to the implicit monitor lock associated with every object, but
  * forces all lock acquisition and release to occur in a block-structured way:
  * when multiple locks are acquired they must be released in the opposite
  * order, and all locks must be released in the same lexical scope in which
  * they were acquired.
  *
- * <p>While the scoping mechanism for <tt>synchronized</tt> methods
+ * <p>While the scoping mechanism for {@code synchronized} methods
  * and statements makes it much easier to program with monitor locks,
  * and helps avoid many common programming errors involving locks,
  * there are occasions where you need to work with locks in a more
@@ -38,18 +37,18 @@
  * &quot;hand-over-hand&quot; or &quot;chain locking&quot;: you
  * acquire the lock of node A, then node B, then release A and acquire
  * C, then release B and acquire D and so on.  Implementations of the
- * <tt>Lock</tt> interface enable the use of such techniques by
+ * {@code Lock} interface enable the use of such techniques by
  * allowing a lock to be acquired and released in different scopes,
  * and allowing multiple locks to be acquired and released in any
  * order.
  *
  * <p>With this increased flexibility comes additional
  * responsibility. The absence of block-structured locking removes the
- * automatic release of locks that occurs with <tt>synchronized</tt>
+ * automatic release of locks that occurs with {@code synchronized}
  * methods and statements. In most cases, the following idiom
  * should be used:
  *
- * <pre><tt>     Lock l = ...; 
+ * <pre><tt>     Lock l = ...;
  *     l.lock();
  *     try {
  *         // access the resource protected by this lock
@@ -63,39 +62,42 @@
  * held is protected by try-finally or try-catch to ensure that the
  * lock is released when necessary.
  *
- * <p><tt>Lock</tt> implementations provide additional functionality
- * over the use of <tt>synchronized</tt> methods and statements by
+ * <p>{@code Lock} implementations provide additional functionality
+ * over the use of {@code synchronized} methods and statements by
  * providing a non-blocking attempt to acquire a lock ({@link
  * #tryLock()}), an attempt to acquire the lock that can be
  * interrupted ({@link #lockInterruptibly}, and an attempt to acquire
  * the lock that can timeout ({@link #tryLock(long, TimeUnit)}).
  *
- * <p>A <tt>Lock</tt> class can also provide behavior and semantics
+ * <p>A {@code Lock} class can also provide behavior and semantics
  * that is quite different from that of the implicit monitor lock,
  * such as guaranteed ordering, non-reentrant usage, or deadlock
  * detection. If an implementation provides such specialized semantics
  * then the implementation must document those semantics.
  *
- * <p>Note that <tt>Lock</tt> instances are just normal objects and can 
- * themselves be used as the target in a <tt>synchronized</tt> statement.
+ * <p>Note that {@code Lock} instances are just normal objects and can
+ * themselves be used as the target in a {@code synchronized} statement.
  * Acquiring the
- * monitor lock of a <tt>Lock</tt> instance has no specified relationship
- * with invoking any of the {@link #lock} methods of that instance. 
- * It is recommended that to avoid confusion you never use <tt>Lock</tt>
+ * monitor lock of a {@code Lock} instance has no specified relationship
+ * with invoking any of the {@link #lock} methods of that instance.
+ * It is recommended that to avoid confusion you never use {@code Lock}
  * instances in this way, except within their own implementation.
  *
- * <p>Except where noted, passing a <tt>null</tt> value for any
+ * <p>Except where noted, passing a {@code null} value for any
  * parameter will result in a {@link NullPointerException} being
  * thrown.
  *
  * <h3>Memory Synchronization</h3>
- * <p>All <tt>Lock</tt> implementations <em>must</em> enforce the same
- * memory synchronization semantics as provided by the built-in monitor lock:
+ *
+ * <p>All {@code Lock} implementations <em>must</em> enforce the same
+ * memory synchronization semantics as provided by the built-in monitor
+ * lock, as described in <a href="http://java.sun.com/docs/books/jls/">
+ * The Java Language Specification, Third Edition (17.4 Memory Model)</a>:
  * <ul>
- * <li>A successful lock operation acts like a successful 
- * <tt>monitorEnter</tt> action
- * <li>A successful <tt>unlock</tt> operation acts like a successful
- * <tt>monitorExit</tt> action
+ * <li>A successful {@code lock} operation has the same memory
+ * synchronization effects as a successful <em>Lock</em> action.
+ * <li>A successful {@code unlock} operation has the same
+ * memory synchronization effects as a successful <em>Unlock</em> action.
  * </ul>
  *
  * Unsuccessful locking and unlocking operations, and reentrant
@@ -108,7 +110,7 @@
  * non-interruptible, and timed) may differ in their performance
  * characteristics, ordering guarantees, or other implementation
  * qualities.  Further, the ability to interrupt the <em>ongoing</em>
- * acquisition of a lock may not be available in a given <tt>Lock</tt>
+ * acquisition of a lock may not be available in a given {@code Lock}
  * class.  Consequently, an implementation is not required to define
  * exactly the same guarantees or semantics for all three forms of
  * lock acquisition, nor is it required to support interruption of an
@@ -119,12 +121,11 @@
  * acquisition is supported: which is either totally, or only on
  * method entry.
  *
- * <p>As interruption generally implies cancellation, and checks for 
+ * <p>As interruption generally implies cancellation, and checks for
  * interruption are often infrequent, an implementation can favor responding
  * to an interrupt over normal method return. This is true even if it can be
  * shown that the interrupt occurred after another action may have unblocked
- * the thread. An implementation should document this behavior. 
- *
+ * the thread. An implementation should document this behavior.
  *
  * @see ReentrantLock
  * @see Condition
@@ -132,45 +133,50 @@
  *
  * @since 1.5
  * @author Doug Lea
- *
- **/
+ */
 public interface Lock {
 
     /**
      * Acquires the lock.
-     * <p>If the lock is not available then
-     * the current thread becomes disabled for thread scheduling 
-     * purposes and lies dormant until the lock has been acquired.
+     *
+     * <p>If the lock is not available then the current thread becomes
+     * disabled for thread scheduling purposes and lies dormant until the
+     * lock has been acquired.
+     *
      * <p><b>Implementation Considerations</b>
-     * <p>A <tt>Lock</tt> implementation may be able to detect 
-     * erroneous use of the lock, such as an invocation that would cause 
-     * deadlock, and may throw an (unchecked) exception in such circumstances. 
-     * The circumstances and the exception type must be documented by that 
-     * <tt>Lock</tt> implementation.
      *
-     **/
+     * <p>A {@code Lock} implementation may be able to detect erroneous use
+     * of the lock, such as an invocation that would cause deadlock, and
+     * may throw an (unchecked) exception in such circumstances.  The
+     * circumstances and the exception type must be documented by that
+     * {@code Lock} implementation.
+     */
     void lock();
 
     /**
-     * Acquires the lock unless the current thread is  
-     * {@link Thread#interrupt interrupted}. 
+     * Acquires the lock unless the current thread is
+     * {@linkplain Thread#interrupt interrupted}.
+     *
      * <p>Acquires the lock if it is available and returns immediately.
-     * <p>If the lock is not available then
-     * the current thread becomes disabled for thread scheduling 
-     * purposes and lies dormant until one of two things happens:
+     *
+     * <p>If the lock is not available then the current thread becomes
+     * disabled for thread scheduling purposes and lies dormant until
+     * one of two things happens:
+     *
      * <ul>
      * <li>The lock is acquired by the current thread; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread, and interruption of lock acquisition is supported.
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
+     * current thread, and interruption of lock acquisition is supported.
      * </ul>
+     *
      * <p>If the current thread:
      * <ul>
-     * <li>has its interrupted status set on entry to this method; or 
-     * <li>is {@link Thread#interrupt interrupted} while acquiring 
-     * the lock, and interruption of lock acquisition is supported, 
+     * <li>has its interrupted status set on entry to this method; or
+     * <li>is {@linkplain Thread#interrupt interrupted} while acquiring the
+     * lock, and interruption of lock acquisition is supported,
      * </ul>
-     * then {@link InterruptedException} is thrown and the current thread's 
-     * interrupted status is cleared. 
+     * then {@link InterruptedException} is thrown and the current thread's
+     * interrupted status is cleared.
      *
      * <p><b>Implementation Considerations</b>
      *
@@ -183,28 +189,26 @@
      * <p>An implementation can favor responding to an interrupt over
      * normal method return.
      *
-     * <p>A <tt>Lock</tt> implementation may be able to detect
+     * <p>A {@code Lock} implementation may be able to detect
      * erroneous use of the lock, such as an invocation that would
      * cause deadlock, and may throw an (unchecked) exception in such
      * circumstances.  The circumstances and the exception type must
-     * be documented by that <tt>Lock</tt> implementation.
-     *
-     * @throws InterruptedException if the current thread is interrupted
-     * while acquiring the lock (and interruption of lock acquisition is 
-     * supported).
+     * be documented by that {@code Lock} implementation.
      *
-     * @see Thread#interrupt
-     *
-     **/
+     * @throws InterruptedException if the current thread is
+     *         interrupted while acquiring the lock (and interruption
+     *         of lock acquisition is supported).
+     */
     void lockInterruptibly() throws InterruptedException;
 
-
     /**
      * Acquires the lock only if it is free at the time of invocation.
+     *
      * <p>Acquires the lock if it is available and returns immediately
-     * with the value <tt>true</tt>.
-     * If the lock is not available then this method will return 
-     * immediately with the value <tt>false</tt>.
+     * with the value {@code true}.
+     * If the lock is not available then this method will return
+     * immediately with the value {@code false}.
+     *
      * <p>A typical usage idiom for this method would be:
      * <pre>
      *      Lock lock = ...;
@@ -221,109 +225,103 @@
      * This usage ensures that the lock is unlocked if it was acquired, and
      * doesn't try to unlock if the lock was not acquired.
      *
-     * @return <tt>true</tt> if the lock was acquired and <tt>false</tt>
-     * otherwise.
-     **/
+     * @return {@code true} if the lock was acquired and
+     *         {@code false} otherwise
+     */
     boolean tryLock();
 
     /**
      * Acquires the lock if it is free within the given waiting time and the
-     * current thread has not been {@link Thread#interrupt interrupted}.
+     * current thread has not been {@linkplain Thread#interrupt interrupted}.
      *
      * <p>If the lock is available this method returns immediately
-     * with the value <tt>true</tt>.
+     * with the value {@code true}.
      * If the lock is not available then
-     * the current thread becomes disabled for thread scheduling 
+     * the current thread becomes disabled for thread scheduling
      * purposes and lies dormant until one of three things happens:
      * <ul>
      * <li>The lock is acquired by the current thread; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread, and interruption of lock acquisition is supported; or
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
+     * current thread, and interruption of lock acquisition is supported; or
      * <li>The specified waiting time elapses
      * </ul>
-     * <p>If the lock is acquired then the value <tt>true</tt> is returned.
+     *
+     * <p>If the lock is acquired then the value {@code true} is returned.
+     *
      * <p>If the current thread:
      * <ul>
-     * <li>has its interrupted status set on entry to this method; or 
-     * <li>is {@link Thread#interrupt interrupted} while acquiring 
-     * the lock, and interruption of lock acquisition is supported, 
+     * <li>has its interrupted status set on entry to this method; or
+     * <li>is {@linkplain Thread#interrupt interrupted} while acquiring
+     * the lock, and interruption of lock acquisition is supported,
      * </ul>
-     * then {@link InterruptedException} is thrown and the current thread's 
-     * interrupted status is cleared. 
-     * <p>If the specified waiting time elapses then the value <tt>false</tt>
+     * then {@link InterruptedException} is thrown and the current thread's
+     * interrupted status is cleared.
+     *
+     * <p>If the specified waiting time elapses then the value {@code false}
      * is returned.
-     * If the time is 
+     * If the time is
      * less than or equal to zero, the method will not wait at all.
      *
      * <p><b>Implementation Considerations</b>
+     *
      * <p>The ability to interrupt a lock acquisition in some implementations
-     * may not be possible, and if possible may 
-     * be an expensive operation. 
+     * may not be possible, and if possible may
+     * be an expensive operation.
      * The programmer should be aware that this may be the case. An
      * implementation should document when this is the case.
-     * <p>An implementation can favor responding to an interrupt over normal 
+     *
+     * <p>An implementation can favor responding to an interrupt over normal
      * method return, or reporting a timeout.
-     * <p>A <tt>Lock</tt> implementation may be able to detect 
-     * erroneous use of the lock, such as an invocation that would cause 
-     * deadlock, and may throw an (unchecked) exception in such circumstances. 
-     * The circumstances and the exception type must be documented by that 
-     * <tt>Lock</tt> implementation.
+     *
+     * <p>A {@code Lock} implementation may be able to detect
+     * erroneous use of the lock, such as an invocation that would cause
+     * deadlock, and may throw an (unchecked) exception in such circumstances.
+     * The circumstances and the exception type must be documented by that
+     * {@code Lock} implementation.
      *
      * @param time the maximum time to wait for the lock
-     * @param unit the time unit of the <tt>time</tt> argument.
-     * @return <tt>true</tt> if the lock was acquired and <tt>false</tt>
-     * if the waiting time elapsed before the lock was acquired.
+     * @param unit the time unit of the {@code time} argument
+     * @return {@code true} if the lock was acquired and {@code false}
+     *         if the waiting time elapsed before the lock was acquired
      *
      * @throws InterruptedException if the current thread is interrupted
-     * while acquiring the lock (and interruption of lock acquisition is 
-     * supported).
-     *
-     * @see Thread#interrupt
-     *
-     **/
+     *         while acquiring the lock (and interruption of lock
+     *         acquisition is supported)
+     */
     boolean tryLock(long time, TimeUnit unit) throws InterruptedException;
 
     /**
      * Releases the lock.
+     *
      * <p><b>Implementation Considerations</b>
-     * <p>A <tt>Lock</tt> implementation will usually impose
+     *
+     * <p>A {@code Lock} implementation will usually impose
      * restrictions on which thread can release a lock (typically only the
      * holder of the lock can release it) and may throw
      * an (unchecked) exception if the restriction is violated.
      * Any restrictions and the exception
-     * type must be documented by that <tt>Lock</tt> implementation.
-     **/
+     * type must be documented by that {@code Lock} implementation.
+     */
     void unlock();
 
     /**
-     * Returns a new {@link Condition} instance that is bound to this 
-     * <tt>Lock</tt> instance.
-     * <p>Before waiting on the condition the lock must be held by the 
-     * current thread. 
-     * A call to {@link Condition#await()} will atomically release the lock 
+     * Returns a new {@link Condition} instance that is bound to this
+     * {@code Lock} instance.
+     *
+     * <p>Before waiting on the condition the lock must be held by the
+     * current thread.
+     * A call to {@link Condition#await()} will atomically release the lock
      * before waiting and re-acquire the lock before the wait returns.
+     *
      * <p><b>Implementation Considerations</b>
-     * <p>The exact operation of the {@link Condition} instance depends on the
-     * <tt>Lock</tt> implementation and must be documented by that
+     *
+     * <p>The exact operation of the {@link Condition} instance depends on
+     * the {@code Lock} implementation and must be documented by that
      * implementation.
-     * 
-     * @return A new {@link Condition} instance for this <tt>Lock</tt> 
-     * instance.
-     * @throws UnsupportedOperationException if this <tt>Lock</tt> 
-     * implementation does not support conditions.
-     **/
+     *
+     * @return A new {@link Condition} instance for this {@code Lock} instance
+     * @throws UnsupportedOperationException if this {@code Lock}
+     *         implementation does not support conditions
+     */
     Condition newCondition();
-
 }
-
-
-
-
-
-
-
-
-
-
-
-

Modified: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java?rev=798469&r1=798468&r2=798469&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java Tue Jul 28 09:30:33 2009
@@ -13,49 +13,56 @@
  * Basic thread blocking primitives for creating locks and other
  * synchronization classes.
  *
- * <p>This class associates with each thread that uses it, a permit
+ * <p>This class associates, with each thread that uses it, a permit
  * (in the sense of the {@link java.util.concurrent.Semaphore
- * Semaphore} class). A call to <tt>park</tt> will return immediately
+ * Semaphore} class). A call to {@code park} will return immediately
  * if the permit is available, consuming it in the process; otherwise
- * it <em>may</em> block.  A call to <tt>unpark</tt> makes the permit
+ * it <em>may</em> block.  A call to {@code unpark} makes the permit
  * available, if it was not already available. (Unlike with Semaphores
  * though, permits do not accumulate. There is at most one.)
  *
- * <p>Methods <tt>park</tt> and <tt>unpark</tt> provide efficient
+ * <p>Methods {@code park} and {@code unpark} provide efficient
  * means of blocking and unblocking threads that do not encounter the
- * problems that cause the deprecated methods <tt>Thread.suspend</tt>
- * and <tt>Thread.resume</tt> to be unusable for such purposes: Races
- * between one thread invoking <tt>park</tt> and another thread trying
- * to <tt>unpark</tt> it will preserve liveness, due to the
- * permit. Additionally, <tt>park</tt> will return if the caller's
+ * problems that cause the deprecated methods {@code Thread.suspend}
+ * and {@code Thread.resume} to be unusable for such purposes: Races
+ * between one thread invoking {@code park} and another thread trying
+ * to {@code unpark} it will preserve liveness, due to the
+ * permit. Additionally, {@code park} will return if the caller's
  * thread was interrupted, and timeout versions are supported. The
- * <tt>park</tt> method may also return at any other time, for "no
+ * {@code park} method may also return at any other time, for "no
  * reason", so in general must be invoked within a loop that rechecks
- * conditions upon return. In this sense <tt>park</tt> serves as an
+ * conditions upon return. In this sense {@code park} serves as an
  * optimization of a "busy wait" that does not waste as much time
- * spinning, but must be paired with an <tt>unpark</tt> to be
+ * spinning, but must be paired with an {@code unpark} to be
  * effective.
  *
  * <p>These methods are designed to be used as tools for creating
  * higher-level synchronization utilities, and are not in themselves
- * useful for most concurrency control applications.
- *
- * <p><b>Sample Usage.</b> Here is a sketch of a First-in-first-out
- * non-reentrant lock class.
- * <pre>
+ * useful for most concurrency control applications.  The {@code park}
+ * method is designed for use only in constructions of the form:
+ * <pre>while (!canProceed()) { ... LockSupport.park(this); }</pre>
+ * where neither {@code canProceed} nor any other actions prior to the
+ * call to {@code park} entail locking or blocking.  Because only one
+ * permit is associated with each thread, any intermediary uses of
+ * {@code park} could interfere with its intended effects.
+ *
+ * <p><b>Sample Usage.</b> Here is a sketch of a first-in-first-out
+ * non-reentrant lock class:
+ * <pre>{@code
  * class FIFOMutex {
- *   private AtomicBoolean locked = new AtomicBoolean(false);
- *   private Queue&lt;Thread&gt; waiters = new ConcurrentLinkedQueue&lt;Thread&gt;();
+ *   private final AtomicBoolean locked = new AtomicBoolean(false);
+ *   private final Queue<Thread> waiters
+ *     = new ConcurrentLinkedQueue<Thread>();
  *
- *   public void lock() { 
+ *   public void lock() {
  *     boolean wasInterrupted = false;
  *     Thread current = Thread.currentThread();
  *     waiters.add(current);
  *
  *     // Block while not first in queue or cannot acquire lock
- *     while (waiters.peek() != current || 
- *            !locked.compareAndSet(false, true)) { 
- *        LockSupport.park();
+ *     while (waiters.peek() != current ||
+ *            !locked.compareAndSet(false, true)) {
+ *        LockSupport.park(this);
  *        if (Thread.interrupted()) // ignore interrupts while waiting
  *          wasInterrupted = true;
  *     }
@@ -68,26 +75,26 @@
  *   public void unlock() {
  *     locked.set(false);
  *     LockSupport.unpark(waiters.peek());
- *   } 
- * }
- * </pre>
+ *   }
+ * }}</pre>
  */
 
 public class LockSupport {
     private LockSupport() {} // Cannot be instantiated.
 
     // Hotspot implementation via intrinsics API
-    private static final Unsafe unsafe =  Unsafe.getUnsafe();
+    private static final Unsafe unsafe = Unsafe.getUnsafe();
 
     /**
-     * Make available the permit for the given thread, if it
+     * Makes available the permit for the given thread, if it
      * was not already available.  If the thread was blocked on
-     * <tt>park</tt> then it will unblock.  Otherwise, its next call
-     * to <tt>park</tt> is guaranteed not to block. This operation
+     * {@code park} then it will unblock.  Otherwise, its next call
+     * to {@code park} is guaranteed not to block. This operation
      * is not guaranteed to have any effect at all if the given
      * thread has not been started.
-     * @param thread the thread to unpark, or <tt>null</tt>, in which case
-     * this operation has no effect. 
+     *
+     * @param thread the thread to unpark, or {@code null}, in which case
+     *        this operation has no effect
      */
     public static void unpark(Thread thread) {
         if (thread != null)
@@ -97,20 +104,26 @@
     /**
      * Disables the current thread for thread scheduling purposes unless the
      * permit is available.
-     * <p>If the permit is available then it is consumed and the call returns
-     * immediately; otherwise 
-     * the current thread becomes disabled for thread scheduling 
-     * purposes and lies dormant until one of three things happens:
+     *
+     * <p>If the permit is available then it is consumed and the call
+     * returns immediately; otherwise the current thread becomes disabled
+     * for thread scheduling purposes and lies dormant until one of three
+     * things happens:
+     *
      * <ul>
-     * <li>Some other thread invokes <tt>unpark</tt> with the current thread 
-     * as the target; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread; or
+     *
+     * <li>Some other thread invokes {@link #unpark unpark} with the
+     * current thread as the target; or
+     *
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts}
+     * the current thread; or
+     *
      * <li>The call spuriously (that is, for no reason) returns.
      * </ul>
-     * <p>This method does <em>not</em> report which of these caused the 
-     * method to return. Callers should re-check the conditions which caused 
-     * the thread to park in the first place. Callers may also determine, 
+     *
+     * <p>This method does <em>not</em> report which of these caused the
+     * method to return. Callers should re-check the conditions which caused
+     * the thread to park in the first place. Callers may also determine,
      * for example, the interrupt status of the thread upon return.
      */
     public static void park() {
@@ -120,21 +133,27 @@
     /**
      * Disables the current thread for thread scheduling purposes, for up to
      * the specified waiting time, unless the permit is available.
-     * <p>If the permit is available then it is consumed and the call returns
-     * immediately; otherwise 
-     * the current thread becomes disabled for thread scheduling 
-     * purposes and lies dormant until one of four things happens:
+     *
+     * <p>If the permit is available then it is consumed and the call
+     * returns immediately; otherwise the current thread becomes disabled
+     * for thread scheduling purposes and lies dormant until one of four
+     * things happens:
+     *
      * <ul>
-     * <li>Some other thread invokes <tt>unpark</tt> with the current thread 
-     * as the target; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread; or
+     * <li>Some other thread invokes {@link #unpark unpark} with the
+     * current thread as the target; or
+     *
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts}
+     * the current thread; or
+     *
      * <li>The specified waiting time elapses; or
+     *
      * <li>The call spuriously (that is, for no reason) returns.
      * </ul>
-     * <p>This method does <em>not</em> report which of these caused the 
-     * method to return. Callers should re-check the conditions which caused 
-     * the thread to park in the first place. Callers may also determine, 
+     *
+     * <p>This method does <em>not</em> report which of these caused the
+     * method to return. Callers should re-check the conditions which caused
+     * the thread to park in the first place. Callers may also determine,
      * for example, the interrupt status of the thread, or the elapsed time
      * upon return.
      *
@@ -142,37 +161,40 @@
      */
     public static void parkNanos(long nanos) {
         if (nanos > 0)
-            unsafe.park(false, nanos);   
+            unsafe.park(false, nanos);
     }
 
     /**
      * Disables the current thread for thread scheduling purposes, until
      * the specified deadline, unless the permit is available.
-     * <p>If the permit is available then it is consumed and the call returns
-     * immediately; otherwise 
-     * the current thread becomes disabled for thread scheduling 
-     * purposes and lies dormant until one of four things happens:
+     *
+     * <p>If the permit is available then it is consumed and the call
+     * returns immediately; otherwise the current thread becomes disabled
+     * for thread scheduling purposes and lies dormant until one of four
+     * things happens:
+     *
      * <ul>
-     * <li>Some other thread invokes <tt>unpark</tt> with the current thread 
-     * as the target; or
-     * <li>Some other thread {@link Thread#interrupt interrupts} the current
-     * thread; or
+     * <li>Some other thread invokes {@link #unpark unpark} with the
+     * current thread as the target; or
+     *
+     * <li>Some other thread {@linkplain Thread#interrupt interrupts}
+     * the current thread; or
+     *
      * <li>The specified deadline passes; or
+     *
      * <li>The call spuriously (that is, for no reason) returns.
      * </ul>
-     * <p>This method does <em>not</em> report which of these caused the 
-     * method to return. Callers should re-check the conditions which caused 
-     * the thread to park in the first place. Callers may also determine, 
+     *
+     * <p>This method does <em>not</em> report which of these caused the
+     * method to return. Callers should re-check the conditions which caused
+     * the thread to park in the first place. Callers may also determine,
      * for example, the interrupt status of the thread, or the current time
      * upon return.
      *
-     * @param deadline the absolute time, in milliseconds from the Epoch, to
-     * wait until
+     * @param deadline the absolute time, in milliseconds from the Epoch,
+     *        to wait until
      */
     public static void parkUntil(long deadline) {
-        unsafe.park(true, deadline);   
+        unsafe.park(true, deadline);
     }
-
 }
-
-

Modified: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java?rev=798469&r1=798468&r2=798469&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java Tue Jul 28 09:30:33 2009
@@ -12,11 +12,18 @@
  * The {@link #readLock read lock} may be held simultaneously by
  * multiple reader threads, so long as there are no writers.  The
  * {@link #writeLock write lock} is exclusive.
- * 
+ *
+ * <p>All <tt>ReadWriteLock</tt> implementations must guarantee that
+ * the memory synchronization effects of <tt>writeLock</tt> operations
+ * (as specified in the {@link Lock} interface) also hold with respect
+ * to the associated <tt>readLock</tt>. That is, a thread successfully
+ * acquiring the read lock will see all updates made upon previous
+ * release of the write lock.
+ *
  * <p>A read-write lock allows for a greater level of concurrency in
- * accessing shared data, than that permitted by a mutual exclusion lock.
+ * accessing shared data than that permitted by a mutual exclusion lock.
  * It exploits the fact that while only a single thread at a time (a
- * <em>writer</em> thread) can modify the shared data, in many cases any 
+ * <em>writer</em> thread) can modify the shared data, in many cases any
  * number of threads can concurrently read the data (hence <em>reader</em>
  * threads).
  * In theory, the increase in concurrency permitted by the use of a read-write
@@ -27,7 +34,7 @@
  *
  * <p>Whether or not a read-write lock will improve performance over the use
  * of a mutual exclusion lock depends on the frequency that the data is
- * read compared to being modified, the duration of the read and write 
+ * read compared to being modified, the duration of the read and write
  * operations, and the contention for the data - that is, the number of
  * threads that will try to read or write the data at the same time.
  * For example, a collection that is initially populated with data and
@@ -56,14 +63,14 @@
  * lengthy delays for a write if the readers are frequent and long-lived as
  * expected. Fair, or &quot;in-order&quot; implementations are also possible.
  *
- * <li>Determining whether readers that request the read lock while a 
+ * <li>Determining whether readers that request the read lock while a
  * reader is active and a writer is waiting, are granted the read lock.
  * Preference to the reader can delay the writer indefinitely, while
- * preference to the write can reduce the potential for concurrency.
+ * preference to the writer can reduce the potential for concurrency.
  *
  * <li>Determining whether the locks are reentrant: can a thread with the
- * write lock reacquire it? can it acquire a read lock while holding the
- * write lock? is the read lock itself reentrant?
+ * write lock reacquire it? Can it acquire a read lock while holding the
+ * write lock? Is the read lock itself reentrant?
  *
  * <li>Can the write lock be downgraded to a read lock without allowing
  * an intervening writer? Can a read lock be upgraded to a write lock,



Mime
View raw message