Class condition
boost::condition —
An object of class condition is a
synchronization primitive used to cause a thread to wait until a
particular shared-data condition (or time) is met.
Synopsis
Description
A condition object is always used in
conjunction with a mutex
object (an object whose type is a model of a Mutex or one of its
refinements). The mutex object must be locked prior to waiting on the
condition, which is verified by passing a lock object (an object whose
type is a model of Lock or
one of its refinements) to the condition object's
wait functions. Upon blocking on the condition
object, the thread unlocks the mutex object. When the thread returns
from a call to one of the condition object's wait
functions the mutex object is again locked. The tricky unlock/lock
sequence is performed automatically by the
condition object's wait functions.
The condition type is often used to
implement the Monitor Object and other important patterns (see
[SchmidtStalRohnertBuschmann] and [Hoare74]). Monitors are one
of the most important patterns for creating reliable multithreaded
programs.
See Glossary for definitions of thread states
blocked and ready. Note that "waiting" is a synonym for blocked.
condition
construct/copy/destruct
-
condition();
-
~condition();
condition
notification
-
void notify_one();
Effects: |
If there is a thread waiting on *this ,
change that thread's state to ready. Otherwise there is no
effect. |
Notes: |
If more than one thread is waiting on *this ,
it is unspecified which is made ready. After returning to a ready
state the notified thread must still acquire the mutex again (which
occurs within the call to one of the condition
object's wait functions.) |
-
void notify_all();
Effects: |
Change the state of all threads waiting on
*this to ready. If there are no waiting threads,
notify_all() has no effect. |
condition
waiting
-
template<typename ScopedLock> void wait(ScopedLock& lock);
Requires: |
ScopedLock meets the ScopedLock
requirements. |
Effects: |
Releases the lock on the mutex object
associated with lock , blocks the current thread of execution
until readied by a call to this->notify_one()
or this->notify_all() , and then reacquires the
lock. |
Throws: |
lock_error if
!lock.locked()
|
-
template<typename ScopedLock, typename Pred>
void wait(ScopedLock& lock, Pred pred);
Requires: |
ScopedLock meets the ScopedLock
requirements and the return from pred() is
convertible to bool . |
Effects: |
As if: while (!pred())
wait(lock)
|
Throws: |
lock_error if
!lock.locked()
|
-
template<typename ScopedLock>
bool timed_wait(ScopedLock& lock, const boost::xtime& xt);
Requires: |
ScopedLock meets the ScopedLock
requirements. |
Effects: |
Releases the lock on the mutex object
associated with lock , blocks the current thread of execution
until readied by a call to this->notify_one()
or this->notify_all() , or until time xt
is reached, and then reacquires the lock. |
Returns: |
false if time xt is reached,
otherwise true . |
Throws: |
lock_error if
!lock.locked()
|
-
template<typename ScopedLock, typename Pred>
bool timed_wait(ScopedLock& lock, const boost::xtime& xt, Pred pred);
Requires: |
ScopedLock meets the ScopedLock
requirements and the return from pred() is
convertible to bool . |
Effects: |
As if: while (!pred()) { if (!timed_wait(lock,
xt)) return false; } return true;
|
Returns: |
false if xt is reached,
otherwise true . |
Throws: |
lock_error if
!lock.locked()
|