Bayonne2 / Common C++ 2 Framework
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Private Attributes | Static Private Attributes
Mutex Class Reference

The Mutex class is used to protect a section of code so that at any given time only a single thread can perform the protected operation. More...

#include <thread.h>

Inheritance diagram for Mutex:
Inheritance graph
[legend]
Collaboration diagram for Mutex:
Collaboration graph
[legend]

Public Member Functions

 Mutex (const char *name=NULL)
 The mutex is always initialized as a recursive entity. More...
 
virtual ~Mutex ()
 Destroying the mutex removes any system resources associated with it. More...
 
void nameMutex (const char *name)
 Enable setting of mutex name for deadlock debug. More...
 
void enterMutex (void)
 Entering a Mutex locks the mutex for the current thread. More...
 
void enter (void)
 Future abi will use enter/leave/test members. More...
 
void leave (void)
 Future abi will use enter/leave/test members. More...
 
bool test (void)
 Future abi will use enter/leave/test members. More...
 
bool tryEnterMutex (void)
 Tries to lock the mutex for the current thread. More...
 
void leaveMutex (void)
 Leaving a mutex frees that mutex for use by another thread. More...
 

Static Public Member Functions

static void setDebug (bool mode)
 Enable or disable deadlock debugging. More...
 

Private Attributes

String _name
 
int volatile _level
 
Thread *volatile _tid
 
pthread_mutex_t _mutex
 

Static Private Attributes

static bool _debug
 

Detailed Description

The Mutex class is used to protect a section of code so that at any given time only a single thread can perform the protected operation.

The Mutex can be used as a base class to protect access in a derived class. When used in this manner, the ENTER_CRITICAL and LEAVE_CRITICAL macros can be used to specify when code written for the derived class needs to be protected by the default Mutex of the derived class, and hence is presumed to be 'thread safe' from multiple instance execution. One of the most basic Common C++ synchronization object is the Mutex class. A Mutex only allows one thread to continue execution at a given time over a specific section of code. Mutex's have a enter and leave method; only one thread can continue from the Enter until the Leave is called. The next thread waiting can then get through. Mutex's are also known as "CRITICAL SECTIONS" in win32-speak.

The Mutex is always recursive in that if the same thread invokes the same mutex lock multiple times, it must release it multiple times. This allows a function to call another function which also happens to use the same mutex lock when called directly. This was deemed essential because a mutex might be used to block individual file requests in say, a database, but the same mutex might be needed to block a whole series of database updates that compose a "transaction" for one thread to complete together without having to write alternate non-locking member functions to invoke for each part of a transaction.

Strangely enough, the original pthread draft standard does not directly support recursive mutexes. In fact this is the most common "NP" extension for most pthread implementations. Common C++ emulates recursive mutex behavior when the target platform does not directly support it.

In addition to the Mutex, Common C++ supports a rwlock class. This implements the X/Open recommended "rwlock". On systems which do not support rwlock's, the behavior is emulated with a Mutex; however, the advantage of a rwlock over a mutex is then entirely lost. There has been some suggested clever hacks for "emulating" the behavior of a rwlock with a pair of mutexes and a semaphore, and one of these will be adapted for Common C++ in the future for platforms that do not support rwlock's directly.

Author
David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m Mutex lock for protected access.

Definition at line 186 of file thread.h.

Constructor & Destructor Documentation

Mutex::Mutex ( const char *  name = NULL)

The mutex is always initialized as a recursive entity.

Parameters
nameof mutex for optional deadlock detection
virtual Mutex::~Mutex ( )
virtual

Destroying the mutex removes any system resources associated with it.

If a mutex lock is currently in place, it is presumed to terminate when the Mutex is destroyed.

Member Function Documentation

void Mutex::enter ( void  )
inline

Future abi will use enter/leave/test members.

Definition at line 263 of file thread.h.

void Mutex::enterMutex ( void  )

Entering a Mutex locks the mutex for the current thread.

This also can be done using the ENTER_CRITICAL macro or by using the ++ operator on a mutex.

See Also
leaveMutex
void Mutex::leave ( void  )
inline

Future abi will use enter/leave/test members.

Definition at line 269 of file thread.h.

void Mutex::leaveMutex ( void  )

Leaving a mutex frees that mutex for use by another thread.

If the mutex has been entered (invoked) multiple times (recursivily) by the same thread, then it will need to be exited the same number of instances before it is free for re-use. This operation can also be done using the LEAVE_CRITICAL macro or by the – operator on a mutex.

See Also
enterMutex
void Mutex::nameMutex ( const char *  name)
inline

Enable setting of mutex name for deadlock debug.

Parameters
namefor mutex.

Definition at line 248 of file thread.h.

static void Mutex::setDebug ( bool  mode)
inlinestatic

Enable or disable deadlock debugging.

Parameters
modedebug mode.

Definition at line 240 of file thread.h.

bool Mutex::test ( void  )
inline

Future abi will use enter/leave/test members.

Returns
true if entered.

Definition at line 277 of file thread.h.

bool Mutex::tryEnterMutex ( void  )

Tries to lock the mutex for the current thread.

Behaves like enterMutex , except that it doesn't block the calling thread if the mutex is already locked by another thread.

Returns
true if locking the mutex was succesful otherwise false
See Also
enterMutex
leaveMutex

Field Documentation

bool Mutex::_debug
staticprivate

Definition at line 189 of file thread.h.

int volatile Mutex::_level
private

Definition at line 193 of file thread.h.

pthread_mutex_t Mutex::_mutex
private

Definition at line 204 of file thread.h.

String Mutex::_name
private

Definition at line 190 of file thread.h.

Thread* volatile Mutex::_tid
private

Definition at line 194 of file thread.h.


The documentation for this class was generated from the following file: