| Home | Libraries | People | FAQ | More

## 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

    class condition : private boost::noncopyable   // Exposition only
    {
    public:
      // construct/copy/destruct
      condition();
      ~condition();

      // notification
      void notify_one();
      void notify_all();

      // waiting
      template<typename ScopedLock> void wait(ScopedLock&);
      template<typename ScopedLock, typename Pred> void wait(ScopedLock&, Pred);
      template<typename ScopedLock>
        bool timed_wait(ScopedLock&, const boost::xtime&);
      template<typename ScopedLock, typename Pred>
        bool timed_wait(ScopedLock&, const boost::xtime&, Pred);
    };

## 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

1.     condition();

   Effects: | Constructs a condition object.

2.     ~condition();

   Effects: | Destroys `*this`.

### `condition` notification

1.     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.)

2.     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

1.     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()`

2.     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()`

3.     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()`

4.     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()`

| Copyright © 2001-2003 William E. Kempf