| Home | Libraries | People | FAQ | More

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