Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages | Examples

ArMutex Class Reference

#include <ArMutex.h>

List of all members.


Detailed Description

Mutex wrapper class.

This class wraps the operating system's mutex functions. It allows mutualy exclusive access to a critical section. This is extremely useful for multiple threads which want to use the same variable. On Linux, ArMutex simply uses the POSIX pthread interface in an object oriented manner. It also applies the same concept to Windows using Windows' own abilities to restrict access to critical sections.

Note:
ArMutex is by default a recursive mutex. This means that a thread is allowed to acquire an additional lock (whether via lock() or tryLock()) on a locked mutex if that same thread already has the lock. This allows a thread to lock a mutex, but not become deadlocked if any functions called while it is locked also attempt to lock the mutex, while still preventing other threads from interrupting it. If you want a non-recursive mutex, so that multiple attempts by the same thread to lock a mutex to block, supply an argument of 'false' to the constructor.
Examples:

gpsRobotTaskExample.cpp, and threadExample.cpp.


Public Types

typedef pthread_mutex_t MutexType
enum  Status { STATUS_FAILED_INIT = 1, STATUS_FAILED, STATUS_ALREADY_LOCKED }

Public Member Functions

 ArMutex (const ArMutex &mutex)
 Copy constructor.
 ArMutex (bool recursive=true)
 Constructor.
virtual const char * getError (int messageNumber) const
 Get a human readable error message from an error code.
virtual MutexType & getMutex ()
 Get a reference to the underlying OS-specific mutex variable.
virtual int lock ()
void setLog (bool log)
void setLogName (const char *logName)
 Sets a name we'll use to log with.
void setLogNameVar (const char *logName,...)
 Sets a name we'll use to log with formatting.
virtual int tryLock ()
virtual int unlock ()
 Unlock the mutex, allowing another thread to obtain the lock.
virtual ~ArMutex ()
 Destructor.

Static Public Member Functions

static double getLockWarningTime (void)
static double getUnlockWarningTime (void)
static void setLockWarningTime (double lockWarningSeconds)
static void setUnlockWarningTime (double unlockWarningSeconds)

Protected Member Functions

void checkLockTime ()
void checkUnlockTime ()
void initLockTiming ()
void startLockTimer ()
void startUnlockTimer ()
void uninitLockTiming ()

Protected Attributes

bool myFailedInit
bool myFirstLock
ArTimemyLockStarted
ArTimemyLockTime
bool myLog
std::string myLogName
MutexType myMutex
bool myNonRecursive
ArStrMap myStrMap
bool myWasAlreadyLocked

Static Protected Attributes

static unsigned int ourLockWarningMS = 0
static ArFunctorourNonRecursiveDeadlockFunctor = NULL
static unsigned int ourUnlockWarningMS = 0


Member Enumeration Documentation

enum ArMutex::Status
 

Enumeration values:
STATUS_FAILED_INIT  Failed to initialize.
STATUS_FAILED  General failure.
STATUS_ALREADY_LOCKED  Mutex already locked.


Constructor & Destructor Documentation

ArMutex::ArMutex bool  recursive = true  ) 
 

Constructor.

KMC TESTING myStrMap[STATUS_FAILED_INIT]="Failed to initialize"; myStrMap[STATUS_FAILED]="General failure"; myStrMap[STATUS_ALREADY_LOCKED]="Mutex already locked";


Member Function Documentation

static double ArMutex::getLockWarningTime void   )  [inline, static]
 

Gets the lock warning time (sec)

Note:
Available on Linux only

static double ArMutex::getUnlockWarningTime void   )  [inline, static]
 

Gets the lock warning time (sec)

Note:
Available on Linux only

int ArMutex::lock  )  [virtual]
 

Lock the mutex

If this is a recursive mutex (the default type), and a different thread has locked this mutex, then block until it is unlocked; if this thread has locked this mutex, then continue immediately and do not block.

If this is not a recursive mutex, then block if any thread (including this thread) has locked this mutex.

Call setLog(true) to enable extra logging.

Returns:
0 if the mutex was successfully locked (after blocking if it was already locked by another thread, or by any thread if this is not a recursive mutex).

ArMutex::STATUS_ALREADY_LOCKED immediately if this is a recursive mutex (default) and the current thread has already locked this mutex.

ArMutex::STATUS_FAILED on an error from the platform mutex implementation.

ArMutex::STATUS_FAILED_INIT if the platform threading is not enabled, initialized, etc.

static void ArMutex::setLockWarningTime double  lockWarningSeconds  )  [inline, static]
 

Sets the lock warning time (sec). If it takes more than lockWarningSeconds to perform the mutex lock in lock(), log a warning.

Note:
Available on Linux only

void ArMutex::setLog bool  log  )  [inline]
 

Sets a flag that will log out when we lock and unlock. Use setLogName() to set a descriptive name for this mutex, and ArThread::setThreadName() to set a descriptive name for a thread.

void ArMutex::setLogNameVar const char *  logName,
  ...
 

Sets a name we'll use to log with formatting.

Java and Python Wrappers: Not available in Java or Python wrapper libraries. use setLogName()

static void ArMutex::setUnlockWarningTime double  unlockWarningSeconds  )  [inline, static]
 

Sets the unlock warning time (sec). If it takes more than unlockWarningSeconds between the mutex being locked with lock() then unlocked with unlock(), log a warning.

Note:
Available on Linux only

int ArMutex::tryLock  )  [virtual]
 

Try to lock the mutex, but do not block

If this is a recursive mutex (the default type), and a different thread has locked this mutex, then return ArMutex::STATUS_ALREADY_LOCKED; if this thread has locked this mutex, then return 0.

If this is not a recursive mutex, then return 0 if any thread (including this thread) has locked this mutex.

Returns ArMutex::STATUS_FAILED or ArMutex::STATUS_FAILED_INIT on an error (such as threading not initialized or supported).

Call setLog(true) to enable extra logging.

Returns:
0 If tryLock() acquires the lock, or mutex is a recursive mutex (default) and is already locked by this thread

ArMutex::STATUS_ALREADY_LOCKED if this mutex is currently locked by another thread, or if mutex is not recursive, by any thread including the current thread.

ArMutex::STATUS_FAILED on an error from the platform mutex implementation.

ArMutex::STATUS_FAILED_INIT if the platform threading is not enabled, initialized, etc.


The documentation for this class was generated from the following files:
Generated on Thu Jan 7 10:34:42 2010 for Aria by  doxygen 1.4.2