Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Barriers -- EXTENSION

Class barrier
Constructor barrier(unsigned int)
Constructor barrier(unsigned int, F&&)
Destructor ~barrier()
Member Function wait()
Member Function count_down_and_wait()

A barrier is a simple concept. Also known as a rendezvous, it is a synchronization point between multiple threads. The barrier is configured for a particular number of threads (n), and as threads reach the barrier they must wait until all n threads have arrived. Once the n-th thread has reached the barrier, all the waiting threads can proceed, and the barrier is reset.

#include <boost/thread/barrier.hpp>

class barrier
{
public:
    barrier(barrier const&) = delete;
    barrier& operator=(barrier const&) = delete;

    barrier(unsigned int count);
    template <typename F>
    barrier(unsigned int count, F&&);

    ~barrier();

    bool wait();
    void count_down_and_wait();
};

Instances of boost::barrier are not copyable or movable.

barrier(unsigned int count);

Effects:

Construct a barrier for count threads.

Throws:

boost::thread_resource_error if an error occurs.

barrier(unsigned int count, F&& completion);

Requires:

The result type of the completion function call completion() is void or unsigned int.

Effects:

Construct a barrier for count threads and a completion function completion.

Throws:

boost::thread_resource_error if an error occurs.

~barrier();

Precondition:

No threads are waiting on *this.

Effects:

Destroys *this.

Throws:

Nothing.

bool wait();

Effects:

Block until count threads have called wait or count_down_and_wait on *this. When the count-th thread calls wait, the barrier is reset and all waiting threads are unblocked. The reset depends on whether the barrier was constructed with a completion function or not. If there is no completion function or if the completion function result is void, the reset consists in restoring the original count. Otherwise the rest consist in assigning the result of the completion function (which must not be 0).

Returns:

true for exactly one thread from each batch of waiting threads, false otherwise.

Throws:

- boost::thread_resource_error if an error occurs.

- boost::thread_interrupted if the wait was interrupted by a call to interrupt() on the boost::thread object associated with the current thread of execution.

Notes:

wait() is an interruption point.

void count_down_and_wait();

Effects:

Block until count threads have called wait or count_down_and_wait on *this. When the count-th thread calls wait, the barrier is reset and all waiting threads are unblocked. The reset depends on whether the barrier was constructed with a completion function or not. If there is no completion function or if the completion function result is void, the reset consists in restoring the original count. Otherwise the rest consist in assigning the result of the completion function (which must not be 0).

Throws:

- boost::thread_resource_error if an error occurs.

- boost::thread_interrupted if the wait was interrupted by a call to interrupt() on the boost::thread object associated with the current thread of execution.

Notes:

count_down_and_wait() is an interruption point.


PrevUpHomeNext