You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by hi...@apache.org on 2009/07/16 16:01:17 UTC
svn commit: r794678 [15/19] - in
/harmony/enhanced/classlib/trunk/modules/concurrent/src:
main/java/java/util/concurrent/ main/java/java/util/concurrent/atomic/
main/java/java/util/concurrent/locks/ test/java/
Modified: harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Condition.java Thu Jul 16 14:01:15 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 "<em>spurious
- * wakeup</em>" is permitted to occur, in
+ * <p>When waiting upon a {@code Condition}, a "<em>spurious
+ * wakeup</em>" 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 "<em>spurious wakeup</em>" 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 "<em>spurious wakeup</em>" 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 "<em>spurious wakeup</em>" occurs
+ * <li>Some other thread invokes the {@link #signalAll} method for this
+ * {@code Condition}; or
+ * <li>A "<em>spurious wakeup</em>" 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 "<em>spurious wakeup</em>" 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)) > 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 "<em>spurious wakeup</em>" 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/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/Lock.java Thu Jul 16 14:01:15 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 @@
* "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
- * <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/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/LockSupport.java Thu Jul 16 14:01:15 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<Thread> waiters = new ConcurrentLinkedQueue<Thread>();
+ * 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/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java?rev=794678&r1=794677&r2=794678&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java (original)
+++ harmony/enhanced/classlib/trunk/modules/concurrent/src/main/java/java/util/concurrent/locks/ReadWriteLock.java Thu Jul 16 14:01:15 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 "in-order" 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,