Aria: ArMutex Class Reference

- Main Page
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# 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.

## 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
static ArFunctor * | ourNonRecursiveDeadlockFunctor
static unsigned int | ourUnlockWarningMS

## Member Enumeration Documentation

enum ArMutex::Status

Enumerator:

  STATUS_FAILED_INIT | Failed to initialize.
  STATUS_FAILED | General failure.
  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

virtual 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

virtual 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 file:

- ArMutex.h