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
ArTime *	myLockStarted
ArTime *	myLockTime
bool	myLog
std::string	myLogName
MutexType	myMutex
bool	myNonRecursive
ArStrMap	myStrMap
bool	myWasAlreadyLocked
Static Protected Attributes
static unsigned int	ourLockWarningMS = 0
static ArFunctor *	ourNonRecursiveDeadlockFunctor = 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:

• ArMutex.h
• ArMutex.cpp
• ArMutex_LIN.cpp
• ArMutex_WIN.cpp

---