RWReadersWriterLock

Module:  Threads   Package:  Synchronization

RWReadersWriterLock   RWSynchObject

• Local Index
• Header File
• Description
• Example
• Public Constructor
• Public Destructor
• Member Typedefs
• Public Member Functions
• Private Constructor
• Private Member Operator
• See Also

Members

acquire() acquireRead() acquireWrite() LockGuard operator

ReadLockGuard ReadUnlockGuard release() RWReadersWriterLock() tryAcquire()

tryAcquireRead() tryAcquireWrite() TryLockGuard TryReadLockGuard TryWriteLockGuard

UnlockGuard WriteLockGuard WriteUnlockGuard ~RWReadersWriterLock()

#include <rw/sync/RWReadersWriterLock.h> 

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.

#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;    
  }
};

RWReadersWriterLock(RWCancellationState
                     state=RW_CANCELLATION_DISABLED);

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

~RWReadersWriterLock();

Recovers any system resources used to implement the RWReadersWriterLock. Can throw RWTHRInternalError.

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.

void
acquire();

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();

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.

This method will return immediately on success for single-threaded builds. A debug assertion will occur or an RWTHRInternalError will be thrown on failure.

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.

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.

This method will return immediately in single-threaded builds.

void
acquireWrite();

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.

This method will return immediately on success for single-threaded builds. A debug assertion will occur or an RWTHRInternalError will be thrown on failure.

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.

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.

This method will return immediately in single-threaded builds.

void
release();

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.

bool
tryAcquire();

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

bool
tryAcquireRead();

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.

bool
tryAcquireWrite();

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.

RWReadersWriterLock(const RWReadersWriterLock& second);

Copy construction prohibited.

RWReadersWriterLock&
operator=(const RWReadersWriterLock& second);

Assignment prohibited.

RWTReadLockGuard<Resource>, RWTTryReadLockGuard<Resource>, RWTReadUnlockGuard<Resource>, RWTWriteLockGuard<Resource>, RWTTryWriteLockGuard<Resource>, RWTWriteUnlockGuard<Resource>

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.