SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWMutexLock Class Reference

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

#include <rw/sync/RWMutexLock.h>

Inheritance diagram for RWMutexLock:
RWSynchObject

Public Types

typedef RWTLockGuard< RWMutexLockLockGuard
 
typedef RWTReadLockGuard< RWMutexLockReadLockGuard
 
typedef RWTReadUnlockGuard< RWMutexLockReadUnlockGuard
 
typedef RWTTryLockGuard< RWMutexLockTryLockGuard
 
typedef RWTTryReadLockGuard< RWMutexLockTryReadLockGuard
 
typedef RWTTryWriteLockGuard< RWMutexLockTryWriteLockGuard
 
typedef RWTUnlockGuard< RWMutexLockUnlockGuard
 
typedef RWTWriteLockGuard< RWMutexLockWriteLockGuard
 
typedef RWTWriteUnlockGuard< RWMutexLockWriteUnlockGuard
 

Public Member Functions

 RWMutexLock (RWCancellationState state=0)
 
 RWMutexLock (RWStaticCtor)
 
 ~RWMutexLock ()
 
void acquire ()
 
RWWaitStatus acquire (unsigned long milliseconds)
 
void acquireRead ()
 
RWWaitStatus acquireRead (unsigned long milliseconds)
 
void acquireWrite ()
 
RWWaitStatus acquireWrite (unsigned long milliseconds)
 
RWMutexLockRepgetMutexLockRep () const
 
bool isAcquired () const
 
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

 RWMutexLock (const RWMutexLock &second)
 
RWMutexLockoperator= (const RWMutexLock &second)
 

Related Symbols

(Note that these are not member symbols.)

typedef pthread_mutex_t RWMutexLockRep
 
typedef mutex_t RWMutexLockRep
 
typedef RW_MUTEX_T RWMutexLockRep
 
typedef void * RWMutexLockRep
 

Additional Inherited Members

- Protected Member Functions inherited from RWSynchObject
 RWSynchObject (const RWSynchObject &second)
 
 RWSynchObject (RWCancellationState state=0)
 
 RWSynchObject (RWStaticCtor)
 
RWSynchObjectoperator= (const RWSynchObject &second)
 
void testCancellation ()
 

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.

Example
#include <rw/sync/RWMutexLock.h>
#include <rw/sync/RWTLockGuard.h>
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 synchronization 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.
}
Implements a mutex, or mutual exclusion lock.
Definition RWMutexLock.h:231
void acquire()
A guard that acquires its resource upon creation and releases it upon destruction.
Definition RWTLockGuard.h:61
See also
RWNullMutexLock, RWTLockGuard, RWTTryLockGuard

Member Typedef Documentation

◆ LockGuard

Predefined type for compatible guard.

◆ ReadLockGuard

Predefined type for compatible guard.

◆ ReadUnlockGuard

Predefined type for compatible guard.

◆ TryLockGuard

Predefined type for compatible guard.

◆ TryReadLockGuard

Predefined type for compatible guard.

◆ TryWriteLockGuard

Predefined type for compatible guard.

◆ UnlockGuard

Predefined type for compatible guard.

◆ WriteLockGuard

Predefined type for compatible guard.

◆ WriteUnlockGuard

Predefined type for compatible guard.

Constructor & Destructor Documentation

◆ RWMutexLock() [1/3]

RWMutexLock::RWMutexLock ( RWStaticCtor )

Creates an RWMutexLock but does no direct initialization. The mutex will be initialized upon first use.

The RWMutexLock static constructor must be used only for global static instances. Use of this constructor with an automatically or dynamically allocated instance produces errors or other unpredictable behavior.

The initialization of a global static mutex is not thread-safe. It is conceivable that two threads can attempt to acquire and initialize a mutex simultaneously, resulting in a race condition. When designing your application, take care to avoid such a possibility.

◆ RWMutexLock() [2/3]

RWMutexLock::RWMutexLock ( RWCancellationState state = 0)

Creates and initializes an RWMutexLock. The thread cancellation state of the object is initialized to state. Possible exceptions include RWTHRResourceLimit and RWTHRInternalError.

◆ ~RWMutexLock()

RWMutexLock::~RWMutexLock ( )

Recovers the system resource used to implement the RWMutexLock. Possible exceptions include RWTHRInternalError.

◆ RWMutexLock() [3/3]

RWMutexLock::RWMutexLock ( const RWMutexLock & second)
private

Copy construction prohibited.

Member Function Documentation

◆ acquire() [1/2]

void RWMutexLock::acquire ( )

Causes the current thread to block until the mutex is released, at which time the thread acquires the mutex and continues. In the debug version of the Threads Module, this function will produce an assertion and abort if a thread attempts to recursively acquire the same mutex. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

This function throws an RWCancellation object if the mutex has cancellation detection enabled and a runnable containing the calling thread has been canceled.

In single-threaded builds, this method returns immediately. If the mutex was unavailable for acquisition, a debug assertion occurs or an RWTHRInternalError is thrown.

◆ acquire() [2/2]

RWWaitStatus RWMutexLock::acquire ( unsigned long milliseconds)

Blocks at least for the specified number of milliseconds, or until the mutex is released, whichever comes first. If the mutex is released within the specified time, acquires it, and continues. If the mutex is not released, returns RW_THR_TIMEOUT. In the debug version of the Threads Module, this function produces an assertion and aborts if a thread attempts to recursively acquire the same mutex.

Note that true timed-acquisition is not supported on all platforms. For platforms without true timed-acquisition support, the function simply returns RW_THR_TIMEOUT if the mutex cannot be acquired immediately, Timed mutex acquisition is available if the macro RW_THR_HAS_TIMED_MUTEX_ACQUIRE is defined.

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

This method returns immediately in single-threaded builds.

◆ acquireRead() [1/2]

void RWMutexLock::acquireRead ( )
inline

Calls acquire(). Provided for compatibility with read/write locks. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

◆ acquireRead() [2/2]

RWWaitStatus RWMutexLock::acquireRead ( unsigned long milliseconds)
inline

Calls acquire(milliseconds). Provided for compatibility with read/write locks. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

◆ acquireWrite() [1/2]

void RWMutexLock::acquireWrite ( )
inline

Calls acquire(). Provided for compatibility with read/write locks. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

◆ acquireWrite() [2/2]

RWWaitStatus RWMutexLock::acquireWrite ( unsigned long milliseconds)
inline

Calls acquire(milliseconds). Provided for compatibility with read/write locks. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

◆ getMutexLockRep()

RWMutexLockRep * RWMutexLock::getMutexLockRep ( ) const
inline

Provides access to the underlying platform-specific mutex implementation.

◆ isAcquired()

bool RWMutexLock::isAcquired ( ) const

Determines whether the calling thread currently owns the mutex.

Condition:
Available only from the debug version of the Threads Module.

◆ operator=()

RWMutexLock & RWMutexLock::operator= ( const RWMutexLock & second)
private

Assignment prohibited.

◆ release()

void RWMutexLock::release ( )

Releases the mutex, making it available. Possible exceptions include RWTHRInternalError.

◆ tryAcquire()

bool RWMutexLock::tryAcquire ( )

Tries to acquire the mutex without blocking. Returns true if the mutex is acquired, and false if the mutex is not acquired.

Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

◆ tryAcquireRead()

bool RWMutexLock::tryAcquireRead ( )
inline

Calls tryAcquire(). Provided for compatibility with read/write locks. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

◆ tryAcquireWrite()

bool RWMutexLock::tryAcquireWrite ( )
inline

Calls tryAcquire(). Provided for compatibility with read/write locks. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.

Friends And Related Symbol Documentation

◆ RWMutexLockRep [1/4]

typedef pthread_mutex_t RWMutexLockRep
related

Typedef for the internal mutex lock.

Condition:
This type is used for build configurations based on POSIX threads.

◆ RWMutexLockRep [2/4]

typedef mutex_t RWMutexLockRep
related

Typedef for the internal mutex lock.

Condition:
This type is used for build configurations based on Solaris threads.

◆ RWMutexLockRep [3/4]

typedef RW_MUTEX_T RWMutexLockRep
related

Typedef for the internal mutex lock.

Condition:
This type is used for build configurations based on Win32 threads when the macro RW_SYNC_MUTEX_USES_CRITICAL_SECTION is defined.

◆ RWMutexLockRep [4/4]

typedef void* RWMutexLockRep
related

Typedef for the internal mutex lock.

Condition:
This type is used for build configurations based on Win32 threads when the macro RW_SYNC_MUTEX_USES_CRITICAL_SECTION is not defined.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.