A simple wrapper class that makes use of ::pthread_cond_t easier in a C++ world. More...

#include <carma/util/PthreadCond.h>

Public Member Functions
void	Broadcast ()
	Wake any waiters. More...

const ::pthread_cond_t &	InternalPthreadCond () const
	Obtain a reference to the internal ::pthread_cond_t. More...

::pthread_cond_t &	InternalPthreadCond ()
	Obtain a reference to the internal ::pthread_cond_t. More...

	PthreadCond ()
	Default construct a cond with the CARMA defaults. More...

	PthreadCond (const PthreadCondAttr &attr)
	Construct a cond with the given attributes. More...

	PthreadCond (const ::pthread_condattr_t &attr)
	Construct a cond with the given attributes. More...

void	Signal ()
	Wake one of any waiters. More...

bool	TimedWait (::pthread_mutex_t &m, const struct::timespec &abstime)
	Wait until waken or timed out. More...

bool	TimedWait (PthreadMutex &m, const struct::timespec &abstime)
	Wait until waken or timed out. More...

void	Wait (::pthread_mutex_t &m)
	Wait until waken. More...

void	Wait (PthreadMutex &m)
	Wait until waked. More...

Detailed Description

A simple wrapper class that makes use of ::pthread_cond_t easier in a C++ world.

Condition variables (and ::pthread_cond_t, the POSIX realization of them) are a bit too complicated and tricky to explain here. Look them up in a book on POSIX/Pthread programming if you need more information.

Definition at line 43 of file PthreadCond.h.

Constructor & Destructor Documentation

carma::util::PthreadCond::PthreadCond ( )

explicit

Default construct a cond with the CARMA defaults.

Any internal errors will throw an exception.

carma::util::PthreadCond::PthreadCond ( const PthreadCondAttr & attr )

explicit

Construct a cond with the given attributes.

Any internal errors will throw an exception.

carma::util::PthreadCond::PthreadCond ( const ::pthread_condattr_t & attr )

explicit

Construct a cond with the given attributes.

Any internal errors will throw an exception.

Member Function Documentation

void carma::util::PthreadCond::Broadcast ( )

Wake any waiters.

Wake all threads waiting on this instance at the time of the call.

Warning: While it is legal to Broadcast without holding the associated Mutex, it is a mistake to assume that all waiting threads are blocked on the condition, even if it seems this is the only possible option. In reality, when the lock is not held by the broadcaster, you are at the mercy of the scheduler which may have scheduled your waiting thread out prior to the atomic blocking on the condition. In this case, your waiter will never receive the broadcast. This can be especially problematic when tearing down threads where the assumption can easily lead to deadlock. If you need predictable scheduling, you should lock the associated mutex before broadcasting.

const ::pthread_cond_t & carma::util::PthreadCond::InternalPthreadCond ( ) const

Obtain a reference to the internal ::pthread_cond_t.

Warning: Use this with care. Certainly do not go off and call something like ::pthread_cond_destroy on the return value. If you don't know what you are doing with POSIX condition variables then think twice before using this method.

Returns: a reference to the internal ::pthread_cond_t

Definition at line 202 of file PthreadCond.h.

pthread_cond_t & carma::util::PthreadCond::InternalPthreadCond ( )

Obtain a reference to the internal ::pthread_cond_t.

Warning: Use this with care. Certainly do not go off and call something like ::pthread_cond_destroy on the return value. If you don't know what you are doing with POSIX condition variables then think twice before using this method.

Returns: a reference to the internal ::pthread_cond_t

Definition at line 209 of file PthreadCond.h.

void carma::util::PthreadCond::Signal ( )

Wake one of any waiters.

If any threads are waiting on this instance at the time of the call then wake one of them.

Warning: While it is legal to Signal without holding the associated Mutex, it is a mistake to assume that any waiting thread is blocked on the condition, even if it seems this is the only possible option. In reality, when the lock is not held by the signaler, you are at the mercy of the scheduler which may have scheduled your waiting thread out prior to the atomic blocking on the condition. In this case, your waiter will never receive the signal. This can be especially problematic when tearing down threads where the assumption can easily lead to deadlock. If you need predictable scheduling, you should lock the associated mutex before signalling.

bool carma::util::PthreadCond::TimedWait	(	::pthread_mutex_t &	m,
		const struct::timespec &	abstime
	)

Wait until waken or timed out.

Atomically release the given mutex and wait the caller's thread on this instance until either waked or abstime has arrived in absolute time. In all cases the mutex will be reacquired (unless the given mutex is invalid/errors in some way). Spurious wakes may occur and hence the condition being waited for should be rechecked and rewaited if needed.

Returns: true if waked and false if timed out

bool carma::util::PthreadCond::TimedWait	(	PthreadMutex &	m,
		const struct::timespec &	abstime
	)

Wait until waken or timed out.

Atomically release the given mutex and wait the caller's thread on this instance until either waked or abstime has arrived in absolute time. In all cases the mutex will be reacquired (unless the given mutex is invalid/errors in some way). Spurious wakes may occur and hence the condition being waited for should be rechecked and rewaited if needed.

Returns: true if waked and false if timed out

Definition at line 194 of file PthreadCond.h.

void carma::util::PthreadCond::Wait ( ::pthread_mutex_t & m )

Wait until waken.

Atomically release the given mutex and wait the caller's thread on this instance until waked and the mutex has been reacquired (unless the given mutex is invalid/errors in some way). Spurious wakes may occur and hence the condition being waited for should be rechecked and rewaited if needed.

void carma::util::PthreadCond::Wait ( PthreadMutex & m )

Wait until waked.

Atomically release the given mutex and wait the caller's thread on this instance until waked and the mutex has been reacquired (unless the given mutex is invalid/errors in some way). Spurious wakes may occur and hence the condition being waited for should be rechecked and rewaited if needed.

Definition at line 187 of file PthreadCond.h.

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

carma/util/PthreadCond.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation