Cgu::Thread::RWLock::ReaderLock Class Reference

A scoped locking class for exception safe RWLock read locking. More...

#include <c++-gtk-utils/rw_lock.h>

Public Member Functions
int	lock ()
int	trylock ()
int	unlock ()
	ReaderLock (RWLock &rw_lock_)
	ReaderLock (RWLock &rw_lock_, Locked tag)
	~ReaderLock ()

Detailed Description

A scoped locking class for exception safe RWLock read locking.

See also

Thread::RWLock Thread::RWLock::ReaderTrackLock Thread::RWLock::WriterLock Thread::RWLock::WriterTrackLock Thread::Thread

Constructor & Destructor Documentation

ReaderLock() [1/2]

Cgu::Thread::RWLock::ReaderLock::ReaderLock ( 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.

Since 1.2.1

ReaderLock() [2/2]

Cgu::Thread::RWLock::ReaderLock::ReaderLock ( RWLock &  rw_lock_, Locked  tag  )

inline

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.

Since 1.2.1

~ReaderLock()

Cgu::Thread::RWLock::ReaderLock::~ReaderLock ( )

inline

The destructor unlocks the read-write lock which is managed for reading. It is not a cancellation point. It does not throw.

Since 1.2.1

Member Function Documentation

lock()

int Cgu::Thread::RWLock::ReaderLock::lock ( )

inline

Calls RWLock::reader_lock(), and so relocks the read-write lock for reading. 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::ReaderLock::unlock() (that is, where the thread owning the RWLock::ReaderLock object has temporarily allowed another thread to take the read-write lock concerned for writing if another thread does not hold a read lock or the read-write lock has not been recursively locked for reading). 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.

See also

RWLock::ReaderTrackLock

Since 1.2.1

trylock()

int Cgu::Thread::RWLock::ReaderLock::trylock ( )

inline

Calls RWLock::reader_trylock(), and so tries to relock the read-write lock for reading, 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::ReaderLock::unlock() (that is, where the thread owning the RWLock::ReaderLock object has temporarily allowed another thread to take the read-write lock concerned for writing if another thread does not hold a read lock or the read-write lock has not been recursively locked for reading). 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.

See also

RWLock::ReaderTrackLock

Since 1.2.1

unlock()

int Cgu::Thread::RWLock::ReaderLock::unlock ( )

inline

Calls RWLock::unlock(), and so unlocks a locked read-write lock held by the calling thread for reading (so temporarily allowing another thread to take the read-write lock for writing should no other read lock be held or the particular implementation provides writer priority). This method should normally only be called if it is to be followed by a call to RWLock::ReaderLock::lock() or a successful call to RWLock::ReaderLock::trylock() before the RWLock::ReaderLock object concerned goes out of scope (otherwise RWLock::ReaderLock's destructor will attempt to unlock an already unlocked read-write lock or a read-write lock of which another thread holds a lock - RWLock::ReaderLock objects do not maintain state). See RWLock::ReaderTrackLock::unlock() for a safe version of this method. 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).

See also

RWLock::ReaderTrackLock

Since 1.2.1

---

The documentation for this class was generated from the following file:

• rw_lock.h