Cgu::Thread::Mutex Class Reference

A wrapper class for pthread mutexes. More...

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

Classes
class	Lock
	A scoped locking class for exception safe Mutex locking. More...
class	TrackLock
	A scoped locking class for exception safe Mutex locking which tracks the status of its mutex. More...

Public Member Functions
	Mutex (const Mutex &)=delete
Mutex &	operator= (const Mutex &)=delete
int	lock () noexcept
int	trylock () noexcept
int	unlock () noexcept
	Mutex ()
	~Mutex ()

Friends
class	Cond

Detailed Description

A wrapper class for pthread mutexes.

See also

Thread::Thread Thread::Mutex::Lock Thread::Mutex::TrackLock Thread::Cond Thread::RecMutex

This class can be used interchangeably with threads started with GThread and by this library, as both glib and this library use pthreads underneath on POSIX and other unix-like OSes. It can also in practice be used interchangeably with those started by C++11/14 std::thread and with std::mutex and similar objects, as in C++11/14 on unix-like OSes these facilities will be built on top of pthreads (for which purpose C++11/14 provides the std::native_handle_type type and std::thread::native_handle() function), or if they are not, they will use the same threading primitives provided by the kernel.

Mutex objects can be constructed statically as well as dynamically and there is no need to call g_thread_init() before they are constructed, even if glib < 2.32 is used. (If created as a static object in global scope, it will not be possible to catch Thread::MutexError thrown by its constructor, but if a static global mutex throws there is nothing that could be done anyway except abort, and it would show that the pthreads installation is seriously defective.)

Constructor & Destructor Documentation

Mutex() [1/2]

Cgu::Thread::Mutex::Mutex ( const Mutex &  )

delete

This class cannot be copied. The copy constructor is deleted.

Mutex() [2/2]

Cgu::Thread::Mutex::Mutex ( )

inline

Initialises the pthread mutex. It is not a cancellation point.

Exceptions

Cgu::Thread::MutexError

Throws this exception if initialization of the mutex fails. (It is often not worth checking for this, as it means either memory is exhausted or pthread has run out of other resources to create new mutexes.)

~Mutex()

Cgu::Thread::Mutex::~Mutex ( )

inline

Destroys the pthread mutex. It is not a cancellation point. It does not throw. Destroying a mutex which is currently locked or associated with an active condition variable wait results in undefined behavior.

Member Function Documentation

lock()

int Cgu::Thread::Mutex::lock ( )

inlinenoexcept

Locks the mutex and acquires ownership. Blocks if already locked until it becomes free. It is not a cancellation point. It does not throw. It is thread safe.

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 EDEADLK, which it would do if the default pthread mutex behaviour happens to return that error rather than deadlock in the case of recursive locking. Most default implementations do not do this and hence the return value is usually not worth checking for except during debugging.

operator=()

Mutex& Cgu::Thread::Mutex::operator= ( const Mutex &  )

delete

This class cannot be copied. The assignment operator is deleted.

trylock()

int Cgu::Thread::Mutex::trylock ( )

inlinenoexcept

Tries to lock the mutex and acquire ownership, but returns immediately if it is already locked with value EBUSY. It is not a cancellation point. It does not throw. It is thread safe.

Returns

0 if successful, otherwise EBUSY.

Note

With this library implementation, the only pthread error number which could be returned by this method is EBUSY.

unlock()

int Cgu::Thread::Mutex::unlock ( )

inlinenoexcept

Unlocks a locked mutex owned by the calling thread and relinquishes ownership. It is not a cancellation point. It does not throw. It must be called by the thread which owns the mutex.

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 mutex (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).

Friends And Related Function Documentation

Cond

friend class Cond

friend

---

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

• mutex.h