Encapsulation for a condition variable. More...

#include <sync.h>

Inheritance diagram for isc::util::thread::CondVar:

Classes
class	Impl

Public Member Functions
	CondVar ()
	Constructor. More...

	~CondVar ()
	Destructor. More...

void	signal ()
	Unblock a thread waiting for the condition variable. More...

void	wait (Mutex &mutex)
	Wait on the condition variable. More...

Detailed Description

Encapsulation for a condition variable.

This class provides a simple encapsulation of condition variable for inter-thread synchronization. It has similar but simplified interface as that for pthread_cond_ variants.

It uses the Mutex class object for the mutex used with the condition variable. Since for normal applications the internal Mutex::Locker class is the only available interface to acquire a lock, sample code for waiting on a condition variable would look like this:

CondVar cond;
Mutex mutex;
{
    Mutex::Locker locker(mutex);
    while (some_condition) {
        cond.wait(mutex);
    }
    // do something under the protection of locker
}   // lock is released here

Note that mutex passed to the wait() method must be the same one used to construct the locker.

Right now there is no equivalent to pthread_cond_broadcast() or pthread_cond_timedwait() in this class, because this class was meant for internal development of BIND 10 and we don't need these at the moment. If and when we need these interfaces they can be added at that point. Also, Kea likely to not use threading model, so the usefulness of this class is uncertain.

Note: This class is defined as a friend class of Mutex and directly refers to and modifies private internals of the Mutex class. It breaks the assumption that the lock is only acquired or released via the Locker class and breaks other integrity assumption on Mutex, thereby making it more fragile, but we couldn't find other way to implement a safe and still simple realization of condition variables. So, this is a kind of compromise. If this class is needed to be extended, first consider a way to use public interfaces of Mutex; do not easily rely on the fact that this class is a friend of it.

Definition at line 205 of file sync.h.

Constructor & Destructor Documentation

◆ CondVar()

isc::util::thread::CondVar::CondVar ( )

Constructor.

Exceptions

std::bad_alloc	memory allocation failure
isc::Unexpected	other unexpected shortage of system resource

Definition at line 217 of file sync.cc.

◆ ~CondVar()

isc::util::thread::CondVar::~CondVar ( )

Destructor.

An object of this class must not be destroyed while some thread is waiting on it. If this condition isn't met the destructor will terminate the program.

Definition at line 220 of file sync.cc.

Member Function Documentation

◆ signal()

void isc::util::thread::CondVar::signal ( )

Unblock a thread waiting for the condition variable.

This method wakes one of other threads (if any) waiting on this object via the wait() call.

This method never throws; if some unexpected low level error happens it terminates the program.

Definition at line 242 of file sync.cc.

References isc::util::thread::CondVar::Impl::cond_.

Referenced by isc::test::ThreadedTest::doSignal().

◆ wait()

void isc::util::thread::CondVar::wait ( Mutex & mutex )

Wait on the condition variable.

This method works like pthread_cond_wait(). For mutex it takes an Mutex class object. A lock for the mutex must have been acquired. If this condition isn't met, it can throw an exception (in the debug mode build) or result in undefined behavior.

The lock will be automatically released within this method, and will be re-acquired on the exit of this method.

Exceptions

isc::InvalidOperation	mutex isn't locked
isc::BadValue	mutex is not a valid `Mutex` object

Parameters

mutex A Mutex object to be released on wait().

Definition at line 225 of file sync.cc.

References isc::util::thread::CondVar::Impl::cond_, and isc_throw.

Referenced by isc::test::ThreadedTest::doWait().

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

Classes