CXMutex

The CXMutex class is the most basic form of locking primitive. The object exists in one of two states: LOCKED or UNLOCKED. Any thread may lock the object, after which any further attempt (by any thread, including the lock-owner) to lock it again will block until it has been unlocked. The unlock must be performed by the lock-owner thread.

 

</div> <div class="mw-parser-output">void LockMutex(void) const;</div> <div class="mw-parser-output">void UnlockMutex(void) const;</div> <div class="mw-parser-output">bool TryAndLockMutex(void) const;</div> <div class="mw-parser-output">

Restrictions

The CXMutex is UNLOCKED when constructed.

The CXMutex should be returned to the UNLOCKED state prior to destruction. It is considered an error for the application to destroy a CXMutex while it is locked, because that would likely to lead to unlock attempts after destruction.

An attempt to lock or unlock a CXMutex during or after its destruction is considered an error. The resultant behaviour is undefined. This includes the scenario where a lock attempt is placed prior to destruction, but cannot be honored until destruction has begun.

It is considered an error for the application to attempt to lock a CXMutex on the lock-owner thread. The resultant behaviour is undefined, typically leading to either a deadlock, an assertion, or both.

No attempt is made to detect or recover from deadlocks. It is the callers responsibility to ensure that locks are taken and released in an approriate manner to avoid deadlocks.

 

Performance

CXMutex uses the underlying OS mutex support, and typically performs a system call. While not horrifically slow, it is measurably slower on average than a CXSpinLock in any case where the lock is low-contention. CXMutex is well-suited to tasks where locking and unlocking do not occur overly frequently, and where the amount of time spent with the lock held is non-trivial.