Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

ReentrantReadWriteLock Class Reference

An implementation of ReadWriteLock supporting similar semantics to ReentrantLock. More...

Inheritance diagram for ReentrantReadWriteLock:

ReadWriteLock List of all members.

Public Member Functions

 this (bool fair=false)
Lock writeLock ()
Lock readLock ()
bool isFair ()
int getReadLockCount ()
bool isWriteLocked ()
bool isWriteLockedByCurrentThread ()
int getWriteHoldCount ()
bool hasQueuedThreads ()
bool hasQueuedThread (Thread thread)
int getQueueLength ()
bool hasWaiters (Condition condition)
int getWaitQueueLength (Condition condition)
char[] toString ()

Static Public Member Functions

static int sharedCount (int c)
static int exclusiveCount (int c)

Public Attributes

const int SHARED_SHIFT = 16
const int SHARED_UNIT = (1 << SHARED_SHIFT)
const int EXCLUSIVE_MASK = (1 << SHARED_SHIFT) - 1

Protected Member Functions

Thread getOwner ()
Thread[] getQueuedWriterThreads ()
Thread[] getQueuedReaderThreads ()
Thread[] getQueuedThreads ()
Thread[] getWaitingThreads (Condition condition)

Private Attributes

final ReentrantReadWriteLock
ReadLock 
readerLock
final ReentrantReadWriteLock
WriteLock 
writerLock
final Sync sync

Classes

class  FairSync
class  NonfairSync
class  ReadLock
class  Sync
class  WriteLock

Detailed Description

An implementation of ReadWriteLock supporting similar semantics to ReentrantLock.

This class has the following properties:

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;
   bool cacheValid;
   ReentrantReadWriteLock rwl;
   this() { 
     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.

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 Error throws from locking methods.

Definition at line 194 of file ReadWriteLock.d.


Member Function Documentation

this bool  fair = false  )  [inline]
 

Creates a new ReentrantReadWriteLock with the given fairness policy.

Parameters:
fair true if this lock should use a fair ordering policy

Definition at line 208 of file ReadWriteLock.d.

References readerLock, sync, and writerLock.

Lock writeLock  )  [inline]
 

Returns the lock used for writing.

Returns:
the lock used for writing.

Reimplemented from ReadWriteLock.

Definition at line 217 of file ReadWriteLock.d.

References writerLock.

Lock readLock  )  [inline]
 

Returns the lock used for reading.

Returns:
the lock used for reading.

Reimplemented from ReadWriteLock.

Definition at line 218 of file ReadWriteLock.d.

References readerLock.

static int sharedCount int  c  )  [inline, static]
 

Returns the number of shared holds represented in count

Definition at line 232 of file ReadWriteLock.d.

References SHARED_SHIFT.

Referenced by ReentrantReadWriteLock::Sync::getReadLockCount(), and toString().

static int exclusiveCount int  c  )  [inline, static]
 

Returns the number of exclusive holds represented in count

Definition at line 234 of file ReadWriteLock.d.

References EXCLUSIVE_MASK.

Referenced by ReentrantReadWriteLock::Sync::getOwner(), ReentrantReadWriteLock::Sync::getWriteHoldCount(), ReentrantReadWriteLock::Sync::isHeldExclusively(), ReentrantReadWriteLock::Sync::isWriteLocked(), ReentrantReadWriteLock::Sync::nonfairTryAcquire(), ReentrantReadWriteLock::Sync::nonfairTryAcquireShared(), toString(), ReentrantReadWriteLock::FairSync::tryAcquire(), ReentrantReadWriteLock::FairSync::tryAcquireShared(), and ReentrantReadWriteLock::Sync::tryRelease().

bool isFair  )  [inline]
 

Returns true if this lock has fairness set true.

Returns:
true if this lock has fairness set true.

Definition at line 709 of file ReadWriteLock.d.

References sync.

Thread getOwner  )  [inline, protected]
 

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.

Returns:
the owner, or null if not owned.

Definition at line 722 of file ReadWriteLock.d.

References ReentrantReadWriteLock::Sync::getOwner(), and sync.

int getReadLockCount  )  [inline]
 

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.

Definition at line 732 of file ReadWriteLock.d.

References ReentrantReadWriteLock::Sync::getReadLockCount(), and sync.

bool isWriteLocked  )  [inline]
 

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 write lock and false otherwise.

Definition at line 743 of file ReadWriteLock.d.

References ReentrantReadWriteLock::Sync::isWriteLocked(), and sync.

bool isWriteLockedByCurrentThread  )  [inline]
 

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

Returns:
true if current thread holds this lock and false otherwise.

Definition at line 752 of file ReadWriteLock.d.

References ReentrantReadWriteLock::Sync::isHeldExclusively(), and sync.

int getWriteHoldCount  )  [inline]
 

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 this lock by the current thread, or zero if this lock is not held by the current thread.

Definition at line 764 of file ReadWriteLock.d.

References ReentrantReadWriteLock::Sync::getWriteHoldCount(), and sync.

Thread [] getQueuedWriterThreads  )  [inline, protected]
 

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

Definition at line 778 of file ReadWriteLock.d.

References sync.

Thread [] getQueuedReaderThreads  )  [inline, protected]
 

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

Definition at line 792 of file ReadWriteLock.d.

References sync.

bool hasQueuedThreads  )  [inline]
 

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.

Returns:
true if there may be other threads waiting to acquire the lock.

Definition at line 806 of file ReadWriteLock.d.

References AbstractLock::hasQueuedThreads(), and sync.

bool hasQueuedThread Thread  thread  )  [inline]
 

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.

Parameters:
thread the thread
Returns:
true if the given thread is queued waiting for this lock.

Definition at line 820 of file ReadWriteLock.d.

References sync, and thread.

int getQueueLength  )  [inline]
 

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.

Returns:
the estimated number of threads waiting for this lock

Definition at line 833 of file ReadWriteLock.d.

References sync.

Thread [] getQueuedThreads  )  [inline, protected]
 

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.

Returns:
the collection of threads

Definition at line 847 of file ReadWriteLock.d.

References sync.

bool hasWaiters Condition  condition  )  [inline]
 

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.

Parameters:
condition the condition
Returns:
true if there are any waiting threads.

Definition at line 861 of file ReadWriteLock.d.

References sync.

int getWaitQueueLength Condition  condition  )  [inline]
 

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.

Parameters:
condition the condition
Returns:
the estimated number of waiting threads.

Definition at line 878 of file ReadWriteLock.d.

References sync.

Thread [] getWaitingThreads Condition  condition  )  [inline, protected]
 

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.

Parameters:
condition the condition
Returns:
the collection of threads

Definition at line 897 of file ReadWriteLock.d.

References sync.

char [] toString  )  [inline]
 

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.

Returns:
a string identifying this lock, as well as its lock state.

Definition at line 912 of file ReadWriteLock.d.

References exclusiveCount(), ReentrantReadWriteLock::Sync::getCount(), sharedCount(), and sync.


Member Data Documentation

final ReentrantReadWriteLock ReadLock readerLock [private]
 

Definition at line 196 of file ReadWriteLock.d.

Referenced by readLock(), and this().

final ReentrantReadWriteLock WriteLock writerLock [private]
 

Definition at line 198 of file ReadWriteLock.d.

Referenced by this(), and writeLock().

final Sync sync [private]
 

Definition at line 200 of file ReadWriteLock.d.

Referenced by getOwner(), getQueuedReaderThreads(), getQueuedThreads(), getQueuedWriterThreads(), getQueueLength(), getReadLockCount(), getWaitingThreads(), getWaitQueueLength(), getWriteHoldCount(), hasQueuedThread(), hasQueuedThreads(), hasWaiters(), isFair(), isWriteLocked(), isWriteLockedByCurrentThread(), this(), and toString().

const int SHARED_SHIFT = 16
 

Definition at line 227 of file ReadWriteLock.d.

Referenced by sharedCount().

const int SHARED_UNIT = (1 << SHARED_SHIFT)
 

Definition at line 228 of file ReadWriteLock.d.

const int EXCLUSIVE_MASK = (1 << SHARED_SHIFT) - 1
 

Definition at line 229 of file ReadWriteLock.d.

Referenced by exclusiveCount().


The documentation for this class was generated from the following file:
Generated on Sat Dec 24 17:28:41 2005 for Mango by  doxygen 1.4.0