An implementation of {@link ReadWriteLock} supporting similar
semantics to {@link ReentrantLock}.
This class has the following properties:
- Acquisition order
This class does not impose a reader or writer preference
ordering for lock access. However, it does support an optional
fairness policy. When constructed as fair, threads
contend for entry using an approximately arrival-order policy. When
the write lock is released either the longest-waiting single writer
will be assigned the write lock, or if there is a reader waiting
longer than any writer, the set of readers will be assigned the
read lock. When constructed as non-fair, the order of entry to the
lock need not be in arrival order. In either case, if readers are
active and a writer enters the lock then no subsequent readers will
be granted the read lock until after that writer has acquired and
released the write lock.
- Reentrancy
This lock allows both readers and writers to reacquire read or
write locks in the style of a {@link ReentrantLock}. Readers are not
allowed until all write locks held by the writing thread have been
released.
Additionally, a writer can acquire the read lock - but not vice-versa.
Among other applications, reentrancy can be useful when
write locks are held during calls or callbacks to methods that
perform reads under read locks.
If a reader tries to acquire the write lock it will never succeed.
- Lock downgrading
Reentrancy also allows downgrading from the write lock to a read lock,
by acquiring the write lock, then the read lock and then releasing the
write lock. However, upgrading from a read lock to the write lock, is
not possible.
- Interruption of lock acquisition
The read lock and write lock both support interruption during lock
acquisition.
- {@link Condition} support
The write lock provides a {@link Condition} implementation that
behaves in the same way, with respect to the write lock, as the
{@link Condition} implementation provided by
{@link ReentrantLock#newCondition} does for {@link ReentrantLock}.
This {@link Condition} can, of course, only be used with the write lock.
The read lock does not support a {@link Condition} and
readLock().newCondition() throws
UnsupportedOperationException.
- Instrumentation
This class supports methods to determine whether locks
are held or contended. These methods are designed for monitoring
system state, not for synchronization control.
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.
Sample usages. Here is a code sketch showing how to exploit
reentrancy to perform lock downgrading after updating a cache (exception
handling is elided for simplicity):
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();
}
}
ReentrantReadWriteLocks can be used to improve concurrency in some
uses of some kinds of Collections. This is typically worthwhile
only when the collections are expected to be large, accessed by
more reader threads than writer threads, and entail operations with
overhead that outweighs synchronization overhead. For example, here
is a class using a TreeMap that is expected to be large and
concurrently accessed.
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(); }
}
}
Implementation Notes
A reentrant write lock intrinsically defines an owner and can
only be released by the thread that acquired it. In contrast, in
this implementation, the read lock has no concept of ownership, and
there is no requirement that the thread releasing a read lock is
the same as the one that acquired it. However, this property is
not guaranteed to hold in future implementations of this class.
This lock supports a maximum of 65536 recursive write locks
and 65536 read locks. Attempts to exceed these limits result in
{@link Error} throws from locking methods. |
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 exclusive 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 sync.getOwner();
|
public final int | getQueueLength()Returns an estimate of the number of threads waiting to
acquire. 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 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 sync.getSharedQueuedThreads();
|
protected java.util.Collection | getQueuedThreads()Returns a collection containing threads that may be waiting to
acquire. 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 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 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 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.
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.
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 sync.getWriteHoldCount();
|
public final boolean | hasQueuedThread(java.lang.Thread thread)Queries whether the given thread is waiting to acquire this
lock. Note that because cancellations may occur at any time, a
true return does not guarantee that this thread
will ever acquire. This method is designed primarily for use
in monitoring of the system state.
return sync.isQueued(thread);
|
public final boolean | hasQueuedThreads()Queries whether any threads are waiting to acquire. Note that
because cancellations may occur at any time, a true
return does not guarantee that any other thread will ever
acquire. This method is designed primarily for use in
monitoring of the system state.
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.
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 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 sync.isWriteLocked();
|
public boolean | isWriteLockedByCurrentThread()Queries if the write lock is held by the current thread.
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 ="
follwed by the number of reentrantly held write locks, and the
String "Read locks =" followed by the number of held
read locks.
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;
|