RWReadersWriterLock


RWReadersWriterLock  RWSynchObject

Data Type and Member Function Indexes
Package
Header File
Description
Example
Public Constructor
Public Destructor
Member Typedefs
Public Member Functions
See Also

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Header File

#include <rw/sync/RWReadersWriterLock.h>

Description

RWReadersWriterLock is a multiple-readers, single-writer synchronization lock. With this type of lock, multiple readers are allowed concurrent access to the protected critical section. However, exclusive access is granted to writers; a reader and a writer cannot both enter the critical section, and only one writer at a time will be granted access. A writer that attempts to acquire the lock will block waiting for readers to exit the critical section. Note that because this lock favors writers over readers, the writer will get priority over any readers that try to access the lock after the time the writer attempts to acquire it. A reader attempting to access the lock will only acquire it after all writers attempting access have acquired and released the lock.

Example

#include <iostream.h>
#include <rw/sync/RWReadersWriterLock.h>

// Class Ratio maintains the ratio x : y.  Once x and y
// are set in the constructor, any change to either x
// or y will cause the other to change such that the
// ratio is maintained.
//
// It is important that modifications of x and y occur
// as an atomic operation since during the brief period
// between modifying one and then the other, the object is
// in an inconsistent state.

class Ratio {
private:
  typedef RWReadersWriterLock::ReadLockGuard  ReadGuard;
  typedef RWReadersWriterLock::WriteLockGuard WriteGuard;
  double               x_;
  double               y_;
  RWReadersWriterLock  rdwrLock_;

public:
  
  Ratio(double x, double y) : x_(x), y_(y) { }

  // The read locks in ratio() and getXandY()
  // ensure that x_ and y_ can be accessed without
  // worrying that the object is in a state where
  // one has been modified without the other.
  // However, because they are read locks, there is
  // no limit to the number of threads that can
  // be running in either of these two member functions
  // simultaneously.  Thus there is no unnecessary
  // blocking when multiple threads wish only to read
  // the data without modifying it.

  double ratio()
  {
    ReadGuard readlock(rdwrLock_);
    return (double)x_ / (double)y_;
  }

  void getXandY(double& x, double& y)
  {
    ReadGuard readlock(rdwrLock_);
    x = x_;
    y = y_;
  }

  // The write locks in setX() and setY() ensure that
  // x_ and y_ are updated atomically so that the integrity
  // of the ratio is always maintained.  These methods
  // obtain exclusive access to rdwrLock; all other
  // threads will block upon trying to enter any of the
  // four methods shown for this class.

  void setX(int i)
  {
    WriteGuard writelock(rdwrLock_);
    double r = x_ / y_;
    x_ = i;
    y_ = x_ / r;    
  }
    
  void setY(int i)
  {
    WriteGuard writelock(rdwrLock_);
    double r = x_ / y_;
    y_ = i;
    x_ = y_ * r;    
  }
};

Public Constructor

RWReadersWriterLock(RWCancellationState
                     state=RW_CANCELLATION_DISABLED)
throws(RWTHRInternalError);

Creates and initializes an RWReadersWriterLock. The thread cancellation state of the object is initialized to state.

Public Destructor

~RWReadersWriterLock(void)
throws(RWTHRInternalError);

Recovers any system resources used to implement the RWReadersWriterLock.

Member Typedefs

typedef RWTLockGuard<RWReadersWriterLock>        
         LockGuard;
typedef RWTReadLockGuard<RWReadersWriterLock>    
         ReadLockGuard;
typedef RWTWriteLockGuard<RWReadersWriterLock>   
         WriteLockGuard;

typedef RWTTryLockGuard<RWReadersWriterLock>     
         TryLockGuard;
typedef RWTTryReadLockGuard<RWReadersWriterLock>
         TryReadLockGuard;
typedef RWTTryWriteLockGuard<RWReadersWriterLock>
         TryWriteLockGuard;

typedef RWTUnlockGuard<RWReadersWriterLock>      
         UnlockGuard;
typedef RWTReadUnlockGuard<RWReadersWriterLock> 
         ReadUnlockGuard;
typedef RWTWriteUnlockGuard<RWReadersWriterLock> 
         WriteUnlockGuard;

Predefined types for compatible guards.

Public Member Functions

void
acquire(void);

Calls acquireWrite(). Provided for compatibility with simple mutex locks. Possible exceptions include RWCancellation and RWTHRInternalError.

RWWaitStatus
acquire(unsigned long milliseconds);

Returns the result of calling acquireWrite(milliseconds). Provided for compatibility with simple mutex locks. Possible exceptions include RWCancellation and RWTHRInternalError.

void
acquireRead(void);

Acquires the lock as a reader. If there are writers waiting for the lock, the calling thread will block until all readers currently in the protected code exit and until all waiting writers have acquired and left the protected code. At that time, the thread will be given access to the protected code concurrently with other readers waiting on the lock.

This function will throw an RWCancellation object if the lock has cancellation detection enabled and a runnable containing the calling thread has been canceled. Other possible exceptions include RWTHRInternalError.

RWWaitStatus
acquireRead(unsigned long milliseconds);

Attempts to acquire the lock as a reader. If there are writers waiting for the lock, the calling thread will block until all readers currently in the protected code exit and until all waiting writers have acquired and left the protected code. At that time, the thread will be given access to the protected code concurrently with other readers waiting on the lock.

If the lock cannot be acquired within the time specified, the function returns RW_THR_TIMEOUT.

void
acquireWrite(void);

Acquires the lock as a writer. The calling thread will be given priority access to the lock over all readers which have not yet acquired the lock. If readers already have acquired the lock, but have not released it, or another writer owns the lock, the call will block until the lock is available. This function will throw an RWCancellation object if the lock has cancellation detection enabled and a runnable containing the calling thread has been canceled. Other possible exceptions include RWTHRInternalError.

RWWaitStatus
acquireWrite(unsigned long milliseconds);

Attempts to acquire the lock as a writer. The calling thread will be given priority access to the lock over all readers which have not yet acquired the lock. If readers already have acquired the lock, but have not released it, or another writer owns the lock, the call will block until the lock is available. If the lock cannot be acquired within the time specified, the function returns RW_THR_TIMEOUT.

void
release(void);

Releases the lock to one writer waiting to access the protected code. If there are no writers blocked waiting for the lock, all readers blocked on the lock are given concurrent access to the protected code. Possible exceptions include RWTHRInternalError.

RWBoolean
tryAcquire(void);

Calls tryAcquireWrite(). Interface used by simple mutex locks. Possible exceptions include RWCancellation and RWTHRInternalError.

RWBoolean
tryAcquireRead(void);

Attempts to acquire the lock as a reader. If there are no writers either waiting for the lock, or that own the lock, the calling thread acquires the lock and this function returns TRUE. Otherwise, this function returns FALSE without acquiring the lock. Possible exceptions include RWCancellation and RWTHRInternalError.

RWBoolean
tryAcquireWrite(void);

Attempts to acquire the lock as a writer. If no thread currently owns the lock the calling thread is given ownership of the lock and this function returns TRUE. Otherwise, this function returns FALSE without acquiring the lock. Possible exceptions include RWCancellation and RWTHRInternalError.