boost/libs/thread/doc/barrier.qbk

[/
  (C) Copyright 2007-8 Anthony Williams.
  (C) Copyright 2013 Vicente J. Botet Escriba.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:barriers Barriers -- EXTENSION]

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.

[section:barrier Class `barrier`]

    #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 __barrier__ are not copyable or movable.

[section Constructor `barrier(unsigned int)`]

    barrier(unsigned int count);

[variablelist

[[Effects:] [Construct a barrier for `count` threads.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]

[endsect]
[section Constructor `barrier(unsigned int, F&&)`]

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

[variablelist

[[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:] [__thread_resource_error__ if an error occurs.]]

]


[endsect]
[section Destructor `~barrier()`]

    ~barrier();

[variablelist

[[Precondition:] [No threads are waiting on `*this`.]]

[[Effects:] [Destroys `*this`.]]

[[Throws:] [Nothing.]]

]

[endsect]
[section Member Function `wait()`]

    bool wait();

[variablelist

[[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:] [

- __thread_resource_error__ if an error occurs. 

- __thread_interrupted__ if the wait was interrupted by a call to
__interrupt__ on the __thread__ object associated with the current thread of execution.

]]

[[Notes:] [`wait()` is an ['interruption point].]]

]

[endsect]
[section Member Function `count_down_and_wait()`]

        void count_down_and_wait();

[variablelist

[[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:] [

- __thread_resource_error__ if an error occurs. 

- __thread_interrupted__ if the wait was interrupted by a call to
__interrupt__ on the __thread__ object associated with the current thread of execution.

]]

[[Notes:] [`count_down_and_wait()` is an ['interruption point].]]

]


[endsect]
[endsect]
[endsect]