boost.png (6897 bytes) Home Libraries People FAQ More
PrevUpHomeNext

Class barrier

boost::barrier —

An object of class barrier is a synchronization primitive used to cause a set of threads to wait until they each perform a certain function or each reach a particular point in their execution.

Synopsis

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

  // waiting
  bool wait();
};

Description

When a barrier is created, it is initialized with a thread count N. The first N-1 calls to wait() will all cause their threads to be blocked. The Nth call to wait() will allow all of the waiting threads, including the Nth thread, to be placed in a ready state. The Nth call will also "reset" the barrier such that, if an additional N+1th call is made to wait(), it will be as though this were the first call to wait(); in other words, the N+1th to 2N-1th calls to wait() will cause their threads to be blocked, and the 2Nth call to wait() will allow all of the waiting threads, including the 2Nth thread, to be placed in a ready state and reset the barrier. This functionality allows the same set of N threads to re-use a barrier object to synchronize their execution at multiple points during their execution.

See Glossary for definitions of thread states blocked and ready. Note that "waiting" is a synonym for blocked.

barrier construct/copy/destruct

  1. barrier(size_t count);

    Effects: Constructs a barrier object that will cause count threads to block on a call to wait(). 

  2. ~barrier();

    Effects: Destroys *this. If threads are still executing their wait() operations, the behavior for these threads is undefined.

barrier waiting

  1. bool wait();

    Effects: Wait until N threads call wait(), where N equals the count provided to the constructor for the barrier object.

    Note that if the barrier is destroyed before wait() can return, the behavior is undefined.


    Returns: Exactly one of the N threads will receive a return value of true, the others will receive a value of false. Precisely which thread receives the return value of true will be implementation-defined. Applications can use this value to designate one thread as a leader that will take a certain action, and the other threads emerging from the barrier can wait for that action to take place.

Copyright © 2001-2003 William E. Kempf
PrevUpHomeNext