Lock a mutex in an RAII manner. More...
Public Member Functions | |
| guard (guard const &rhs)=delete | |
| The copy operator is deleted. | |
| guard (mutex &m) | |
| Lock a mutex. | |
| ~guard () | |
| Ensure that the mutex was unlocked. | |
| bool | is_locked () const |
| This function returns whether the guard is current locked. | |
| void | lock () |
| Relock this mutex. | |
| guard & | operator= (guard const &rhs)=delete |
| The assignment operator is deleted. | |
| void | unlock (bool done=true) |
| Unlock this mutex. | |
Private Attributes | |
| bool | f_locked = false |
| Whether the guard is currently in effect. | |
| mutex * | f_mutex = nullptr |
| The mutex used by the guard class. | |
Detailed Description
This class is used to lock mutexes in a safe manner in regard to exceptions. It is extremely important to unlock all mutexes before a thread quits otherwise the application will lock up.
- Warning
- This guard implementation assumes that the guard itself is used in one single thread. In other words, even though you could add a guard inside an object as a variable member, the lock() and is_locked() functions are not safe in that situation. The constructor and destructor are, so you could still do it that way. It is still preferred to push a guard on the stack as shown in the example above, rather than as a variable member of a class you then create on the stack.
Constructor & Destructor Documentation
◆ guard() [1/2]
| cppthread::guard::guard | ( | mutex & | m | ) |
This function locks the specified mutex and keep track of the lock until the destructor is called.
The mutex parameter cannot be a reference to a nullptr pointer.
- Parameters
-
[in] m The Snap! mutex to lock.
Definition at line 85 of file guard.cpp.
References f_locked, f_mutex, and cppthread::mutex::lock().
◆ guard() [2/2]
|
delete |
The guard class saves a bare pointer to the mutex it is guarding. Because of that, a copy is not really possible and it's also not useful. Plus Effective C++ wants it this way (which is great).
- Parameters
-
[in] rhs The right hand side.
◆ ~guard()
| cppthread::guard::~guard | ( | ) |
The destructor ensures that the mutex gets unlocked. Note that it is written to avoid exceptions, however, if an exception occurs it ends up calling exit(1).
- Note
- If a function throws it logs information using the Snap! logger.
Definition at line 108 of file guard.cpp.
References cppthread::end(), cppthread::log, and unlock().
Member Function Documentation
◆ is_locked()
| bool cppthread::guard::is_locked | ( | ) | const |
This function returns the f_locked flag of the guard object. If true, then the guard is expected to have its mutex locked. If false, then the guard mutex is not currently locked.
- Warning
- This function is not 100% safe if you call unlock() with its done parameter set to true, which is the default. It is safe if the guard is only used by on the stack.
- Returns
- true if the guard currently holds the lock.
Definition at line 236 of file guard.cpp.
References f_locked, f_mutex, cppthread::mutex::lock(), and cppthread::mutex::unlock().
◆ lock()
| void cppthread::guard::lock | ( | ) |
This function can be called any number of times. If called while the mutex is not locked, then it gets relocked, otherwise nothing happens.
Note that when creating the guard, the mutex is automatically locked, so you rarely need to call this function.
This is most often used when a mutex needs to be unlocked within a guarded block:
This example shows how one can run do_special_thing_while_unlocked() while the lock is not being held. The way it is written is still RAII safe. If the do_special_thing_while_unlocked() throws, the mutex is in a known state (i.e. unlocked when exiting the guarded block).
- Note
- This implementation always attempts a mutex::lock(), checks whether it was necessary (i.e. is the f_locked flag false?) and if not, it unlocks the mutex (since the guard already had the lock to itself).
- Warning
- It is not 100% safe to call this function when the guard::unlock() function is called with its done parameter set to true, which is the default if you don't specify false in your call. It is safe if the guard is only used on the stack.
- See also
- unlock()
Definition at line 203 of file guard.cpp.
References f_locked, f_mutex, cppthread::mutex::lock(), and cppthread::mutex::unlock().
◆ operator=()
The guard class saves a bare pointer to the mutex it is guarding. Because of that, an assignment is not really possible and it's also not useful. Plus Effective C++ wants it this way (which is great).
- Parameters
-
[in] rhs The right hand side.
- Returns
- A reference to this object.
◆ unlock()
| void cppthread::guard::unlock | ( | bool | done = true | ) |
This function can be called any number of times. If the mutex is currently locked, the function unlocks it, otherwise nothing happens.
If necessary, you can relock the mutex using the lock() function.
This function may throw an exception if the mutex::unlock() call fails.
- Parameters
-
[in] done Whether you are done with this guard, if so, the pointer will be set to null and you can then destroy the mutex (this is the default). If instead you want to be able to re-lock the mutex, then set this parameter to false. The mutex cannot be destroyed if this parameter is set to false.
- See also
- lock()
Definition at line 142 of file guard.cpp.
References f_locked, f_mutex, and cppthread::mutex::unlock().
Referenced by ~guard().
Member Data Documentation
◆ f_locked
|
private |
◆ f_mutex
|
private |
Whenever you want to lock a part of your code so only one thread runs it at any given time, you want to use a guard. This guard makes use of a mutex that you pass to it on construction.
The guard object keeps a reference to your mutex and uses it to lock on construction and unlock on destruction. This generates a perfect safe guard around your code. Safe guard which is exception safe since it will still get unlocked when an exception occurs.
- Warning
- Note that it is not safe if you get a Unix signal. The lock will very likely still be in place if such a signal happens while within the lock.
Definition at line 56 of file guard.h.
Referenced by guard(), is_locked(), lock(), and unlock().
The documentation for this class was generated from the following files: