ArMutex Class Reference

Cross-platform mutex wrapper class. More...

#include <ArMutex.h>

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

Public Member Functions
	ArMutex (bool recursive=true)
	Constructor. More...
	ArMutex (const ArMutex &mutex)
	Copy 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 ()
	Lock the mutex. More...
void	setLog (bool log)
	Sets a flag that will log out when we lock and unlock. More...
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. More...
virtual int	tryLock ()
	Try to lock the mutex, but do not block. More...
virtual int	unlock ()
	Unlock the mutex, allowing another thread to obtain the lock.
virtual	~ArMutex ()
	Destructor.

Static Public Member Functions
static double	getLockWarningTime (void)
	Gets the lock warning time (sec) More...
static double	getUnlockWarningTime (void)
	Gets the lock warning time (sec) More...
static void	setLockWarningTime (double lockWarningSeconds)
	Sets the lock warning time (sec). More...
static void	setUnlockWarningTime (double unlockWarningSeconds)
	Sets the unlock warning time (sec). More...

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

Detailed Description

Cross-platform 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. ArMutex also adds additional diagnostic/debugging tools such as logging and timing.

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.

Member Enumeration Documentation

Status

enum ArMutex::Status

Enumerator
STATUS_FAILED_INIT	Failed to initialize.
STATUS_FAILED	General failure.
STATUS_ALREADY_LOCKED	Mutex already locked.

Constructor & Destructor Documentation

ArMutex()

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

getLockWarningTime()

static double ArMutex::getLockWarningTime ( void  )

inlinestatic

Gets the lock warning time (sec)

Note

Available on Linux only

getUnlockWarningTime()

static double ArMutex::getUnlockWarningTime ( void  )

inlinestatic

Gets the lock warning time (sec)

Note

Available on Linux only

lock()

int ArMutex::lock ( void  )

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.

This function will block until no other thread has this mutex locked. If it returns 0, then it obtained the lock and the thread is free to use the critical section that this mutex protects. Else it returns an error code. See getError().

Examples:

threadExample.cpp.

setLockWarningTime()

static void ArMutex::setLockWarningTime ( double  lockWarningSeconds )

inlinestatic

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

setLog()

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.

setLogNameVar()

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()

setUnlockWarningTime()

static void ArMutex::setUnlockWarningTime ( double  unlockWarningSeconds )

inlinestatic

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

tryLock()

int ArMutex::tryLock ( )

virtual

Try to lock the mutex, but do not block.

Try to lock the mutex.

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.

This function will not block if another thread has the mutex locked. It will return instantly if that is the case. It will return STATUS_ALREADY_LOCKED if another thread has the mutex locked. If it obtains the lock, it will return 0.

---

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

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