cosmos::Condition Class Reference

A class to represent a pthread condition. More...

#include <Condition.hxx>

Inheritance diagram for cosmos::Condition:

Public Types
enum class	WaitTimedRes { TIMED_OUT , SIGNALED }
	Strong type to express waitTimed() results. More...

Public Member Functions
	Condition (Mutex &lock)
	Create a condition coupled with the given lock.
void	wait () const
	Wait for the Condition to be signaled.
WaitTimedRes	waitTimed (const MonotonicTime ts) const
	Wait for the Condition to be signaled with timeout.
void	signal ()
	Signal and unblock one waiting thread.
void	broadcast ()
	Signal and unblock all waiting threads.
Mutex &	mutex ()

Protected Attributes
pthread_cond_t	m_pcond
Mutex &	m_lock

Detailed Description

A class to represent a pthread condition.

The current implementation only provides the most basic condition operations. Refer to the POSIX man pages for more information.

A condition allows to efficiently wait for a certain program condition to be reached. A thread typically evaluates some program state, owning a Mutex, and if there is no work to be done it invokes wait() on the Condition which atomically unlocks the Mutex and waits for another thread to signal the condition.

There are some caveats to be considered:

• A condition can only ever be used with the same Mutex it is coupled to.
• A condition can experience "spurious wakeups" i.e. it will be signaled but the program state did not actually change. Therefore you always need to check after wakeup whether the condition actually is as expected.

Definition at line 33 of file Condition.hxx.

Member Enumeration Documentation

WaitTimedRes

enum class cosmos::Condition::WaitTimedRes

strong

Strong type to express waitTimed() results.

Definition at line 41 of file Condition.hxx.

                                {
                TIMED_OUT,
                SIGNALED
        };

Constructor & Destructor Documentation

Condition()

cosmos::Condition::Condition ( Mutex & lock )

explicit

Create a condition coupled with the given lock.

The given Mutex will be associated with the Condition for the complete lifetime of the object. You need to make sure that lock is never destroyed before the associated Condition object is destroyed.

Definition at line 7 of file Condition.cxx.

                                :
                m_lock{lock} {
        int res = -1;
 
        pthread_condattr_t attr;
 
        res = pthread_condattr_init(&attr);
 
        if (auto err = Errno{res}; err != Errno::NO_ERROR) {
                cosmos_throw (ApiError("pthread_condattr_init()", err));
        }
 
        try {
                /*
                 * we need the monotonic clock for time based wait
                 * operations on the condition, it's the most robust
                 * clock available
                 */
                res = pthread_condattr_setclock(&attr, to_integral(ClockType::MONOTONIC));
 
                if (auto err = Errno{res}; err != Errno::NO_ERROR) {
                        cosmos_throw (ApiError("pthread_condattr_setclock()", err));
                }
 
                res = ::pthread_cond_init(&m_pcond, &attr);
 
                if (auto err = Errno{res}; err != Errno::NO_ERROR) {
                        cosmos_throw (ApiError("pthread_cond_init()", err));
                }
        } catch(...) {
                (void)pthread_condattr_destroy(&attr);
                throw;
        }
}

~Condition()

cosmos::Condition::~Condition ( )

inline

Definition at line 57 of file Condition.hxx.

                     {
                const auto destroy_res = ::pthread_cond_destroy(&m_pcond);
 
                assert (!destroy_res);
                (void)destroy_res;
        }

Member Function Documentation

broadcast()

void cosmos::Condition::broadcast ( )

inline

Signal and unblock all waiting threads.

All threads currently waiting for a signal on the condition will be woken up. Keep in mind that each thread will contend for acquiring the mutex at wakeup and thus a certain serialization will take place until all threads evaluated the new program state and release the mutex again.

Definition at line 124 of file Condition.hxx.

                         {
                auto res = ::pthread_cond_broadcast(&m_pcond);
 
                if (auto err = Errno{res}; err != Errno::NO_ERROR) {
                        cosmos_throw (ApiError("pthread_cond_broadcast()", err));
                }
        }

mutex()

Mutex & cosmos::Condition::mutex ( )

inline

Definition at line 132 of file Condition.hxx.

{ return m_lock; }

signal()

void cosmos::Condition::signal ( )

inline

Signal and unblock one waiting thread.

This call will unblock at most one thread waiting for a signal on the condition. If multiple threads are waiting for a signal then the rest of the thread will not be woken up.

This call will not block the caller. If not thread is currently waiting for a signal then nothing happens.

Definition at line 108 of file Condition.hxx.

                      {
                auto res = ::pthread_cond_signal(&m_pcond);
 
                if (auto err = Errno{res}; err != Errno::NO_ERROR) {
                        cosmos_throw (ApiError("pthread_cond_signal()", err));
                }
        }

wait()

void cosmos::Condition::wait ( ) const

inline

Wait for the Condition to be signaled.

The associated Mutex must already be locked at entry, otherwise undefined behaviour is the result.

Upon return the Mutex will again be owned by the caller.

Definition at line 71 of file Condition.hxx.

                          {
                auto res = ::pthread_cond_wait(&m_pcond, &(m_lock.m_pmutex));
 
                if (auto err = Errno{res}; err != Errno::NO_ERROR) {
                        cosmos_throw (ApiError("pthread_cond_wait()", Errno{err}));
                }
        }

waitTimed()

WaitTimedRes cosmos::Condition::waitTimed ( const MonotonicTime ts ) const

inline

Wait for the Condition to be signaled with timeout.

This is like wait() but waits at most until the given absolute time has been reached.

Upon return the Mutex will again be owned by the caller, regardless of whether the condition was signaled or a timeout occurred.

Returns

Whether a timeout or a signal occurred.

Definition at line 89 of file Condition.hxx.

                                                             {
                auto res = ::pthread_cond_timedwait(&m_pcond, &(m_lock.m_pmutex), &ts);
 
                switch(Errno{res}) {
                default: cosmos_throw (ApiError("pthread_cond_timedwait()", Errno{res})); return WaitTimedRes::TIMED_OUT; /* just to silence compiler warning */
                case Errno::NO_ERROR: return WaitTimedRes::SIGNALED;
                case Errno::TIMEDOUT: return WaitTimedRes::TIMED_OUT;
                }
        }

Member Data Documentation

m_lock

Mutex& cosmos::Condition::m_lock

protected

Definition at line 138 of file Condition.hxx.

m_pcond

pthread_cond_t cosmos::Condition::m_pcond

mutableprotected

Definition at line 137 of file Condition.hxx.

---

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

• include/thread/Condition.hxx
• src/thread/Condition.cxx