Difference between revisions of "CXMutex"
From cxwiki
(Created page with "<div class="mw-parser-output"><div class="mw-parser-output">The CXMutex class is the most basic form of locking primitive. The object exists in one of two states: LOCKED or UN...") |
|||
| Line 1: | Line 1: | ||
| − | <div class="mw-parser-output"><div class="mw-parser-output">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"> </div> <div class="mw-parser-output"><syntaxhighlight lang="C++ | + | <div class="mw-parser-output"><div class="mw-parser-output"><div class="mw-parser-output">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"> </div> <div class="mw-parser-output"><syntaxhighlight lang="C++">void LockMutex(void) const; |
| + | void UnlockMutex(void) const; | ||
| + | bool TryAndLockMutex(void) const; | ||
| + | </syntaxhighlight> | ||
| + | </div> | ||
= Restrictions = | = Restrictions = | ||
<div class="mw-parser-output">The CXMutex is UNLOCKED when constructed.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output"> </div> | <div class="mw-parser-output">The CXMutex is UNLOCKED when constructed.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output">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.</div> <div class="mw-parser-output"> </div> | ||
= Performance = | = Performance = | ||
| − | <div class="mw-parser-output">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.</div> <div class="mw-parser-output"> </div> <div class="mw-parser-output"> </div> </div> | + | <div class="mw-parser-output">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.</div> <div class="mw-parser-output"> </div> <div class="mw-parser-output"> </div> </div> </div> |
Revision as of 20:17, 22 February 2018
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.
void LockMutex(void) const;
void UnlockMutex(void) const;
bool TryAndLockMutex(void) const;
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.