Cgu::Thread::RecMutex::Lock Class Reference

A scoped locking class for exception safe RecMutex locking. More...

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

Public Member Functions
int	lock ()
int	trylock ()
int	unlock ()
	Lock (RecMutex &mutex_)
	Lock (RecMutex &mutex_, Locked tag)
	~Lock ()

Detailed Description

A scoped locking class for exception safe RecMutex locking.

See also

Thread::RecMutex Thread::RecMutex::TrackLock Thread::Thread

Constructor & Destructor Documentation

Lock() [1/2]

Cgu::Thread::RecMutex::Lock::Lock ( 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.

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.

Lock() [2/2]

Cgu::Thread::RecMutex::Lock::Lock ( 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.

~Lock()

Cgu::Thread::RecMutex::Lock::~Lock ( )

inline

The destructor unlocks the owned mutex. See RecMutex::unlock() for a description of the outcomes. It is not a cancellation point. It does not throw.

Member Function Documentation

lock()

int Cgu::Thread::RecMutex::Lock::lock ( )

inline

This calls RecMutex::lock(), and so locks the mutex and reacquires 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::Lock::unlock() (that is, where the thread owning the RecMutex::Lock object has temporarily allowed another thread to take the mutex concerned if it is not recursively locked). 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.

See also

RecMutex::TrackLock.

trylock()

int Cgu::Thread::RecMutex::Lock::trylock ( )

inline

This calls RecMutex::trylock(), and so tries to lock the mutex and reacquire 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::Lock::unlock() (that is, where the thread owning the RecMutex::Lock object has temporarily allowed another thread to take the mutex concerned if it is not recursively locked). 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.

See also

RecMutex::TrackLock.

unlock()

int Cgu::Thread::RecMutex::Lock::unlock ( )

inline

This calls RecMutex::unlock() and so unlocks a locked mutex owned by the calling thread, so temporarily allowing another thread to take the mutex if the mutex has not been recursively locked, or if it has been recursively locked decrements the lock count, so temporarily relinquishing ownership. This method should normally only be called if it is to be followed by a call to RecMutex::Lock::lock() or a successful call to RecMutex::Lock::trylock() before the RecMutex::Lock object concerned goes out of scope (otherwise RecMutex::Lock's destructor will attempt to decrement the lock count of a mutex which already has a lock count of 0 or which another thread has by then taken ownership or leave the lock count in an unbalanced condition - RecMutex::Lock objects do not maintain state). See RecMutex::TrackLock::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 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).

See also

RecMutex::TrackLock.

---

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

• mutex.h