A scoped locking class for exception safe RecMutex locking which tracks the status of its mutex.
More...
#include <c++-gtk-utils/mutex.h>
A scoped locking class for exception safe RecMutex locking which tracks the status of its mutex.
- See also
- Thread::RecMutex Thread::RecMutex::Lock Thread::Thread
This class is similar to a RecMutex::Lock object, except that it tracks whether the mutex it manages is locked by the thread creating the RecMutex::TrackLock object with respect to the particular locking operation to be governed by the object (provided that, while the RecMutex::TrackLock object exists, the thread creating it only accesses the mutex with respect that particular operation through that object). This enables RecMutex::TrackLock::unlock() to be used without it being followed later by a call to RecMutex::TrackLock::lock() or a successful call to RecMutex::TrackLock::trylock(), and also permits locking to be deferred until after construction of the lock object. Note that only one thread may call the methods of any one RecMutex::TrackLock object, including causing its destructor to be invoked.
◆ TrackLock() [1/5]
This class cannot be copied. The copy constructor is deleted.
◆ TrackLock() [2/5]
| Cgu::Thread::RecMutex::TrackLock::TrackLock |
( |
RecMutex & |
mutex_ | ) |
|
|
inline |
This constructor locks the mutex passed to it. See RecMutex::lock() for a description of the outcomes. It is not a cancellation point. It does not throw.
- Parameters
-
| mutex_ | The mutex to be locked. |
- Exceptions
-
| Cgu::Thread::RecMutexError | Throws this exception if initialization of the mutex fails because the maximum recursive lock count for the particular mutex in question has been reached. Usually this number is at or around INT_MAX so it is not usually useful to check for it except during debugging. |
◆ TrackLock() [3/5]
| Cgu::Thread::RecMutex::TrackLock::TrackLock |
( |
RecMutex & |
mutex_, |
|
|
Locked |
tag |
|
) |
| |
|
inline |
This constructor takes an already locked mutex (say as a result of RecMutex::trylock()), and takes ownership of it. It is not a cancellation point. It does not throw.
- Parameters
-
| mutex_ | The mutex to be managed by this object. |
| tag | Pass the Cgu::Thread::locked enum tag to this parameter. |
◆ TrackLock() [4/5]
This constructor defers locking of the mutex (and so taking ownership of it) until an explicit call to lock() or trylock() is made. It is not a cancellation point. It does not throw.
- Parameters
-
| mutex_ | The mutex to be managed by this object. |
| tag | Pass the Cgu::Thread::defer enum tag to this parameter. |
◆ TrackLock() [5/5]
| Cgu::Thread::RecMutex::TrackLock::TrackLock |
( |
| ) |
|
|
delete |
This class requires initialisation with a RecMutex. The default constructor is deleted.
◆ ~TrackLock()
| Cgu::Thread::RecMutex::TrackLock::~TrackLock |
( |
| ) |
|
|
inline |
The destructor unlocks the managed mutex if it is owned by this RecMutex::TrackLock object. See RecMutex::unlock() for a description of the outcomes if it is so owned. It is not a cancellation point. It does not throw.
◆ is_owner()
| bool Cgu::Thread::RecMutex::TrackLock::is_owner |
( |
| ) |
const |
|
inline |
Indicates whether the mutex managed by this Mutex::TrackLock object is locked by it (whether originally or recursively) and so owned by it. It does not throw.
- Returns
- true if the mutex is owned by this object, otherwise false.
◆ lock()
| int Cgu::Thread::RecMutex::TrackLock::lock |
( |
| ) |
|
|
inline |
This calls RecMutex::lock(), and so locks the mutex and acquires ownership. It blocks if the mutex is already locked until the mutex becomes free, unless the calling thread already holds the lock, in which case it increments the lock count and returns immediately. This method should normally only be called if a previous call has been made to RecMutex::TrackLock::unlock() or this RecMutex::TrackLock object has been constructed with the Thread::defer enum tag. It is not a cancellation point. It does not throw.
- Returns
- 0 if successful, otherwise the pthread mutex error number.
- Note
- With this library implementation, the only pthread error number which could be returned by this method is EAGAIN, which it would do if the maximum recursive lock count for the particular mutex in question has been reached. Usually this number is at or around INT_MAX and hence the return value is usually not worth checking for except during debugging.
◆ operator=()
This class cannot be copied. The assignment operator is deleted.
◆ trylock()
| int Cgu::Thread::RecMutex::TrackLock::trylock |
( |
| ) |
|
|
inline |
This calls RecMutex::trylock(), and so tries to lock the mutex and acquire ownership, but returns immediately if it is already locked with value EBUSY unless the calling thread already holds the lock, in which case it returns normally and increments the lock count. This method should normally only be called if a previous call has been made to RecMutex::TrackLock::unlock() or this RecMutex::TrackLock object has been constructed with the Thread::defer enum tag. It is not a cancellation point. It does not throw.
- Returns
- 0 if successful, otherwise EBUSY or other pthread mutex error number.
- Note
- With this library implementation, apart from EBUSY, the only other pthread error number which could be returned by this method is EAGAIN, which it would do if the maximum recursive lock count for the particular mutex in question has been reached. Usually this number is at or around INT_MAX and hence an EAGAIN error return value is usually not worth checking for except during debugging.
◆ unlock()
| int Cgu::Thread::RecMutex::TrackLock::unlock |
( |
| ) |
|
|
inline |
This calls RecMutex::unlock(), and so unlocks a locked mutex owned by the calling thread, or decrements the lock count (if it has been recursively locked). It will cause is_owner() to return false unless a subsequent call is made to lock() or a subsequent successful call is made to trylock(). It is not a cancellation point. It does not throw.
- Returns
- 0 if successful, otherwise the pthread mutex error number.
- Note
- With this library implementation, the only pthread error number which could be returned by this method is EPERM because the calling thread does not own the particular mutex in question (however POSIX does not require that return value in that case and hence the return value is usually not worth checking for except during debugging).
The documentation for this class was generated from the following file:
