File	Doc	Category	Size	Date	Package
ReentrantReadWriteLock.java	API Doc	Java SE 5 API	44039	Fri Aug 26 14:57:26 BST 2005	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) {
// upgrade lock manually
rwl.readLock().unlock(); // must unlock first to obtain writelock
rwl.writeLock().lock();
if (!cacheValid) { // recheck
data = ...
cacheValid = true;
}
// downgrade lock
rwl.readLock().lock(); // reacquire read without giving up write lock
rwl.writeLock().unlock(); // unlock write, still hold read
}

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

class RWDictionary {
private final Map<String, Data> m = new TreeMap<String, Data>();
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
static final int	SHARED_SHIFT
static final int	SHARED_UNIT
static final int	EXCLUSIVE_MASK

Constructors Summary
public ReentrantReadWriteLock() Creates a new ReentrantReadWriteLock with default ordering properties. sync = new NonfairSync(); readerLock = new ReadLock(this); writerLock = new WriteLock(this);
public ReentrantReadWriteLock(boolean fair) Creates a new ReentrantReadWriteLock with the given fairness policy. param fair 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
static int	exclusiveCount(int c) Returns the number of exclusive holds represented in count return c & EXCLUSIVE_MASK;
protected java.lang.Thread	getOwner() Returns the thread that currently owns the write lock, or null if not owned. Note that the owner may be momentarily 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 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	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 condition 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 condition 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 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 true if the given thread is queued waiting for this lock. throws NullPointerException if 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 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 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 true return does not guarantee that a future signal will awaken any threads. This method is designed primarily for use in monitoring of the system state. param condition the condition return 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 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 true if this lock has fairness set true. return 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 true if any thread holds the write lock and false otherwise. return sync.isWriteLocked();
public boolean	isWriteLockedByCurrentThread() Queries if the write lock is held by the current thread. return true if the current thread holds the write lock and false otherwise. return sync.isHeldExclusively();
public java.util.concurrent.locks.ReentrantReadWriteLock$ReadLock	readLock() return readerLock;
static int	sharedCount(int c) Returns the number of shared holds represented in count return c >>> SHARED_SHIFT;
public java.lang.String	toString() Returns a string identifying this lock, as well as its lock state. The state, in brackets, includes the String "Write locks =" followed by the number of reentrantly held write locks, and the String "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 = exclusiveCount(c); int r = sharedCount(c); return super.toString() + "[Write locks = " + w + ", Read locks = " + r + "]";
public java.util.concurrent.locks.ReentrantReadWriteLock$WriteLock	writeLock() return writerLock;