A scoped locking class for exception safe RWLock read locking which tracks the status of its read-write lock.
More...
#include <c++-gtk-utils/rw_lock.h>
A scoped locking class for exception safe RWLock read locking which tracks the status of its read-write lock.
- See also
- Thread::RWLock Thread::RWLock::ReaderLock Thread::RWLock::WriterLock Thread::RWLock::WriterTrackLock Thread::Thread
This class is similar to a RWLock::ReaderLock object, except that it tracks whether the read-write lock it manages is locked for reading by the thread creating the RWLock::ReaderTrackLock object with respect to the particular read-locking operation to be governed by the object (provided that, while the RWLock::ReaderTrackLock object exists, the thread creating it only accesses the managed read-write lock with respect that particular operation through that object). This enables RWLock::ReaderTrackLock::unlock() to be used without it being followed later by a call to RWLock::ReaderTrackLock::lock() or a successful call to RWLock::ReaderTrackLock::trylock(), and also permits locking to be deferred until after construction of the RWLock::ReaderTrackLock object. Note that only one thread may call the methods of any one RWLock::ReaderTrackLock object, including causing its destructor to be invoked.
◆ ReaderTrackLock() [1/5]
This class cannot be copied. The copy constructor is deleted.
◆ ReaderTrackLock() [2/5]
| Cgu::Thread::RWLock::ReaderTrackLock::ReaderTrackLock |
( |
RWLock & |
rw_lock_ | ) |
|
|
inline |
This constructor locks for reading the read-write lock passed to it. It is not a cancellation point.
- Parameters
-
| rw_lock_ | The read-write lock to be locked for reading. |
- Exceptions
-
| Cgu::Thread::RWLockError | Throws this exception if initialization of the read-write lock fails because the maximum number of read locks for the particular read-write lock in question has been reached. Usually this number is at or around INT_MAX so it is not usually useful to check for the exception except during debugging. This exception may also be thrown if the thread constructing this object already holds a write lock on the read-write lock in question. It will do this if the default pthread implementation returns EDEADLK in such a case instead of deadlocking. However as most default implementations will simply deadlock in such circumstances, it is usually not worth checking for this either except during debugging. |
◆ ReaderTrackLock() [3/5]
| Cgu::Thread::RWLock::ReaderTrackLock::ReaderTrackLock |
( |
RWLock & |
rw_lock_, |
|
|
Locked |
tag |
|
) |
| |
|
inlinenoexcept |
This constructor takes a read-write lock already locked for reading (say as a result of RWLock::reader_trylock()), and takes management of that read lock operation. It is not a cancellation point. It does not throw.
- Parameters
-
| rw_lock_ | The read-write lock to be managed for reading by this object. |
| tag | Pass the Cgu::Thread::locked enum tag to this parameter. |
◆ ReaderTrackLock() [4/5]
| Cgu::Thread::RWLock::ReaderTrackLock::ReaderTrackLock |
( |
RWLock & |
rw_lock_, |
|
|
DeferLock |
tag |
|
) |
| |
|
inlinenoexcept |
This constructor defers locking of the read-write lock for reading until an explicit call to lock() or trylock() is made. It is not a cancellation point. It does not throw.
- Parameters
-
| rw_lock_ | The read-write lock to be managed for reading by this object. |
| tag | Pass the Cgu::Thread::defer enum tag to this parameter. |
◆ ReaderTrackLock() [5/5]
| Cgu::Thread::RWLock::ReaderTrackLock::ReaderTrackLock |
( |
| ) |
|
|
delete |
This class requires initialisation with a RWLock. The default constructor is deleted.
◆ ~ReaderTrackLock()
| Cgu::Thread::RWLock::ReaderTrackLock::~ReaderTrackLock |
( |
| ) |
|
|
inline |
The destructor unlocks the read-write lock which is managed for reading if it is owned by this RWLock::ReaderTrackLock object (whether solely or with other read locks). It is not a cancellation point. It does not throw.
◆ is_owner()
| bool Cgu::Thread::RWLock::ReaderTrackLock::is_owner |
( |
| ) |
const |
|
inlinenoexcept |
Indicates whether the read-write lock managed by this RWLock::ReaderTrackLock object is locked for reading by it and so owned by it (whether solely or with other read locks). It does not throw.
- Returns
- true if the read-write lock is owned by this object, otherwise false.
◆ lock()
| int Cgu::Thread::RWLock::ReaderTrackLock::lock |
( |
| ) |
|
|
inlinenoexcept |
This calls RWLock::reader_lock(), and so locks the read-write lock for reading and acquires ownership (which may be shared with other read locks). It blocks if the read-write lock is already locked for writing until it becomes free. This method should normally only be called if a previous call has been made to RWLock::ReaderTrackLock::unlock() or this RWLock::ReaderTrackLock 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 read-write lock error number.
- Note
- With this library implementation, the only pthread error numbers which could be returned by this method are EDEADLK and EAGAIN. EDEADLK would be returned if the default pthread reader lock behaviour happens to return that error rather than deadlock where the thread calling this method already holds a write lock on the particular read-write lock in question. Most default implementations do not do this (they just deadlock) and hence the return value is usually not worth checking for except during debugging. EAGAIN would be returned if the maximum number of read locks for the read-write lock in question has been reached. Usually this number is at or around INT_MAX so it is also not usually useful to check for it except during debugging.
◆ operator=()
This class cannot be copied. The assignment operator is deleted.
◆ trylock()
| int Cgu::Thread::RWLock::ReaderTrackLock::trylock |
( |
| ) |
|
|
inlinenoexcept |
This calls RWLock::reader_trylock(), and so tries to lock the read-write lock for reading and acquire ownership (which may be shared with other read locks), but returns immediately with value EBUSY if it is already locked for writing. This method should normally only be called if a previous call has been made to RWLock::ReaderTrackLock::unlock() or this RWLock::ReaderTrackLock 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 read-write lock 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 would be returned if the maximum number of read locks for the particular read-write lock 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.
◆ unlock()
| int Cgu::Thread::RWLock::ReaderTrackLock::unlock |
( |
| ) |
|
|
inlinenoexcept |
This calls RWLock::unlock(), and so unlocks a locked read-write lock held by the calling thread for reading and relinquishes ownership (whether it was sole or shared with other read locks). 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 read-write lock 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 hold a lock on the particular read-write lock 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:
