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/28 11:30:48 UTC
svn commit: r798469 [19/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...
Modified: harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReentrantLock.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReentrantLock.java?rev=798469&r1=798468&r2=798469&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReentrantLock.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/concurrent/src/main/java/java/util/concurrent/locks/ReentrantLock.java Tue Jul 28 09:30:33 2009
@@ -12,19 +12,19 @@
/**
* A reentrant mutual exclusion {@link Lock} with the same basic
* behavior and semantics as the implicit monitor lock accessed using
- * <tt>synchronized</tt> methods and statements, but with extended
+ * {@code synchronized} methods and statements, but with extended
* capabilities.
*
- * <p> A <tt>ReentrantLock</tt> is <em>owned</em> by the thread last
+ * <p>A {@code ReentrantLock} is <em>owned</em> by the thread last
* successfully locking, but not yet unlocking it. A thread invoking
- * <tt>lock</tt> will return, successfully acquiring the lock, when
+ * {@code lock} will return, successfully acquiring the lock, when
* the lock is not owned by another thread. The method will return
* immediately if the current thread already owns the lock. This can
* be checked using methods {@link #isHeldByCurrentThread}, and {@link
- * #getHoldCount}.
+ * #getHoldCount}.
*
- * <p> The constructor for this class accepts an optional
- * <em>fairness</em> parameter. When set <tt>true</tt>, under
+ * <p>The constructor for this class accepts an optional
+ * <em>fairness</em> parameter. When set {@code true}, under
* contention, locks favor granting access to the longest-waiting
* thread. Otherwise this lock does not guarantee any particular
* access order. Programs using fair locks accessed by many threads
@@ -36,9 +36,12 @@
* fair lock may obtain it multiple times in succession while other
* active threads are not progressing and not currently holding the
* lock.
+ * Also note that the untimed {@link #tryLock() tryLock} method does not
+ * honor the fairness setting. It will succeed if the lock
+ * is available even if other threads are waiting.
*
- * <p> It is recommended practice to <em>always</em> immediately
- * follow a call to <tt>lock</tt> with a <tt>try</tt> block, most
+ * <p>It is recommended practice to <em>always</em> immediately
+ * follow a call to {@code lock} with a {@code try} block, most
* typically in a before/after construction such as:
*
* <pre>
@@ -46,7 +49,7 @@
* private final ReentrantLock lock = new ReentrantLock();
* // ...
*
- * public void m() {
+ * public void m() {
* lock.lock(); // block until condition holds
* try {
* // ... method body
@@ -58,21 +61,21 @@
* </pre>
*
* <p>In addition to implementing the {@link Lock} interface, this
- * class defines methods <tt>isLocked</tt> and
- * <tt>getLockQueueLength</tt>, as well as some associated
- * <tt>protected</tt> access methods that may be useful for
+ * class defines methods {@code isLocked} and
+ * {@code getLockQueueLength}, as well as some associated
+ * {@code protected} access methods that may be useful for
* instrumentation and monitoring.
*
- * <p> Serialization of this class behaves in the same way as built-in
+ * <p>Serialization of this class behaves in the same way as built-in
* locks: a deserialized lock is in the unlocked state, regardless of
* its state when serialized.
*
- * <p> This lock supports a maximum of 2147483648 recursive locks by
- * the same thread.
+ * <p>This lock supports a maximum of 2147483647 recursive locks by
+ * the same thread. Attempts to exceed this limit result in
+ * {@link Error} throws from locking methods.
*
* @since 1.5
* @author Doug Lea
- *
*/
public class ReentrantLock implements Lock, java.io.Serializable {
private static final long serialVersionUID = 7373984872572414699L;
@@ -84,32 +87,34 @@
* into fair and nonfair versions below. Uses AQS state to
* represent the number of holds on the lock.
*/
- static abstract class Sync extends AbstractQueuedSynchronizer {
- /** Current owner thread */
- transient Thread owner;
+ static abstract class Sync extends AbstractQueuedSynchronizer {
+ private static final long serialVersionUID = -5179523762034025860L;
/**
- * Perform {@link Lock#lock}. The main reason for subclassing
+ * Performs {@link Lock#lock}. The main reason for subclassing
* is to allow fast path for nonfair version.
*/
abstract void lock();
- /**
- * Perform non-fair tryLock. tryAcquire is
+ /**
+ * Performs non-fair tryLock. tryAcquire is
* implemented in subclasses, but both need nonfair
- * try for trylock method
+ * try for trylock method.
*/
- final boolean nonfairTryAcquire(int acquires) {
+ final boolean nonfairTryAcquire(int acquires) {
final Thread current = Thread.currentThread();
int c = getState();
if (c == 0) {
if (compareAndSetState(0, acquires)) {
- owner = current;
+ setExclusiveOwnerThread(current);
return true;
}
}
- else if (current == owner) {
- setState(c+acquires);
+ else if (current == getExclusiveOwnerThread()) {
+ int nextc = c + acquires;
+ if (nextc < 0) // overflow
+ throw new Error("Maximum lock count exceeded");
+ setState(nextc);
return true;
}
return false;
@@ -117,19 +122,21 @@
protected final boolean tryRelease(int releases) {
int c = getState() - releases;
- if (Thread.currentThread() != owner)
+ if (Thread.currentThread() != getExclusiveOwnerThread())
throw new IllegalMonitorStateException();
boolean free = false;
if (c == 0) {
free = true;
- owner = null;
+ setExclusiveOwnerThread(null);
}
setState(c);
return free;
}
protected final boolean isHeldExclusively() {
- return getState() != 0 && owner == Thread.currentThread();
+ // While we must in general read state before owner,
+ // we don't need to do so to check if current thread is owner
+ return getExclusiveOwnerThread() == Thread.currentThread();
}
final ConditionObject newCondition() {
@@ -139,23 +146,19 @@
// Methods relayed from outer class
final Thread getOwner() {
- int c = getState();
- Thread o = owner;
- return (c == 0)? null : o;
+ return getState() == 0 ? null : getExclusiveOwnerThread();
}
-
+
final int getHoldCount() {
- int c = getState();
- Thread o = owner;
- return (o == Thread.currentThread())? c : 0;
+ return isHeldExclusively() ? getState() : 0;
}
-
+
final boolean isLocked() {
return getState() != 0;
}
/**
- * Reconstitute this lock instance from a stream
+ * Reconstitutes this lock instance from a stream.
* @param s the stream
*/
private void readObject(java.io.ObjectInputStream s)
@@ -169,18 +172,20 @@
* Sync object for non-fair locks
*/
final static class NonfairSync extends Sync {
+ private static final long serialVersionUID = 7316153563782823691L;
+
/**
- * Perform lock. Try immediate barge, backing up to normal
+ * Performs lock. Try immediate barge, backing up to normal
* acquire on failure.
*/
final void lock() {
if (compareAndSetState(0, 1))
- owner = Thread.currentThread();
+ setExclusiveOwnerThread(Thread.currentThread());
else
acquire(1);
}
- protected final boolean tryAcquire(int acquires) {
+ protected final boolean tryAcquire(int acquires) {
return nonfairTryAcquire(acquires);
}
}
@@ -188,28 +193,32 @@
/**
* Sync object for fair locks
*/
- final static class FairSync extends Sync {
- final void lock() {
- acquire(1);
+ final static class FairSync extends Sync {
+ private static final long serialVersionUID = -3000897897090466540L;
+
+ final void lock() {
+ acquire(1);
}
/**
* Fair version of tryAcquire. Don't grant access unless
* recursive call or no waiters or is first.
*/
- protected final boolean tryAcquire(int acquires) {
+ protected final boolean tryAcquire(int acquires) {
final Thread current = Thread.currentThread();
int c = getState();
if (c == 0) {
- Thread first = getFirstQueuedThread();
- if ((first == null || first == current) &&
+ if (!hasQueuedPredecessors() &&
compareAndSetState(0, acquires)) {
- owner = current;
+ setExclusiveOwnerThread(current);
return true;
}
}
- else if (current == owner) {
- setState(c+acquires);
+ else if (current == getExclusiveOwnerThread()) {
+ int nextc = c + acquires;
+ if (nextc < 0)
+ throw new Error("Maximum lock count exceeded");
+ setState(nextc);
return true;
}
return false;
@@ -217,89 +226,88 @@
}
/**
- * Creates an instance of <tt>ReentrantLock</tt>.
- * This is equivalent to using <tt>ReentrantLock(false)</tt>.
+ * Creates an instance of {@code ReentrantLock}.
+ * This is equivalent to using {@code ReentrantLock(false)}.
*/
- public ReentrantLock() {
+ public ReentrantLock() {
sync = new NonfairSync();
}
/**
- * Creates an instance of <tt>ReentrantLock</tt> with the
+ * Creates an instance of {@code ReentrantLock} with the
* given fairness policy.
- * @param fair true if this lock will be fair; else false
+ *
+ * @param fair {@code true} if this lock should use a fair ordering policy
*/
- public ReentrantLock(boolean fair) {
+ public ReentrantLock(boolean fair) {
sync = (fair)? new FairSync() : new NonfairSync();
}
/**
- * Acquires the lock.
+ * Acquires the lock.
*
- * <p>Acquires the lock if it is not held by another thread and returns
+ * <p>Acquires the lock if it is not held by another thread and returns
* immediately, setting the lock hold count to one.
*
- * <p>If the current thread
- * already holds the lock then the hold count is incremented by one and
- * the method returns immediately.
+ * <p>If the current thread already holds the lock then the hold
+ * count is incremented by one and the method returns immediately.
*
* <p>If the lock is held by another thread then the
- * current thread becomes disabled for thread scheduling
+ * current thread becomes disabled for thread scheduling
* purposes and lies dormant until the lock has been acquired,
- * at which time the lock hold count is set to one.
+ * at which time the lock hold count is set to one.
*/
public void lock() {
sync.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 not held by another thread and returns
+ * <p>Acquires the lock if it is not held by another thread and returns
* immediately, setting the lock hold count to one.
*
- * <p>If the current thread already holds this lock then the hold count
+ * <p>If the current thread already holds this lock then the hold count
* is incremented by one and the method returns immediately.
*
* <p>If the lock is held by another thread then the
- * current thread becomes disabled for thread scheduling
+ * 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.
+ * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
+ * current thread.
*
* </ul>
*
- * <p>If the lock is acquired by the current thread then the lock hold
+ * <p>If the lock is acquired by the current thread then the lock hold
* count is set to one.
*
* <p>If the current thread:
*
* <ul>
*
- * <li>has its interrupted status set on entry to this method; or
+ * <li>has its interrupted status set on entry to this method; or
*
- * <li>is {@link Thread#interrupt interrupted} while acquiring
+ * <li>is {@linkplain Thread#interrupt interrupted} while acquiring
* the lock,
*
* </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>In this implementation, as this method is an explicit interruption
- * point, preference is
- * given to responding to the interrupt over normal or reentrant
- * acquisition of the lock.
+ * <p>In this implementation, as this method is an explicit
+ * interruption point, preference is given to responding to the
+ * interrupt over normal or reentrant acquisition of the lock.
*
* @throws InterruptedException if the current thread is interrupted
*/
- public void lockInterruptibly() throws InterruptedException {
+ public void lockInterruptibly() throws InterruptedException {
sync.acquireInterruptibly(1);
}
@@ -308,43 +316,42 @@
* of invocation.
*
* <p>Acquires the lock if it is not held by another thread and
- * returns immediately with the value <tt>true</tt>, setting the
+ * returns immediately with the value {@code true}, setting the
* lock hold count to one. Even when this lock has been set to use a
- * fair ordering policy, a call to <tt>tryLock()</tt> <em>will</em>
+ * fair ordering policy, a call to {@code tryLock()} <em>will</em>
* immediately acquire the lock if it is available, whether or not
- * other threads are currently waiting for the lock.
- * This "barging" behavior can be useful in certain
+ * other threads are currently waiting for the lock.
+ * This "barging" behavior can be useful in certain
* circumstances, even though it breaks fairness. If you want to honor
- * the fairness setting for this lock, then use
+ * the fairness setting for this lock, then use
* {@link #tryLock(long, TimeUnit) tryLock(0, TimeUnit.SECONDS) }
* which is almost equivalent (it also detects interruption).
*
- * <p> If the current thread
- * already holds this lock then the hold count is incremented by one and
- * the method returns <tt>true</tt>.
+ * <p> If the current thread already holds this lock then the hold
+ * count is incremented by one and the method returns {@code true}.
*
- * <p>If the lock is held by another thread then this method will return
- * immediately with the value <tt>false</tt>.
+ * <p>If the lock is held by another thread then this method will return
+ * immediately with the value {@code false}.
*
- * @return <tt>true</tt> if the lock was free and was acquired by the
- * current thread, or the lock was already held by the current thread; and
- * <tt>false</tt> otherwise.
+ * @return {@code true} if the lock was free and was acquired by the
+ * current thread, or the lock was already held by the current
+ * thread; and {@code false} otherwise
*/
public boolean tryLock() {
return sync.nonfairTryAcquire(1);
}
/**
- * Acquires the lock if it is not held by another thread within the given
- * waiting time and the current thread has not been
- * {@link Thread#interrupt interrupted}.
+ * Acquires the lock if it is not held by another thread within the given
+ * waiting time and the current thread has not been
+ * {@linkplain Thread#interrupt interrupted}.
*
- * <p>Acquires the lock if it is not held by another thread and returns
- * immediately with the value <tt>true</tt>, setting the lock hold count
+ * <p>Acquires the lock if it is not held by another thread and returns
+ * immediately with the value {@code true}, setting the lock hold count
* to one. If this lock has been set to use a fair ordering policy then
* an available lock <em>will not</em> be acquired if any other threads
* are waiting for the lock. This is in contrast to the {@link #tryLock()}
- * method. If you want a timed <tt>tryLock</tt> that does permit barging on
+ * method. If you want a timed {@code tryLock} that does permit barging on
* a fair lock then combine the timed and un-timed forms together:
*
* <pre>if (lock.tryLock() || lock.tryLock(timeout, unit) ) { ... }
@@ -352,60 +359,56 @@
*
* <p>If the current thread
* already holds this lock then the hold count is incremented by one and
- * the method returns <tt>true</tt>.
+ * the method returns {@code true}.
*
* <p>If the lock is held by another thread then the
- * current thread becomes disabled for thread scheduling
+ * 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; or
+ * <li>Some other thread {@linkplain Thread#interrupt interrupts}
+ * the current thread; or
*
* <li>The specified waiting time elapses
*
* </ul>
*
- * <p>If the lock is acquired then the value <tt>true</tt> is returned and
+ * <p>If the lock is acquired then the value {@code true} is returned and
* the lock hold count is set to one.
*
* <p>If the current thread:
*
* <ul>
*
- * <li>has its interrupted status set on entry to this method; or
+ * <li>has its interrupted status set on entry to this method; or
*
- * <li>is {@link Thread#interrupt interrupted} while acquiring
- * the lock,
+ * <li>is {@linkplain Thread#interrupt interrupted} while
+ * acquiring the lock,
*
* </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>If the specified waiting time elapses then the value <tt>false</tt>
- * is returned.
- * If the time is
- * less than or equal to zero, the method will not wait at all.
- *
- * <p>In this implementation, as this method is an explicit interruption
- * point, preference is
- * given to responding to the interrupt over normal or reentrant
- * acquisition of the lock, and over reporting the elapse of the waiting
- * time.
+ * <p>If the specified waiting time elapses then the value {@code false}
+ * is returned. If the time is less than or equal to zero, the method
+ * will not wait at all.
+ *
+ * <p>In this implementation, as this method is an explicit
+ * interruption point, preference is given to responding to the
+ * interrupt over normal or reentrant acquisition of the lock, and
+ * over reporting the elapse of the waiting time.
*
* @param timeout the time to wait for the lock
* @param unit the time unit of the timeout argument
- *
- * @return <tt>true</tt> if the lock was free and was acquired by the
- * current thread, or the lock was already held by the current thread; and
- * <tt>false</tt> if the waiting time elapsed before the lock could be
- * acquired.
- *
+ * @return {@code true} if the lock was free and was acquired by the
+ * current thread, or the lock was already held by the current
+ * thread; and {@code false} if the waiting time elapsed before
+ * the lock could be acquired
* @throws InterruptedException if the current thread is interrupted
- * @throws NullPointerException if unit is null
+ * @throws NullPointerException if the time unit is null
*
*/
public boolean tryLock(long timeout, TimeUnit unit) throws InterruptedException {
@@ -413,22 +416,22 @@
}
/**
- * Attempts to release this lock.
+ * Attempts to release this lock.
+ *
+ * <p>If the current thread is the holder of this lock then the hold
+ * count is decremented. If the hold count is now zero then the lock
+ * is released. If the current thread is not the holder of this
+ * lock then {@link IllegalMonitorStateException} is thrown.
*
- * <p>If the current thread is the
- * holder of this lock then the hold count is decremented. If the
- * hold count is now zero then the lock is released. If the
- * current thread is not the holder of this lock then {@link
- * IllegalMonitorStateException} is thrown.
* @throws IllegalMonitorStateException if the current thread does not
- * hold this lock.
+ * hold this lock
*/
public void unlock() {
sync.release(1);
}
/**
- * Returns a {@link Condition} instance for use with this
+ * Returns a {@link Condition} instance for use with this
* {@link Lock} instance.
*
* <p>The returned {@link Condition} instance supports the same
@@ -440,28 +443,28 @@
* <ul>
*
* <li>If this lock is not held when any of the {@link Condition}
- * {@link Condition#await() waiting} or {@link Condition#signal
- * signalling} methods are called, then an {@link
+ * {@linkplain Condition#await() waiting} or {@linkplain
+ * Condition#signal signalling} methods are called, then an {@link
* IllegalMonitorStateException} is thrown.
*
- * <li>When the condition {@link Condition#await() waiting}
+ * <li>When the condition {@linkplain Condition#await() waiting}
* methods are called the lock is released and, before they
* return, the lock is reacquired and the lock hold count restored
* to what it was when the method was called.
*
- * <li>If a thread is {@link Thread#interrupt interrupted} while
- * waiting then the wait will terminate, an {@link
+ * <li>If a thread is {@linkplain Thread#interrupt interrupted}
+ * while waiting then the wait will terminate, an {@link
* InterruptedException} will be thrown, and the thread's
* interrupted status will be cleared.
*
- * <li> Waiting threads are signalled in FIFO order
+ * <li> Waiting threads are signalled in FIFO order.
*
* <li>The ordering of lock reacquisition for threads returning
* from waiting methods is the same as for threads initially
* acquiring the lock, which is in the default case not specified,
* but for <em>fair</em> locks favors those threads that have been
* waiting the longest.
- *
+ *
* </ul>
*
* @return the Condition object
@@ -473,7 +476,7 @@
/**
* Queries the number of holds on this lock by the current thread.
*
- * <p>A thread has a hold on a lock for each lock action that is not
+ * <p>A thread has a hold on a lock for each lock action that is not
* matched by an unlock action.
*
* <p>The hold count information is typically only used for testing and
@@ -484,8 +487,8 @@
* <pre>
* class X {
* ReentrantLock lock = new ReentrantLock();
- * // ...
- * public void m() {
+ * // ...
+ * public void m() {
* assert lock.getHoldCount() == 0;
* lock.lock();
* try {
@@ -498,7 +501,7 @@
* </pre>
*
* @return the number of holds on this lock by the current thread,
- * or zero if this lock is not held by the current thread.
+ * or zero if this lock is not held by the current thread
*/
public int getHoldCount() {
return sync.getHoldCount();
@@ -517,7 +520,7 @@
* ReentrantLock lock = new ReentrantLock();
* // ...
*
- * public void m() {
+ * public void m() {
* assert lock.isHeldByCurrentThread();
* // ... method body
* }
@@ -532,7 +535,7 @@
* ReentrantLock lock = new ReentrantLock();
* // ...
*
- * public void m() {
+ * public void m() {
* assert !lock.isHeldByCurrentThread();
* lock.lock();
* try {
@@ -543,8 +546,9 @@
* }
* }
* </pre>
- * @return <tt>true</tt> if current thread holds this lock and
- * <tt>false</tt> otherwise.
+ *
+ * @return {@code true} if current thread holds this lock and
+ * {@code false} otherwise
*/
public boolean isHeldByCurrentThread() {
return sync.isHeldExclusively();
@@ -552,47 +556,53 @@
/**
* Queries if this lock is held by any thread. This method is
- * designed for use in monitoring of the system state,
+ * designed for use in monitoring of the system state,
* not for synchronization control.
- * @return <tt>true</tt> if any thread holds this lock and
- * <tt>false</tt> otherwise.
+ *
+ * @return {@code true} if any thread holds this lock and
+ * {@code false} otherwise
*/
public boolean isLocked() {
return sync.isLocked();
}
/**
- * Returns true if this lock has fairness set true.
- * @return true if this lock has fairness set true.
+ * Returns {@code true} if this lock has fairness set true.
+ *
+ * @return {@code true} if this lock has fairness set true
*/
public final boolean isFair() {
return sync instanceof FairSync;
}
/**
- * Returns the thread that currently owns the exclusive lock, or
- * <tt>null</tt> if not owned. Note that the owner may be
- * momentarily <tt>null</tt> even if there are threads trying to
- * acquire the lock but have not yet done so. This method is
- * designed to facilitate construction of subclasses that provide
- * more extensive lock monitoring facilities.
- * @return the owner, or <tt>null</tt> if not owned.
+ * Returns the thread that currently owns this lock, or
+ * {@code null} if not owned. When this method is called by a
+ * thread that is not the owner, the return value reflects a
+ * best-effort approximation of current lock status. For example,
+ * the owner may be momentarily {@code null} even if there are
+ * threads trying to acquire the lock but have not yet done so.
+ * This method is designed to facilitate construction of
+ * subclasses that provide more extensive lock monitoring
+ * facilities.
+ *
+ * @return the owner, or {@code null} if not owned
*/
protected Thread getOwner() {
return sync.getOwner();
}
/**
- * Queries whether any threads are waiting to acquire. Note that
- * because cancellations may occur at any time, a <tt>true</tt>
+ * Queries whether any threads are waiting to acquire this lock. Note that
+ * because cancellations may occur at any time, a {@code true}
* return does not guarantee that any other thread will ever
- * acquire. This method is designed primarily for use in
+ * acquire this lock. This method is designed primarily for use in
* monitoring of the system state.
*
- * @return true if there may be other threads waiting to acquire
- * the lock.
+ * @return {@code true} if there may be other threads waiting to
+ * acquire the lock
*/
- public final boolean hasQueuedThreads() {
+ public final boolean hasQueuedThreads() {
return sync.hasQueuedThreads();
}
@@ -600,26 +610,27 @@
/**
* Queries whether the given thread is waiting to acquire this
* lock. Note that because cancellations may occur at any time, a
- * <tt>true</tt> return does not guarantee that this thread
- * will ever acquire. This method is designed primarily for use
+ * {@code true} return does not guarantee that this thread
+ * will ever acquire this lock. This method is designed primarily for use
* in monitoring of the system state.
*
* @param thread the thread
- * @return true if the given thread is queued waiting for this lock.
- * @throws NullPointerException if thread is null
+ * @return {@code true} if the given thread is queued waiting for this lock
+ * @throws NullPointerException if the thread is null
*/
- public final boolean hasQueuedThread(Thread thread) {
+ public final boolean hasQueuedThread(Thread thread) {
return sync.isQueued(thread);
}
/**
* Returns an estimate of the number of threads waiting to
- * acquire. The value is only an estimate because the number of
+ * acquire this lock. The value is only an estimate because the number of
* threads may change dynamically while this method traverses
* internal data structures. This method is designed for use in
* monitoring of the system state, not for synchronization
* control.
+ *
* @return the estimated number of threads waiting for this lock
*/
public final int getQueueLength() {
@@ -628,12 +639,13 @@
/**
* Returns a collection containing threads that may be waiting to
- * acquire. Because the actual set of threads may change
+ * acquire this lock. Because the actual set of threads may change
* dynamically while constructing this result, the returned
* collection is only a best-effort estimate. The elements of the
* returned collection are in no particular order. This method is
* designed to facilitate construction of subclasses that provide
* more extensive monitoring facilities.
+ *
* @return the collection of threads
*/
protected Collection<Thread> getQueuedThreads() {
@@ -643,18 +655,18 @@
/**
* Queries whether any threads are waiting on the given condition
* associated with this lock. Note that because timeouts and
- * interrupts may occur at any time, a <tt>true</tt> return does
- * not guarantee that a future <tt>signal</tt> will awaken any
+ * interrupts may occur at any time, a {@code true} return does
+ * not guarantee that a future {@code signal} will awaken any
* threads. This method is designed primarily for use in
* monitoring of the system state.
+ *
* @param condition the condition
- * @return <tt>true</tt> if there are any waiting threads.
- * @throws IllegalMonitorStateException if this lock
- * is not held
+ * @return {@code true} if there are any waiting threads
+ * @throws IllegalMonitorStateException if this lock is not held
* @throws IllegalArgumentException if the given condition is
- * not associated with this lock
- * @throws NullPointerException if condition null
- */
+ * not associated with this lock
+ * @throws NullPointerException if the condition is null
+ */
public boolean hasWaiters(Condition condition) {
if (condition == null)
throw new NullPointerException();
@@ -670,14 +682,14 @@
* serves only as an upper bound on the actual number of waiters.
* This method is designed for use in monitoring of the system
* state, not for synchronization control.
+ *
* @param condition the condition
- * @return the estimated number of waiting threads.
- * @throws IllegalMonitorStateException if this lock
- * is not held
+ * @return the estimated number of waiting threads
+ * @throws IllegalMonitorStateException if this lock is not held
* @throws IllegalArgumentException if the given condition is
- * not associated with this lock
- * @throws NullPointerException if condition null
- */
+ * not associated with this lock
+ * @throws NullPointerException if the condition is null
+ */
public int getWaitQueueLength(Condition condition) {
if (condition == null)
throw new NullPointerException();
@@ -695,13 +707,13 @@
* are in no particular order. This method is designed to
* facilitate construction of subclasses that provide more
* extensive condition monitoring facilities.
+ *
* @param condition the condition
* @return the collection of threads
- * @throws IllegalMonitorStateException if this lock
- * is not held
+ * @throws IllegalMonitorStateException if this lock is not held
* @throws IllegalArgumentException if the given condition is
- * not associated with this lock
- * @throws NullPointerException if condition null
+ * not associated with this lock
+ * @throws NullPointerException if the condition is null
*/
protected Collection<Thread> getWaitingThreads(Condition condition) {
if (condition == null)
@@ -712,16 +724,17 @@
}
/**
- * Returns a string identifying this lock, as well as its lock
- * state. The state, in brackets, includes either the String
- * "Unlocked" or the String "Locked by"
- * followed by the {@link Thread#getName} of the owning thread.
- * @return a string identifying this lock, as well as its lock state.
+ * Returns a string identifying this lock, as well as its lock state.
+ * The state, in brackets, includes either the String {@code "Unlocked"}
+ * or the String {@code "Locked by"} followed by the
+ * {@linkplain Thread#getName name} of the owning thread.
+ *
+ * @return a string identifying this lock, as well as its lock state
*/
public String toString() {
- Thread owner = sync.getOwner();
- return super.toString() + ((owner == null) ?
+ Thread o = sync.getOwner();
+ return super.toString() + ((o == null) ?
"[Unlocked]" :
- "[Locked by thread " + owner.getName() + "]");
+ "[Locked by thread " + o.getName() + "]");
}
}