RWMutexLock Class Reference
[Synchronization]

Implements a mutex, or mutual exclusion lock. More...

#include <rw/sync/RWMutexLock.h>

Inheritance diagram for RWMutexLock:

Public Types
typedef RWTLockGuard< RWMutexLock >	LockGuard
typedef RWTReadLockGuard < RWMutexLock >	ReadLockGuard
typedef RWTWriteLockGuard < RWMutexLock >	WriteLockGuard
typedef RWTTryLockGuard < RWMutexLock >	TryLockGuard
typedef RWTTryReadLockGuard < RWMutexLock >	TryReadLockGuard
typedef RWTTryWriteLockGuard < RWMutexLock >	TryWriteLockGuard
typedef RWTUnlockGuard < RWMutexLock >	UnlockGuard
typedef RWTReadUnlockGuard < RWMutexLock >	ReadUnlockGuard
typedef RWTWriteUnlockGuard < RWMutexLock >	WriteUnlockGuard
Public Member Functions
	RWMutexLock (RWStaticCtor)
	RWMutexLock (RWCancellationState state=0)
	~RWMutexLock ()
void	acquire ()
RWWaitStatus	acquire (unsigned long milliseconds)
void	acquireRead ()
RWWaitStatus	acquireRead (unsigned long milliseconds)
void	acquireWrite ()
RWWaitStatus	acquireWrite (unsigned long milliseconds)
RWMutexLockRep *	getMutexLockRep () const
bool	isAcquired () const
void	release ()
bool	tryAcquire ()
bool	tryAcquireRead ()
bool	tryAcquireWrite ()
Private Member Functions
	RWMutexLock (const RWMutexLock &second)
RWMutexLock &	operator= (const RWMutexLock &second)
Related Functions
(Note that these are not member functions.)
typedef bool	RWMutexLockRep
typedef pthread_mutex_t	RWMutexLockRep
typedef mutex_t	RWMutexLockRep
typedef RWMutexType	RWMutexLockRep
typedef void *	RWMutexLockRep

Detailed Description

RWMutexLock implements a mutex or mutual exclusion lock. It can be used to permit only one thread at a time to access a section of code that is to be treated as a single atomic operation. Mutexes are typically used to protect sections of code that access shared resources or data. The sensitive area of code, or critical section, is bracketed by calls to acquire() and release() on the mutex.

All operations on the mutex, except initialization, are themselves guaranteed to be atomic in order to prevent race conditions from destroying the integrity of the lock. However, there is no reliable mechanism to guarantee that a race condition will not occur during initialization of a mutex lock. Generally, the application can ensure this by creating and initializing all mutexes in a primary thread of execution, before other threads are spawned. However, in the common case, when a mutex is used to protect static global data, there is no portable way to atomically initialize the mutex because C++ defines the order of initialization of static variables to be implementation-specific.

RWMutexLock provides some protection against race conditions during initialization of static global mutexes through a special constructor that does no initialization. When this constructor is used, initialization is postponed until the first attempt to acquire the lock. In order to prevent race conditions during mutex initialization by using this constructor, the application must still make sure the first acquire operation on such a mutex is not attempted concurrently by two or more threads.

This class is primarily a portable object wrapper for platform-specific mutex implementations. For example, RWMutexLock uses an instance of pthread_mutex_t for POSIX conforming environments, mutex_t on Solaris platforms, and a mutex represented by a HANDLE under Win32.

If the Threads Module is built with the "Implement RWMutexLock with a Critical Section option enabled", the underlying implementation of the class is altered to use a CRITICAL_SECTION under Win32 systems instead of a HANDLE. This provides a significant performance boost in many cases at the cost of some portability and functionality.

Examples

 #include <rw/sync/RWMutexLock.h>    // for RWMutexLock
 #include <rw/sync/RWTLockGuard.h>    // for RWTLockGuard<T>

 class SavingsAccount {
 public:
    SavingsAccount(int initialBalance);
    void deposit(int amount);
    void withdraw(int amount);
    int balance(void);
    static void decreaseInterestRate(double decrement);
    static double getInterestRate(void);

 private:
    int balance_;
    static double interestRate_;
    RWMutexLock objectMutex_;       // mutex to protect
                                    // instance data
 };

 void SavingsAccount::deposit(int amount)
 {
    // Acquire mutex so that only one thread can access the
    // state. Normally you should use a LockGuard to acquire a
    // mutex that is to be released at the end of a scope. We
    // show the explicit form here for completeness. The
    // preferred form is shown below.

    objectMutex_.acquire();
    balance_ += amount;
    objectMutex_.release();

 }

 void SavingsAccount::withdraw(int amount)
 {

    // An RWTLockGuard acquires a synch. object
    // in its constructor and releases it in its destructor.
    // Using this class is preferred over direct calls to acquire
    // and release the mutex because:
    // 1) you will never forget to do the release
    // 2) if an exception is thrown from somewhere in your
    //    function, the lock will always be released because all
    //    objects on the stack will have their destructors called
    //    as the stack is unwound.

    // calls objectMutex_.acquire():
    RWTLockGuard<RWMutexLock> lock(objectMutex_);
    balance_ -= amount;

    // objectMutex released in lock destructor.
 }


 int SavingsAccount::balance(void)
 {

    // RWMutexLock::LockGuard is a typedef of
    // RWTLockGuard<RWMutexLock>. It has the same effect
    // as above. This is the form that we prefer
    // for purely aesthetic reasons:

    RWMutexLock::LockGuard lock(objectMutex_);
    return balance_;

    // objectMutex released in lock destructor.
 }

See also:: RWNullMutexLock RWTLockGuard<Resource> RWTTryLockGuard<Resource>