 |
Vault
4.1
|
|
Vault
4.1
|
VMutexLocker is a helper class that you can use to make working with mutexes easier, and more importantly to guarantee proper release behavior of a VMutex even when exceptions are raised. More...
#include <vmutexlocker.h>
Public Member Functions | |
| VMutexLocker (VMutex *mutex, const VString &name, bool lockInitially=true) | |
| Constructs the locker, and if specified, acquires the mutex lock. | |
| virtual | ~VMutexLocker () |
| Destructor, unlocks the mutex if this object has acquired it. | |
| virtual void | lock () |
| Acquires the mutex lock; if the mutex is currently locked by another thread, this call blocks until the mutex lock can be acquired (if several threads are competing, the order in which they acquire the mutex is not known). | |
| virtual void | unlock () |
| Releases the mutex lock; if one or more other threads is waiting on the mutex, one of them will unblock and acquire the mutex lock once this thread releases it. | |
| bool | isLocked () const |
| Returns true if this object has acquired the lock. | |
| VMutex * | getMutex () |
| Returns a pointer to the VMutex object. | |
| void | yield () |
| Yields the current thread with the mutex unlocked; that is, this function unlocks the mutex, yields the current thread, and re-locks the mutex before returning. | |
Protected Attributes | |
| VMutex * | mMutex |
| Pointer to the VMutex object, or NULL. | |
| bool | mIsLocked |
| True if this object has acquired the lock. | |
| VString | mName |
| The name of this locker, for diagnostic purposes. | |
VMutexLocker is a helper class that you can use to make working with mutexes easier, and more importantly to guarantee proper release behavior of a VMutex even when exceptions are raised.
VMutexLocker lets you avoid ugly code to properly manage the mutex, and instead let C++ auto object destruction do the work for you.
Typically, you need to acquire and release a mutex lock in a function in order to guarantee thread-safety. It is important that the mutex lock gets released when you are done with it. If you throw an exception, this is ugly to properly code, but VMutexLocker makes it trivial.
void doSomethingSafelyToAnObject(MyObject obj)
{
VMutexLocker locker(obj.mMutex);
obj.somethingDangerous(); // might throw an exception!
if (obj.trouble())
throw VException("Oh no!");
}
In the example above, you are guaranteed that the MyObject's mMutex will be properly unlocked no matter whether you or something you call throws an exception. This is because the locker object is guaranteed to be properly destructed when the function scope exits, and the object's destructor releases the mutex lock.
You can call the lock() method separately if you need to construct the VMutexLocker without locking right away, but lock it later.
You can call the unlock() method separately if you need to unlock the mutex before the VMutexLocker is destructed. Another useful technique to cause the lock to be released earlier than the end of a function is to create a scope specifically to surround the VMutexLocker's existence.
Definition at line 66 of file vmutexlocker.h.
Constructs the locker, and if specified, acquires the mutex lock.
If the mutex is already locked by another thread, this call blocks until it obtains the lock.
You can pass NULL to constructor if you don't want anything to happen; this can useful if, for example, you allow a NULL VMutex pointer to be passed to a routine that needs to lock it if supplied.
| mutex | the VMutex to lock, or NULL if no action is wanted |
| name | the mutex locker name; calling object/function name is a useful string |
| lockInitially | true if the lock should be acquired on construction |
Definition at line 17 of file vmutexlocker.cpp.
References lock().
| bool VMutexLocker::isLocked | ( | ) | const [inline] |
Returns true if this object has acquired the lock.
Definition at line 105 of file vmutexlocker.h.
References mIsLocked.
| VMutex* VMutexLocker::getMutex | ( | ) | [inline] |
Returns a pointer to the VMutex object.
Definition at line 110 of file vmutexlocker.h.
References mMutex.
| void VMutexLocker::yield | ( | ) |
Yields the current thread with the mutex unlocked; that is, this function unlocks the mutex, yields the current thread, and re-locks the mutex before returning.
This can be used to make a thread that has a lock more "cooperative" with other threads that are competing for the same lock.
Definition at line 53 of file vmutexlocker.cpp.
References isLocked(), lock(), and unlock().