Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 55679 invoked from network); 28 Jul 2009 09:31:00 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 28 Jul 2009 09:31:00 -0000 Received: (qmail 63560 invoked by uid 500); 28 Jul 2009 09:32:17 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 63517 invoked by uid 500); 28 Jul 2009 09:32:17 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 63508 invoked by uid 99); 28 Jul 2009 09:32:17 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 28 Jul 2009 09:32:17 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 28 Jul 2009 09:32:11 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 0127423889E6; Tue, 28 Jul 2009 09:31:00 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@harmony.apache.org From: hindessm@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090728093100.0127423889E6@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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; /** - * Condition factors out the Object 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 Lock replaces the use of synchronized methods - * and statements, a Condition 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. * *

Conditions (also known as condition queues 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 atomically releases the associated lock and - * suspends the current thread, just like Object.wait. + * suspends the current thread, just like {@code Object.wait}. * - *

A Condition instance is intrinsically bound to a lock. - * To obtain a Condition instance for a particular {@link Lock} + *

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. * *

As an example, suppose we have a bounded buffer which supports - * put and take methods. If a - * take is attempted on an empty buffer, then the thread will block - * until an item becomes available; if a put 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 put threads and take + * 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. * 

  * class BoundedBuffer {
- *   Lock lock = new ReentrantLock();
+ *   final Lock lock = new ReentrantLock();
  *   final Condition notFull  = lock.newCondition(); 
  *   final Condition notEmpty = lock.newCondition(); 
  *
- *   Object[] items = new Object[100];
+ *   final Object[] items = new Object[100];
  *   int putptr, takeptr, count;
  *
  *   public void put(Object x) throws InterruptedException {
  *     lock.lock();
  *     try {
- *       while (count == items.length) 
+ *       while (count == items.length)
  *         notFull.await();
- *       items[putptr] = x; 
+ *       items[putptr] = x;
  *       if (++putptr == items.length) putptr = 0;
  *       ++count;
  *       notEmpty.signal();
@@ -68,9 +68,9 @@
  *   public Object take() throws InterruptedException {
  *     lock.lock();
  *     try {
- *       while (count == 0) 
+ *       while (count == 0)
  *         notEmpty.await();
- *       Object x = items[takeptr]; 
+ *       Object x = items[takeptr];
  *       if (++takeptr == items.length) takeptr = 0;
  *       --count;
  *       notFull.signal();
@@ -78,7 +78,7 @@
  *     } finally {
  *       lock.unlock();
  *     }
- *   } 
+ *   }
  * }
  *
* @@ -86,61 +86,63 @@ * this functionality, so there is no reason to implement this * sample usage class.) * - *

A Condition implementation can provide behavior and semantics - * that is - * different from that of the Object monitor methods, such as - * guaranteed ordering for notifications, or not requiring a lock to be held + *

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. * - *

Note that Condition instances are just normal objects and can - * themselves be used as the target in a synchronized statement, + *

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 Condition 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 Condition or the use of its - * {@link #await waiting} and {@link #signal signalling} methods. - * It is recommended that to avoid confusion you never use Condition + * {@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. * - *

Except where noted, passing a null value for any parameter + *

Except where noted, passing a {@code null} value for any parameter * will result in a {@link NullPointerException} being thrown. * *

Implementation Considerations

* - *

When waiting upon a Condition, a "spurious - * wakeup" is permitted to occur, in + *

When waiting upon a {@code Condition}, a "spurious + * wakeup" 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 - * Condition 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. * - *

The three forms of condition waiting - * (interruptible, non-interruptible, and timed) may differ in their ease of + *

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. - *

Consequently, an implementation is not required to define exactly the - * same guarantees or semantics for all three forms of waiting, nor is it + * + *

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. + * *

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. - *

As interruption generally implies cancellation, and checks for + * + *

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}. * - *

The lock associated with this Condition is atomically - * released and the current thread becomes disabled for thread scheduling + *

The lock associated with this {@code Condition} is atomically + * released and the current thread becomes disabled for thread scheduling * purposes and lies dormant until one of four things happens: *

    - *
  • Some other thread invokes the {@link #signal} method for this - * Condition and the current thread happens to be chosen as the + *
  • 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 - *
  • Some other thread invokes the {@link #signalAll} method for this - * Condition; or - *
  • Some other thread {@link Thread#interrupt interrupts} the current - * thread, and interruption of thread suspension is supported; or - *
  • A "spurious wakeup" occurs + *
  • Some other thread invokes the {@link #signalAll} method for this + * {@code Condition}; or + *
  • Some other thread {@linkplain Thread#interrupt interrupts} the + * current thread, and interruption of thread suspension is supported; or + *
  • A "spurious wakeup" occurs. *
* *

In all cases, before this method can return the current thread must @@ -171,20 +173,21 @@ * *

If the current thread: *

    - *
  • has its interrupted status set on entry to this method; or - *
  • is {@link Thread#interrupt interrupted} while waiting - * and interruption of thread suspension is supported, + *
  • has its interrupted status set on entry to this method; or + *
  • is {@linkplain Thread#interrupt interrupted} while waiting + * and interruption of thread suspension is supported, *
- * 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. - * + * *

Implementation Considerations + * *

The current thread is assumed to hold the lock associated with this - * Condition 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. * - *

The lock associated with this condition is atomically - * released and the current thread becomes disabled for thread scheduling + *

The lock associated with this condition is atomically + * released and the current thread becomes disabled for thread scheduling * purposes and lies dormant until one of three things happens: *

    - *
  • Some other thread invokes the {@link #signal} method for this - * Condition and the current thread happens to be chosen as the + *
  • 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 - *
  • Some other thread invokes the {@link #signalAll} method for this - * Condition; or - *
  • A "spurious wakeup" occurs + *
  • Some other thread invokes the {@link #signalAll} method for this + * {@code Condition}; or + *
  • A "spurious wakeup" occurs. *
* *

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 guaranteed to hold this lock. * - *

If the current thread's interrupt status is set when it enters - * this method, or it is {@link Thread#interrupt interrupted} + *

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 interrupted status will still + * returns from this method its interrupted status will still * be set. - * + * *

Implementation Considerations + * *

The current thread is assumed to hold the lock associated with this - * Condition 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. * - *

The lock associated with this condition is atomically - * released and the current thread becomes disabled for thread scheduling + *

The lock associated with this condition is atomically + * released and the current thread becomes disabled for thread scheduling * purposes and lies dormant until one of five things happens: *

    - *
  • Some other thread invokes the {@link #signal} method for this - * Condition and the current thread happens to be chosen as the - * thread to be awakened; or - *
  • Some other thread invokes the {@link #signalAll} method for this - * Condition; or - *
  • Some other thread {@link Thread#interrupt interrupts} the current - * thread, and interruption of thread suspension is supported; or + *
  • 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 + *
  • Some other thread invokes the {@link #signalAll} method for this + * {@code Condition}; or + *
  • Some other thread {@linkplain Thread#interrupt interrupts} the + * current thread, and interruption of thread suspension is supported; or *
  • The specified waiting time elapses; or *
  • A "spurious wakeup" occurs. *
@@ -259,17 +262,17 @@ * *

If the current thread: *

    - *
  • has its interrupted status set on entry to this method; or - *
  • is {@link Thread#interrupt interrupted} while waiting - * and interruption of thread suspension is supported, + *
  • has its interrupted status set on entry to this method; or + *
  • is {@linkplain Thread#interrupt interrupted} while waiting + * and interruption of thread suspension is supported, *
- * 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. * *

The method returns an estimate of the number of nanoseconds - * remaining to wait given the supplied nanosTimeout + * 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; * } - * // ... + * // ... * } * * @@ -296,10 +299,11 @@ * than specified when re-waits occur. * *

Implementation Considerations + * *

The current thread is assumed to hold the lock associated with this - * Condition 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 nanosTimeout 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)) > 0 * * @param time the maximum time to wait - * @param unit the time unit of the time argument. - * @return false if the waiting time detectably elapsed - * before return from the method, else true. - * @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. * - *

The lock associated with this condition is atomically - * released and the current thread becomes disabled for thread scheduling + *

The lock associated with this condition is atomically + * released and the current thread becomes disabled for thread scheduling * purposes and lies dormant until one of five things happens: *

    - *
  • Some other thread invokes the {@link #signal} method for this - * Condition and the current thread happens to be chosen as the - * thread to be awakened; or - *
  • Some other thread invokes the {@link #signalAll} method for this - * Condition; or - *
  • Some other thread {@link Thread#interrupt interrupts} the current - * thread, and interruption of thread suspension is supported; or + *
  • 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 + *
  • Some other thread invokes the {@link #signalAll} method for this + * {@code Condition}; or + *
  • Some other thread {@linkplain Thread#interrupt interrupts} the + * current thread, and interruption of thread suspension is supported; or *
  • The specified deadline elapses; or *
  • A "spurious wakeup" occurs. *
@@ -362,11 +367,11 @@ * *

If the current thread: *

    - *
  • has its interrupted status set on entry to this method; or - *
  • is {@link Thread#interrupt interrupted} while waiting - * and interruption of thread suspension is supported, + *
  • has its interrupted status set on entry to this method; or + *
  • is {@linkplain Thread#interrupt interrupted} while waiting + * and interruption of thread suspension is supported, *
- * 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; * } - * // ... + * // ... * } * * *

Implementation Considerations + * *

The current thread is assumed to hold the lock associated with this - * Condition 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 false if the deadline has - * elapsed upon return, else true. - * - * @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 @@ * *

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 await. - **/ + * lock before returning from {@code await}. + */ void signal(); /** @@ -425,15 +429,7 @@ * *

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 await. - **/ + * 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; /** - * Lock implementations provide more extensive locking - * operations than can be obtained using synchronized 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}. * - *

The use of synchronized methods or statements provides + *

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. * - *

While the scoping mechanism for synchronized methods + *

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 @@ * "hand-over-hand" or "chain locking": 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 - * Lock 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. * *

With this increased flexibility comes additional * responsibility. The absence of block-structured locking removes the - * automatic release of locks that occurs with synchronized + * automatic release of locks that occurs with {@code synchronized} * methods and statements. In most cases, the following idiom * should be used: * - * 

     Lock l = ...; 
+ * 
     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.
  *
- * 
Lock implementations provide additional functionality
- * over the use of synchronized methods and statements by
+ * 
{@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)}).
  *
- * 
A Lock class can also provide behavior and semantics
+ * 
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.
  *
- * 
Note that Lock instances are just normal objects and can 
- * themselves be used as the target in a synchronized statement.
+ * 
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 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 Lock
+ * 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.
  *
- * 
Except where noted, passing a null value for any
+ * 
Except where noted, passing a {@code null} value for any
  * parameter will result in a {@link NullPointerException} being
  * thrown.
  *
  * 
Memory Synchronization

- * 
All Lock implementations must enforce the same
- * memory synchronization semantics as provided by the built-in monitor lock:
+ *
+ * 
All {@code Lock} implementations must enforce the same
+ * memory synchronization semantics as provided by the built-in monitor
+ * lock, as described in 
+ * The Java Language Specification, Third Edition (17.4 Memory Model):
  * 
    
- * 
  • A successful lock operation acts like a successful 
- * monitorEnter action
- * 
  • A successful unlock operation acts like a successful
- * monitorExit action
+ * 
  • A successful {@code lock} operation has the same memory
+ * synchronization effects as a successful Lock action.
+ * 
  • A successful {@code unlock} operation has the same
+ * memory synchronization effects as a successful Unlock action.
  * 

  *
  * 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 ongoing
- * acquisition of a lock may not be available in a given Lock
+ * 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.
  *
- * 
As interruption generally implies cancellation, and checks for 
+ * 
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.
-     * 
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.
+     *
+     * 
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.
+     *
      * 
Implementation Considerations
-     * 
A 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 
-     * Lock implementation.
      *
-     **/
+     * 
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}.
+     *
      * 
Acquires the lock if it is available and returns immediately.
-     * 
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:
+     *
+     * 
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:
+     *
      * 
    
      * 
  • The lock is acquired by the current thread; or
-     * 
  • Some other thread {@link Thread#interrupt interrupts} the current
-     * thread, and interruption of lock acquisition is supported.
+     * 
  • Some other thread {@linkplain Thread#interrupt interrupts} the
+     * current thread, and interruption of lock acquisition is supported.
      * 

+     *
      * 
If the current thread:
      * 
    
-     * 
  • has its interrupted status set on entry to this method; or 
-     * 
  • is {@link Thread#interrupt interrupted} while acquiring 
-     * the lock, and interruption of lock acquisition is supported, 
+     * 
  • has its interrupted status set on entry to this method; or
+     * 
  • is {@linkplain Thread#interrupt interrupted} while acquiring the
+     * lock, and interruption of lock acquisition is supported,
      * 

-     * 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.
      *
      * 
Implementation Considerations
      *
@@ -183,28 +189,26 @@
      * 
An implementation can favor responding to an interrupt over
      * normal method return.
      *
-     * 
A Lock implementation may be able to detect
+     * 
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 Lock 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.
+     *
      * 
Acquires the lock if it is available and returns immediately
-     * with the value true.
-     * If the lock is not available then this method will return 
-     * immediately with the value false.
+     * with the value {@code true}.
+     * If the lock is not available then this method will return
+     * immediately with the value {@code false}.
+     *
      * 
A typical usage idiom for this method would be:
      * 
      *      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 true if the lock was acquired and false
-     * 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}.
      *
      * 
If the lock is available this method returns immediately
-     * with the value true.
+     * 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:
      * 
    
      * 
  • The lock is acquired by the current thread; or
-     * 
  • Some other thread {@link Thread#interrupt interrupts} the current
-     * thread, and interruption of lock acquisition is supported; or
+     * 
  • Some other thread {@linkplain Thread#interrupt interrupts} the
+     * current thread, and interruption of lock acquisition is supported; or
      * 
  • The specified waiting time elapses
      * 

-     * 
If the lock is acquired then the value true is returned.
+     *
+     * 
If the lock is acquired then the value {@code true} is returned.
+     *
      * 
If the current thread:
      * 
    
-     * 
  • has its interrupted status set on entry to this method; or 
-     * 
  • is {@link Thread#interrupt interrupted} while acquiring 
-     * the lock, and interruption of lock acquisition is supported, 
+     * 
  • has its interrupted status set on entry to this method; or
+     * 
  • is {@linkplain Thread#interrupt interrupted} while acquiring
+     * the lock, and interruption of lock acquisition is supported,
      * 

-     * then {@link InterruptedException} is thrown and the current thread's 
-     * interrupted status is cleared. 
-     * 
If the specified waiting time elapses then the value false
+     * then {@link InterruptedException} is thrown and the current thread's
+     * interrupted status is cleared.
+     *
+     * 
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.
      *
      * 
Implementation Considerations
+     *
      * 
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.
-     * 
An implementation can favor responding to an interrupt over normal 
+     *
+     * 
An implementation can favor responding to an interrupt over normal
      * method return, or reporting a timeout.
-     * 
A 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 
-     * Lock implementation.
+     *
+     * 
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 time argument.
-     * @return true if the lock was acquired and false
-     * 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.
+     *
      * 
Implementation Considerations
-     * 
A Lock implementation will usually impose
+     *
+     * 
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 Lock implementation.
-     **/
+     * type must be documented by that {@code Lock} implementation.
+     */
     void unlock();
 
     /**
-     * Returns a new {@link Condition} instance that is bound to this 
-     * Lock instance.
-     * 
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.
+     *
+     * 
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.
+     *
      * 
Implementation Considerations
-     * 
The exact operation of the {@link Condition} instance depends on the
-     * Lock implementation and must be documented by that
+     *
+     * 
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 Lock 
-     * instance.
-     * @throws UnsupportedOperationException if this Lock 
-     * 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.
  *
- * 
This class associates with each thread that uses it, a permit
+ * 
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 park 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 may block.  A call to unpark makes the permit
+ * it may 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.)
  *
- * 
Methods park and unpark provide efficient
+ * 
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 Thread.suspend
- * and Thread.resume to be unusable for such purposes: Races
- * between one thread invoking park and another thread trying
- * to unpark it will preserve liveness, due to the
- * permit. Additionally, park 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
- * park 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 park 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 unpark to be
+ * spinning, but must be paired with an {@code unpark} to be
  * effective.
  *
  * 
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.
- *
- * 
Sample Usage. Here is a sketch of a First-in-first-out
- * non-reentrant lock class.
- * 
+ * useful for most concurrency control applications.  The {@code park}
+ * method is designed for use only in constructions of the form:
+ * 
while (!canProceed()) { ... LockSupport.park(this); }

+ * 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.
+ *
+ * 
Sample Usage. Here is a sketch of a first-in-first-out
+ * non-reentrant lock class:
+ * 
{@code
  * class FIFOMutex {
- *   private AtomicBoolean locked = new AtomicBoolean(false);
- *   private Queue<Thread> waiters = new ConcurrentLinkedQueue<Thread>();
+ *   private final AtomicBoolean locked = new AtomicBoolean(false);
+ *   private final Queue waiters
+ *     = new ConcurrentLinkedQueue();
  *
- *   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());
- *   } 
- * }
- * 

+ *   }
+ * }}

  */
 
 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
-     * park then it will unblock.  Otherwise, its next call
-     * to park 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 null, 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.
-     * 
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:
+     *
+     * 
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:
+     *
      * 
    
-     * 
  • Some other thread invokes unpark with the current thread 
-     * as the target; or
-     * 
  • Some other thread {@link Thread#interrupt interrupts} the current
-     * thread; or
+     *
+     * 
  • Some other thread invokes {@link #unpark unpark} with the
+     * current thread as the target; or
+     *
+     * 
  • Some other thread {@linkplain Thread#interrupt interrupts}
+     * the current thread; or
+     *
      * 
  • The call spuriously (that is, for no reason) returns.
      * 

-     * 
This method does not 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, 
+     *
+     * 
This method does not 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.
-     * 
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:
+     *
+     * 
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:
+     *
      * 
    
-     * 
  • Some other thread invokes unpark with the current thread 
-     * as the target; or
-     * 
  • Some other thread {@link Thread#interrupt interrupts} the current
-     * thread; or
+     * 
  • Some other thread invokes {@link #unpark unpark} with the
+     * current thread as the target; or
+     *
+     * 
  • Some other thread {@linkplain Thread#interrupt interrupts}
+     * the current thread; or
+     *
      * 
  • The specified waiting time elapses; or
+     *
      * 
  • The call spuriously (that is, for no reason) returns.
      * 

-     * 
This method does not 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, 
+     *
+     * 
This method does not 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.
-     * 
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:
+     *
+     * 
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:
+     *
      * 
    
-     * 
  • Some other thread invokes unpark with the current thread 
-     * as the target; or
-     * 
  • Some other thread {@link Thread#interrupt interrupts} the current
-     * thread; or
+     * 
  • Some other thread invokes {@link #unpark unpark} with the
+     * current thread as the target; or
+     *
+     * 
  • Some other thread {@linkplain Thread#interrupt interrupts}
+     * the current thread; or
+     *
      * 
  • The specified deadline passes; or
+     *
      * 
  • The call spuriously (that is, for no reason) returns.
      * 

-     * 
This method does not 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, 
+     *
+     * 
This method does not 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.
- * 
+ *
+ * 
All ReadWriteLock implementations must guarantee that
+ * the memory synchronization effects of writeLock operations
+ * (as specified in the {@link Lock} interface) also hold with respect
+ * to the associated readLock. That is, a thread successfully
+ * acquiring the read lock will see all updates made upon previous
+ * release of the write lock.
+ *
  * 
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
- * writer thread) can modify the shared data, in many cases any 
+ * writer thread) can modify the shared data, in many cases any
  * number of threads can concurrently read the data (hence reader
  * threads).
  * In theory, the increase in concurrency permitted by the use of a read-write
@@ -27,7 +34,7 @@
  *
  * 
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 "in-order" implementations are also possible.
  *
- * 
  • Determining whether readers that request the read lock while a 
+ * 
  • 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.
  *
  * 
  • 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?
  *
  * 
  • 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,