Improved build.xml

[vimdoclet.git] / sample / java.util.concurrent.locks.ReentrantReadWriteLock.txt

*java.util.concurrent.locks.ReentrantReadWriteLock* *ReentrantReadWriteLock* An 

public class ReentrantReadWriteLock
  extends    |java.lang.Object|
  implements |java.util.concurrent.locks.ReadWriteLock|
             |java.io.Serializable|

|java.util.concurrent.locks.ReentrantReadWriteLock_Description|
|java.util.concurrent.locks.ReentrantReadWriteLock_Fields|
|java.util.concurrent.locks.ReentrantReadWriteLock_Constructors|
|java.util.concurrent.locks.ReentrantReadWriteLock_Methods|

================================================================================

*java.util.concurrent.locks.ReentrantReadWriteLock_Constructors*
|java.util.concurrent.locks.ReentrantReadWriteLock()|Creates a new ReentrantRea
|java.util.concurrent.locks.ReentrantReadWriteLock(boolean)|Creates a new Reent

*java.util.concurrent.locks.ReentrantReadWriteLock_Methods*
|java.util.concurrent.locks.ReentrantReadWriteLock.getOwner()|Returns the threa
|java.util.concurrent.locks.ReentrantReadWriteLock.getQueuedReaderThreads()|Ret
|java.util.concurrent.locks.ReentrantReadWriteLock.getQueuedThreads()|Returns a
|java.util.concurrent.locks.ReentrantReadWriteLock.getQueuedWriterThreads()|Ret
|java.util.concurrent.locks.ReentrantReadWriteLock.getQueueLength()|Returns an 
|java.util.concurrent.locks.ReentrantReadWriteLock.getReadLockCount()|Queries t
|java.util.concurrent.locks.ReentrantReadWriteLock.getWaitingThreads(Condition)|
|java.util.concurrent.locks.ReentrantReadWriteLock.getWaitQueueLength(Condition)|
|java.util.concurrent.locks.ReentrantReadWriteLock.getWriteHoldCount()|Queries 
|java.util.concurrent.locks.ReentrantReadWriteLock.hasQueuedThread(Thread)|Quer
|java.util.concurrent.locks.ReentrantReadWriteLock.hasQueuedThreads()|Queries w
|java.util.concurrent.locks.ReentrantReadWriteLock.hasWaiters(Condition)|Querie
|java.util.concurrent.locks.ReentrantReadWriteLock.isFair()|Returns true if thi
|java.util.concurrent.locks.ReentrantReadWriteLock.isWriteLocked()|Queries if t
|java.util.concurrent.locks.ReentrantReadWriteLock.isWriteLockedByCurrentThread()|
|java.util.concurrent.locks.ReentrantReadWriteLock.readLock()|
|java.util.concurrent.locks.ReentrantReadWriteLock.toString()|Returns a string 
|java.util.concurrent.locks.ReentrantReadWriteLock.writeLock()|

*java.util.concurrent.locks.ReentrantReadWriteLock_Description*

An implementation of (|java.util.concurrent.locks.ReadWriteLock|) supporting 
similar semantics to (|java.util.concurrent.locks.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 (|java.util.concurrent.locks.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. 

(|java.util.concurrent.locks.Condition|) support The write lock provides a 
(|java.util.concurrent.locks.Condition|) implementation that behaves in the 
same way, with respect to the write lock, as the 
(|java.util.concurrent.locks.Condition|) implementation provided by 
(|java.util.concurrent.locks.ReentrantLock|) does for 
(|java.util.concurrent.locks.ReentrantLock|) . This 
(|java.util.concurrent.locks.Condition|) can, of course, only be used with the 
write lock. The read lock does not support a 
(|java.util.concurrent.locks.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 (|java.lang.Error|) throws 
from locking methods. 


*java.util.concurrent.locks.ReentrantReadWriteLock()*

public ReentrantReadWriteLock()

Creates a new ReentrantReadWriteLock with default ordering properties. 


*java.util.concurrent.locks.ReentrantReadWriteLock(boolean)*

public ReentrantReadWriteLock(boolean fair)

Creates a new ReentrantReadWriteLock with the given fairness policy. 

    fair - true if this lock should use a fair ordering policy 

*java.util.concurrent.locks.ReentrantReadWriteLock.getOwner()*

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. 


    Returns: the owner, or null if not owned. 
*java.util.concurrent.locks.ReentrantReadWriteLock.getQueuedReaderThreads()*

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. 


    Returns: the collection of threads 
*java.util.concurrent.locks.ReentrantReadWriteLock.getQueuedThreads()*

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. 


    Returns: the collection of threads 
*java.util.concurrent.locks.ReentrantReadWriteLock.getQueuedWriterThreads()*

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. 


    Returns: the collection of threads 
*java.util.concurrent.locks.ReentrantReadWriteLock.getQueueLength()*

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. 


    Returns: the estimated number of threads waiting for this lock 
*java.util.concurrent.locks.ReentrantReadWriteLock.getReadLockCount()*

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. 


    Returns: the number of read locks held. 
*java.util.concurrent.locks.ReentrantReadWriteLock.getWaitingThreads(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. 

    condition - the condition 

    Returns: the collection of threads 
*java.util.concurrent.locks.ReentrantReadWriteLock.getWaitQueueLength(Condition)*

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. 

    condition - the condition 

    Returns: the estimated number of waiting threads. 
*java.util.concurrent.locks.ReentrantReadWriteLock.getWriteHoldCount()*

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. 


    Returns: 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. 
*java.util.concurrent.locks.ReentrantReadWriteLock.hasQueuedThread(Thread)*

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. 

    thread - the thread 

    Returns: true if the given thread is queued waiting for this lock. 
*java.util.concurrent.locks.ReentrantReadWriteLock.hasQueuedThreads()*

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. 


    Returns: true if there may be other threads waiting to acquire the lock. 
*java.util.concurrent.locks.ReentrantReadWriteLock.hasWaiters(Condition)*

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. 

    condition - the condition 

    Returns: true if there are any waiting threads. 
*java.util.concurrent.locks.ReentrantReadWriteLock.isFair()*

public final boolean isFair()

Returns true if this lock has fairness set true. 


    Returns: true if this lock has fairness set true. 
*java.util.concurrent.locks.ReentrantReadWriteLock.isWriteLocked()*

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. 


    Returns: true if any thread holds the write lock and false otherwise. 
*java.util.concurrent.locks.ReentrantReadWriteLock.isWriteLockedByCurrentThread()*

public boolean isWriteLockedByCurrentThread()

Queries if the write lock is held by the current thread. 


    Returns: true if the current thread holds the write lock and false otherwise. 
*java.util.concurrent.locks.ReentrantReadWriteLock.readLock()*

public |java.util.concurrent.locks.ReentrantReadWriteLock.ReadLock| readLock()




*java.util.concurrent.locks.ReentrantReadWriteLock.toString()*

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. 


    Returns: a string identifying this lock, as well as its lock state. 
*java.util.concurrent.locks.ReentrantReadWriteLock.writeLock()*

public |java.util.concurrent.locks.ReentrantReadWriteLock.WriteLock| writeLock()