...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
|
Boost.ThreadsHeader <boost/thread/condition.hpp> |
condition
condition
synopsiscondition
constructors
and destructorcondition
modifier
functionsInclude the header <boost/thread/condition.hpp> to define the class condition.
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. A condition
object is always used in conjunction with a
mutex object (an object whose type is a model of 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 [Schmidt
00] and [Hoare 74]). Monitors are
one of the most important patterns for creating reliable multithreaded programs.
See Formal Definitions for definitions of thread states blocked and ready. Note that "waiting" is a synonym for blocked.
condition
synopsisnamespace boost { class condition : private boost::noncopyable // Exposition only. // Class condition meets the NonCopyable requirement. { public: condition(); ~condition(); void notify_one(); void notify_all(); template <typename Lock> void wait(Lock& lock); template <typename Lock, typename Predicate> void wait(Lock& lock, Predicate pred); template <typename Lock> bool timed_wait(Lock& lock, const xtime& xt); template <typename Lock, typename Predicate> bool timed_wait(Lock& lock, const xtime& XT, Predicate pred); }; };
condition
constructors
and destructorcondition();
condition
object.~condition();
*this
.condition
modifier
functionsvoid notify_one();
*this
, change
that thread's state to ready. Otherwise there is no effect.condition
object's wait functions).void notify_all();
*this
to ready. If there are no waiting threads, notify_all()
has
no effect.template <typename ScopedLock> void wait(ScopedLock& lock);
ScopedLock
meets the ScopedLock
requirements.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.lock_error
if !lock.locked()
condition
has become
true. Without the loop, race conditions can ensue due to possible "spurious
wake ups". The second version encapsulates this loop idiom internally
and is generally the preferred method.Template<typename ScopedLock, typename Pr> void wait(ScopedLock& lock, Pr pred);
ScopedLock
meets the ScopedLock
requirements, return from pred()
convertible to bool.while (!pred()) wait(lock)
lock_error
if !lock.locked()
template <typename ScopedLock> bool timed_wait(ScopedLock& lock, const xtime& XT);
ScopedLock
meets the ScopedLock
requirements. lock
, blocks the current thread
of execution until readied by a call to this->notify_one()
or this->notify_all()
, or until XT
, and then
reacquires the lock.false
if XT
is reached, otherwise
true
.lock_error
if !lock.locked()
condition
has become
true. Without the loop, race conditions can ensue due to "spurious wake
ups". The second version encapsulates this loop idiom internally and
is generally the preferred method.Template<typename ScopedLock, typename Pr> bool timed_wait(ScopedLock& lock, const xtime& XT, Pr pred);
ScopedLock
meets the ScopedLock
requirements, return from pred()
convertible to bool.while (!pred()) { if (!timed_wait(lock, XT)) return false; } return true;
false
if XT
is reached, otherwise
true
.lock_error
if !lock.locked()
libs/thread/example/condition.cpp
Typical output (dependent on scheduling policies) is:
sent: 0 sent: 1 received: 0 received: 1 sent: 2 sent: 3 received: 2 received: 3 sent: 4 received: 4
Revised 09 January, 2003
© Copyright William E. Kempf 2001-2002. All Rights Reserved.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. William E. Kempf makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.