NAME
ost::Mutex -
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.
SYNOPSIS
#include <thread.h>
Inherited by ost::MapTable, ost::MutexCounter, ost::RandomFile
[protected], ost::Runlist, ost::SerialService [private],
ost::SharedMemPager, ost::SocketService [private], and
ost::ThreadQueue.
Public Member Functions
Mutex (const char *name=NULL)
The mutex is always initialized as a recursive entity.
virtual ~Mutex ()
Destroying the mutex removes any system resources associated with
it.
void nameMutex (const char *name)
Enable setting of mutex name for deadlock debug.
void enterMutex (void)
Entering a Mutex locks the mutex for the current thread.
void enter (void)
Future abi will use enter/leave/test members.
void leave (void)
Future abi will use enter/leave/test members.
bool test (void)
Future abi will use enter/leave/test members.
bool tryEnterMutex (void)
Tries to lock the mutex for the current thread.
void leaveMutex (void)
Leaving a mutex frees that mutex for use by another thread.
Static Public Member Functions
static void setDebug (bool mode)
Enable or disable deadlock debugging.
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@ostel.com> Mutex lock for protected access.
Examples:
tcpservice.cpp, and tcpthread.cpp.
Constructor & Destructor Documentation
ost::Mutex::Mutex (const char * name = NULL)
The mutex is always initialized as a recursive entity. Parameters:
name of mutex for optional deadlock detection
virtual ost::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 ost::Mutex::enter (void) [inline]
Future abi will use enter/leave/test members.
void ost::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 ost::Mutex::leave (void) [inline]
Future abi will use enter/leave/test members.
void ost::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 ost::Mutex::nameMutex (const char * name) [inline]
Enable setting of mutex name for deadlock debug. Parameters:
name for mutex.
static void ost::Mutex::setDebug (bool mode) [inline, static]
Enable or disable deadlock debugging. Parameters:
mode debug mode.
bool ost::Mutex::test (void) [inline]
Future abi will use enter/leave/test members. Returns:
true if entered.
bool ost::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
Author
Generated automatically by Doxygen for GNU CommonC++ from the source
code.