A synchronization lock that allows concurrent access to multiple readers, but limits access to a single writer. More...

#include <rw/sync/RWReadersWriterLock.h>

Inheritance diagram for RWReadersWriterLock:

Public Types
typedef RWTLockGuard< RWReadersWriterLock >	LockGuard

typedef RWTReadLockGuard< RWReadersWriterLock >	ReadLockGuard

typedef RWTReadUnlockGuard< RWReadersWriterLock >	ReadUnlockGuard

typedef RWTTryLockGuard< RWReadersWriterLock >	TryLockGuard

typedef RWTTryReadLockGuard< RWReadersWriterLock >	TryReadLockGuard

typedef RWTTryWriteLockGuard< RWReadersWriterLock >	TryWriteLockGuard

typedef RWTUnlockGuard< RWReadersWriterLock >	UnlockGuard

typedef RWTWriteLockGuard< RWReadersWriterLock >	WriteLockGuard

typedef RWTWriteUnlockGuard< RWReadersWriterLock >	WriteUnlockGuard

Public Member Functions
	RWReadersWriterLock (RWCancellationState state=0)

	~RWReadersWriterLock ()

void	acquire ()

RWWaitStatus	acquire (unsigned long)

void	acquireRead ()

RWWaitStatus	acquireRead (unsigned long)

void	acquireWrite ()

RWWaitStatus	acquireWrite (unsigned long)

void	release ()

bool	tryAcquire ()

bool	tryAcquireRead ()

bool	tryAcquireWrite ()

Public Member Functions inherited from RWSynchObject
void	disableCancellation ()

void	enableCancellation (RWCancellationState)

bool	isCancellationEnabled () const

void	setCancellation (RWCancellationState)

Private Member Functions
	RWReadersWriterLock (const RWReadersWriterLock &)

RWReadersWriterLock &	operator= (const RWReadersWriterLock &)

Additional Inherited Members
Protected Member Functions inherited from RWSynchObject
	RWSynchObject (RWCancellationState state=0)

	RWSynchObject (RWStaticCtor)

	RWSynchObject (const RWSynchObject &second)

RWSynchObject &	operator= (const RWSynchObject &second)

void	testCancellation ()

Related Functions inherited from RWSynchObject
#define	RW_CANCELLATION_DISABLED

#define	RW_CANCELLATION_ENABLED

typedef void(*	RWCancellationState) ()

void	rwServiceCancellation (void)

Detailed 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 is granted access. A writer that attempts to acquire the lock blocks waiting for readers to exit the critical section. Note that because this lock favors writers over readers, the writer gets priority over any readers that try to access the lock after the time that the writer attempts to acquire it. A reader attempting to access the lock acquires it only after all writers attempting access have acquired and released the lock.

Example: #include <iostream>

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

}

};

See also: RWTReadLockGuard, RWTTryReadLockGuard, RWTReadUnlockGuard, RWTWriteLockGuard, RWTTryWriteLockGuard, RWTWriteUnlockGuard