File	Doc	Category	Size	Date	Package
ReentrantReadWriteLock.java	API Doc	Java SE 6 API	53141	Tue Jun 10 00:25:58 BST 2008	java.util.concurrent.locks

ReentrantReadWriteLock

• java.lang.Object

class CachedData {
Object data;
volatile boolean cacheValid;
ReentrantReadWriteLock rwl = new ReentrantReadWriteLock();

void processCachedData() {
rwl.readLock().lock();
if (!cacheValid) {
// Must release read lock before acquiring write lock
rwl.readLock().unlock();
rwl.writeLock().lock();
// Recheck state because another thread might have acquired
// write lock and changed state before we did.
if (!cacheValid) {
data = ...
cacheValid = true;
}
// Downgrade by acquiring read lock before releasing write lock
rwl.readLock().lock();
rwl.writeLock().unlock(); // Unlock write, still hold read
}

use(data);
rwl.readLock().unlock();
}
}

{@code
class RWDictionary {
private final Map m = new TreeMap();
private final ReentrantReadWriteLock rwl = new ReentrantReadWriteLock();
private final Lock r = rwl.readLock();
private final Lock w = rwl.writeLock();

public Data get(String key) {
r.lock();
try { return m.get(key); }
finally { r.unlock(); }
}
public String[] allKeys() {
r.lock();
try { return m.keySet().toArray(); }
finally { r.unlock(); }
}
public Data put(String key, Data value) {
w.lock();
try { return m.put(key, value); }
finally { w.unlock(); }
}
public void clear() {
w.lock();
try { m.clear(); }
finally { w.unlock(); }
}
}}

Fields Summary
private static final long	serialVersionUID
private final ReadLock	readerLock Inner class providing readlock
private final WriteLock	writerLock Inner class providing writelock
private final Sync	sync Performs all synchronization mechanics

Constructors Summary
public ReentrantReadWriteLock() Creates a new {@code ReentrantReadWriteLock} with default (nonfair) ordering properties. this(false);
public ReentrantReadWriteLock(boolean fair) Creates a new {@code ReentrantReadWriteLock} with the given fairness policy. param fair {@code true} if this lock should use a fair ordering policy sync = (fair)? new FairSync() : new NonfairSync(); readerLock = new ReadLock(this); writerLock = new WriteLock(this);

Methods Summary
protected java.lang.Thread	getOwner() Returns the thread that currently owns the write 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 return sync.getOwner();
public final int	getQueueLength() Returns an estimate of the number of threads waiting to acquire either the read or write 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 return sync.getQueueLength();
protected java.util.Collection	getQueuedReaderThreads() Returns a collection containing threads that may be waiting to acquire the read 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 lock monitoring facilities. return the collection of threads return sync.getSharedQueuedThreads();
protected java.util.Collection	getQueuedThreads() Returns a collection containing threads that may be waiting to acquire either the read or write 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 return sync.getQueuedThreads();
protected java.util.Collection	getQueuedWriterThreads() Returns a collection containing threads that may be waiting to acquire the write 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 lock monitoring facilities. return the collection of threads return sync.getExclusiveQueuedThreads();
public int	getReadHoldCount() Queries the number of reentrant read holds on this lock by the current thread. A reader thread has a hold on a lock for each lock action that is not matched by an unlock action. return the number of holds on the read lock by the current thread, or zero if the read lock is not held by the current thread since 1.6 return sync.getReadHoldCount();
public int	getReadLockCount() Queries the number of read locks held for this lock. This method is designed for use in monitoring system state, not for synchronization control. return the number of read locks held. return sync.getReadLockCount();
public int	getWaitQueueLength(java.util.concurrent.locks.Condition condition) Returns an estimate of the number of threads waiting on the given condition associated with the write lock. Note that because timeouts and interrupts may occur at any time, the estimate 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 throws IllegalArgumentException if the given condition is not associated with this lock throws NullPointerException if the condition is null if (condition == null) throw new NullPointerException(); if (!(condition instanceof AbstractQueuedSynchronizer.ConditionObject)) throw new IllegalArgumentException("not owner"); return sync.getWaitQueueLength((AbstractQueuedSynchronizer.ConditionObject)condition);
protected java.util.Collection	getWaitingThreads(java.util.concurrent.locks.Condition condition) Returns a collection containing those threads that may be waiting on the given condition associated with the write 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 condition monitoring facilities. param condition the condition return the collection of threads throws IllegalMonitorStateException if this lock is not held throws IllegalArgumentException if the given condition is not associated with this lock throws NullPointerException if the condition is null if (condition == null) throw new NullPointerException(); if (!(condition instanceof AbstractQueuedSynchronizer.ConditionObject)) throw new IllegalArgumentException("not owner"); return sync.getWaitingThreads((AbstractQueuedSynchronizer.ConditionObject)condition);
public int	getWriteHoldCount() Queries the number of reentrant write holds on this lock by the current thread. A writer thread has a hold on a lock for each lock action that is not matched by an unlock action. return the number of holds on the write lock by the current thread, or zero if the write lock is not held by the current thread return sync.getWriteHoldCount();
public final boolean	hasQueuedThread(java.lang.Thread thread) Queries whether the given thread is waiting to acquire either the read or write lock. Note that because cancellations may occur at any time, a {@code true} return does not guarantee that this thread will ever acquire a lock. This method is designed primarily for use in monitoring of the system state. param thread the thread return {@code true} if the given thread is queued waiting for this lock throws NullPointerException if the thread is null return sync.isQueued(thread);
public final boolean	hasQueuedThreads() Queries whether any threads are waiting to acquire the read or write lock. Note that because cancellations may occur at any time, a {@code true} return does not guarantee that any other thread will ever acquire a lock. This method is designed primarily for use in monitoring of the system state. return {@code true} if there may be other threads waiting to acquire the lock return sync.hasQueuedThreads();
public boolean	hasWaiters(java.util.concurrent.locks.Condition condition) Queries whether any threads are waiting on the given condition associated with the write lock. Note that because timeouts and 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 {@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 the condition is null if (condition == null) throw new NullPointerException(); if (!(condition instanceof AbstractQueuedSynchronizer.ConditionObject)) throw new IllegalArgumentException("not owner"); return sync.hasWaiters((AbstractQueuedSynchronizer.ConditionObject)condition);
public final boolean	isFair() Returns {@code true} if this lock has fairness set true. return {@code true} if this lock has fairness set true return sync instanceof FairSync;
public boolean	isWriteLocked() Queries if the write lock is held by any thread. This method is designed for use in monitoring system state, not for synchronization control. return {@code true} if any thread holds the write lock and {@code false} otherwise return sync.isWriteLocked();
public boolean	isWriteLockedByCurrentThread() Queries if the write lock is held by the current thread. return {@code true} if the current thread holds the write lock and {@code false} otherwise return sync.isHeldExclusively();
public java.util.concurrent.locks.ReentrantReadWriteLock$ReadLock	readLock() return readerLock;
public java.lang.String	toString() Returns a string identifying this lock, as well as its lock state. The state, in brackets, includes the String {@code "Write locks ="} followed by the number of reentrantly held write locks, and the String {@code "Read locks ="} followed by the number of held read locks. return a string identifying this lock, as well as its lock state int c = sync.getCount(); int w = Sync.exclusiveCount(c); int r = Sync.sharedCount(c); return super.toString() + "[Write locks = " + w + ", Read locks = " + r + "]";
public java.util.concurrent.locks.ReentrantReadWriteLock$WriteLock	writeLock() return writerLock;