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

       Referenced by ost::SysTime::lock(), and ost::MutexLock::MutexLock().

   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

       Referenced by ost::SysTime::unlock(), and ost::MutexLock::~MutexLock().

   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.