Cgu::Thread::Cond Class Reference

A wrapper class for pthread condition variables. More...

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

Public Member Functions
int	signal ()
int	broadcast ()
int	wait (Mutex &mutex)
int	wait (Mutex::Lock &lock)
int	wait (Mutex::TrackLock &lock)
int	timed_wait (Mutex &mutex, const timespec &abs_time)
int	timed_wait (Mutex::Lock &lock, const timespec &abs_time)
int	timed_wait (Mutex::TrackLock &lock, const timespec &abs_time)
	Cond ()
	~Cond (void)

Static Public Member Functions
static void	get_abs_time (timespec &ts, unsigned int millisec)
static bool	have_monotonic_clock ()

Detailed Description

A wrapper class for pthread condition variables.

See also

Thread::Thread Thread::Mutex Thread::Mutex::Lock Thread::Mutex::TrackLock

Constructor & Destructor Documentation

Cond()

Cgu::Thread::Cond::Cond

(

)

Initialises the pthread condition variable. It is not a cancellation point.

Exceptions

Cgu::Thread::CondError

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

Note

If the system supports monotonic clocks (and this library is not being cross-compiled onto a different architecture), then condition variables will use a system monotonic clock in Cond::timed_wait() and Cond::get_abs_time(). This can be tested at run time by calling Cond::have_monotonic_clock().

~Cond()

Cgu::Thread::Cond::~Cond ( void  )

inline

Destroys the pthread condition variable. It is not a cancellation point. The destructor does not throw. Destroying a condition variable on which another thread is currently blocked results in undefined behavior.

Member Function Documentation

broadcast()

int Cgu::Thread::Cond::broadcast ( )

inline

Unblocks all threads waiting on this condition variable, which acquire the mutex in an order determined by the scheduling policy. Can be called by any thread. It is not a cancellation point. Does not throw.

Returns

0 if successful, otherwise the pthread error number.

Note

With this library implementation, no pthread error should arise so there is no need to check the return value.

get_abs_time()

static void Cgu::Thread::Cond::get_abs_time ( timespec &  ts, unsigned int  millisec  )

static

This is a utility function that inserts into a timespec structure the current time plus a given number of milliseconds ahead, which can be applied to a call to Cond::timed_wait(). It does not throw. It is thread-safe.

Parameters

ts	A timespec object into which the result of current time + millisec will be placed.
millisec	The number of milliseconds ahead of current time to which the timespec object will be set.

Note

If the system supports monotonic clocks (and this library is not being cross-compiled onto a different architecture), then condition variables will use a system monotonic clock in this method and Cond::timed_wait(). This can be tested at run time with Cond::have_monotonic_clock().

have_monotonic_clock()

static bool Cgu::Thread::Cond::have_monotonic_clock ( )

static

Indicates whether the library has been compiled with support for monotonic clocks in Cond::timed_wait(). Most recent linux and BSD distributions will support them, and this function would normally return true unless the library has been cross-compiled from one platform to a different platform. This function can be tested at program initialization, and if they are not supported a warning can be given to the user about the deficiences of using the system clock for timed events. It does not throw. It is thread safe.

Returns

true if the library has been compiled with support for monotonic clocks in Cond::timed_wait(), otherwise false.

Since 1.2.0

signal()

int Cgu::Thread::Cond::signal ( )

inline

Unblock at least one thread waiting on this condition variable. Can be called by any thread. It is not a cancellation point. Does not throw.

Returns

0 if successful, otherwise the pthread error number.

Note

With this library implementation, no pthread error should arise so there is no need to check the return value.

timed_wait() [1/3]

int Cgu::Thread::Cond::timed_wait ( Mutex &  mutex, const timespec &  abs_time  )

inline

Waits on this condition variable until awoken (in which case it re-acquires the mutex), or until the timeout expires (in which case it re-acquires the mutex and returns with ETIMEDOUT). It must be called by the thread which owns the mutex. Re-acquires the mutex when awoken or timing out. It is a cancellation point. This method is cancellation safe even if the stack does not unwind on cancellation (but if the stack does not unwind some other way of destroying this object on cancellation is required, such as by having it allocated on freestore and deleted in a cancellation clean-up handler). This method does not throw.

Parameters

mutex	The locked mutex associated with the wait which is re-acquired on being awoken or timing out.
abs_time	The time at which the wait will unblock if not previously awoken. A suitable value can be obtained by calling the get_abs_time() function.

Returns

0 after being awoken on waiting, otherwise ETIMEDOUT or other pthread error number.

Note

1. With this library implementation, apart from ETIMEDOUT, the only pthread error numbers which could be returned are EINVAL (if the mutex argument is not a valid mutex or the abs_time argument does not comprise a valid timespec struct) or EPERM (if the thread calling this method does not own the mutex).

2. pthread condition variables can, as a matter of design, awake spontaneously (and Cond::signal() may awaken more than one thread). Therefore the relevant condition should be tested in a while loop and not in an if block. 0 will be returned on a spontaneous awakening.

3. If the system supports monotonic clocks (and this library is not being cross-compiled onto a different architecture), then condition variables will use a monotonic clock in Cond::timed_wait() and Cond::get_abs_time(). This can be tested at run time with Cond::have_monotonic_clock().

timed_wait() [2/3]

int Cgu::Thread::Cond::timed_wait ( Mutex::Lock &  lock, const timespec &  abs_time  )

inline

Does the same as Cond::timed_wait(Mutex&, const timespec&), except that as a convenience it will take a Mutex::Lock object handling the Mutex object as an alternative to passing the Mutex object itself.

timed_wait() [3/3]

int Cgu::Thread::Cond::timed_wait ( Mutex::TrackLock &  lock, const timespec &  abs_time  )

inline

Does the same as Cond::timed_wait(Mutex&, const timespec&), except that as a convenience it will take a Mutex::TrackLock object handling the Mutex object as an alternative to passing the Mutex object itself.

Since 1.2.1

wait() [1/3]

int Cgu::Thread::Cond::wait ( Mutex &  mutex )

inline

Waits on this condition variable until awoken. It must be called by the thread which owns the mutex. Re-acquires the mutex when awoken. It is a cancellation point. This method is cancellation safe even if the stack does not unwind on cancellation (but if the stack does not unwind some other way of destroying this object on cancellation is required, such as by having it allocated on freestore and deleted in a cancellation clean-up handler). This method does not throw.

Parameters

mutex

The locked mutex associated with the wait which is re-acquired on being awoken.

Returns

0 after being awoken on waiting, otherwise the pthread error number.

Note

1. pthread condition variables can, as a matter of design, awake spontaneously (and Cond::signal() may awaken more than one thread). Therefore the relevant condition should be tested in a while loop and not in an if block. 0 will be returned on a spontaneous awakening.

2. With this library implementation, the only pthread error numbers which could be returned are EINVAL (if the mutex argument is not a valid mutex) or EPERM (if the thread calling this method does not own the mutex).

wait() [2/3]

int Cgu::Thread::Cond::wait ( Mutex::Lock &  lock )

inline

Does the same as Cond::wait(Mutex&), except that as a convenience it will take a Mutex::Lock object handling the Mutex object as an alternative to passing the Mutex object itself.

wait() [3/3]

int Cgu::Thread::Cond::wait ( Mutex::TrackLock &  lock )

inline

Does the same as Cond::wait(Mutex&), except that as a convenience it will take a Mutex::TrackLock object handling the Mutex object as an alternative to passing the Mutex object itself.

Since 1.2.1

---

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

• mutex.h