Fawkes API  Fawkes Development Version
fawkes::WaitCondition Class Reference

Wait until a given condition holds. More...

#include <>>

Public Member Functions

 WaitCondition (Mutex *mutex=0)
 Constructor. More...
 
 ~WaitCondition ()
 Destructor. More...
 
void wait ()
 Wait for the condition forever. More...
 
bool abstimed_wait (long int sec, long int nanosec)
 Wait with absolute timeout. More...
 
bool reltimed_wait (unsigned int sec, unsigned int nanosec)
 Wait with relative timeout. More...
 
void wake_one ()
 Wake another thread waiting for this condition. More...
 
void wake_all ()
 Wake up all waiting threads. More...
 

Detailed Description

Wait until a given condition holds.

Consider two values x and y and you want to wait until they are equal. For instance there may be a thread counting up after he has finished one particular job before he goes to handle the next one. After 10 threads you want to send out the produced entities in one batch run. So the sending thread has to wait for the producing thread until 10 packages have been produced. Simplified this could be implemented as

virtual void run()
{
forever {
mutex->lock();
while (count != 10) {
wait_condition->wait();
}
}
}

The other thread will wake up this waiting thread after each produced package (the thread does not have to know after how many packages they are sent out). The code could look like this:

virtual void run()
{
forever {
produce_package();
wait_condition->wake_one();
}
}

The WaitCondition can operate in two principal modes, either with an internal or with an external Mutex. If no mutex is passed to the constructor an internal mutex is created and used. If a mutex is passed this instance is used, but ownership is not claimed and you have to delete it manually. Additionally, for external mutexes they are never locked by the wait condition. For external mutexes you get all the freedom, but also have the duty to ensure proper locking from the outside! This applies to wait and wake methods.

See also
Mutex
qa_waitcond_serialize.cpp
qa_waitcond.cpp
Author
Tim Niemueller

Definition at line 32 of file wait_condition.h.

Constructor & Destructor Documentation

◆ WaitCondition()

fawkes::WaitCondition::WaitCondition ( Mutex mutex = 0)

Constructor.

Parameters
mutexthe mutex used for this wait condition. If none is given, an internal mutex will be created and used.

Definition at line 111 of file wait_condition.cpp.

◆ ~WaitCondition()

fawkes::WaitCondition::~WaitCondition ( )

Destructor.

Definition at line 126 of file wait_condition.cpp.

Member Function Documentation

◆ abstimed_wait()

bool fawkes::WaitCondition::abstimed_wait ( long int  sec,
long int  nanosec 
)

Wait with absolute timeout.

This waits for the given mutex until either a wakup signal is received or the timeout has passed. The timeout has to be given in absolute system time, a simulated clock source cannot be used.

Parameters
secSeconds of absolute time since the epoch (value compatible to timeval tv_sec part is sufficient).
nanosecNanoseconds part of the absolute timeout. Added to the seconds part.
Returns
true, if the thread was woken up by another thread calling wake_one() or wake_all(), false otherwise if the timeout has been reached
Exceptions
Exceptionthrown if another error occurs for the POSIX wait condition

Definition at line 174 of file wait_condition.cpp.

Referenced by WaitConditionTest::start_test().

◆ reltimed_wait()

bool fawkes::WaitCondition::reltimed_wait ( unsigned int  sec,
unsigned int  nanosec 
)

Wait with relative timeout.

This waits for the given mutex until either a wakup signal is received or the timeout has passed. The timeout has to be given in relative system time. It is added to the current time and is then used similar to abstime_wait(). A timeout of (0,0) will cause this method to wait forever, similar to wait().

Parameters
secNumber of seconds to wait
nanosecNumber of nanoseconds to wait, added to seconds value
Returns
true, if the thread was woken up by another thread calling wake_one() or wake_all(), false otherwise if the timeout has been reached
Exceptions
Exceptionthrown if another error occurs for the POSIX wait condition

Definition at line 212 of file wait_condition.cpp.

Referenced by WaitConditionTest::start_test().

◆ wait()

◆ wake_all()

void fawkes::WaitCondition::wake_all ( )

Wake up all waiting threads.

This wakes up all threads waiting for this condition. Note: If the internal mutex is used for this wait/wakeup cycle, the lock to this mutex will be acquired during the wakeup, to ensure that all waiting threads are woken up, even if a call to wait() and wake_one() overlapped. If however, an external Mutex is used, you must ensure by yourself that it is properly locked during the wakeup to ensure this.

Definition at line 295 of file wait_condition.cpp.

Referenced by fawkes::RemoteBlackBoard::connection_died(), firevision::FuseClient::disconnect(), fawkes::DynamicMJPEGStreamWebReply::handle_buffer(), fawkes::RemoteBlackBoard::inbound_received(), fawkes::ThreadManager::interrupt_timed_thread_wait(), LaserFilterThread::loop(), firevision::FuseClient::loop(), PointCloudDBROSCommThread::loop(), DynamixelDriverThread::loop(), fawkes::WebviewJpegStreamProducer::loop(), fawkes::AvahiThread::resolve_address(), fawkes::Thread::run(), FvAcquisitionThread::set_enabled(), fawkes::ThreadManager::set_inifin(), fawkes::Thread::set_prepfin_hold(), fawkes::Thread::wakeup(), and fawkes::Thread::~Thread().

◆ wake_one()

void fawkes::WaitCondition::wake_one ( )

Wake another thread waiting for this condition.

This wakes up any thread waiting for the condition, not a particular one. No guarantee is given about the order of the woken up threads. Note: If the internal mutex is used for this wait/wakeup cycle, the lock to this mutex will be acquired during the wakeup, to ensure that all waiting threads are woken up, even if a call to wait() and wake_one() overlapped. If however, an external Mutex is used, you must ensure by yourself that it is properly locked during the wakeup to ensure this.

Definition at line 274 of file wait_condition.cpp.


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