]> git.proxmox.com Git - ceph.git/blob - ceph/src/boost/libs/thread/doc/barrier.qbk
bump version to 12.2.2-pve1
[ceph.git] / ceph / src / boost / libs / thread / doc / barrier.qbk
1 [/
2 (C) Copyright 2007-8 Anthony Williams.
3 (C) Copyright 2013-2015 Vicente J. Botet Escriba.
4 Distributed under the Boost Software License, Version 1.0.
5 (See accompanying file LICENSE_1_0.txt or copy at
6 http://www.boost.org/LICENSE_1_0.txt).
7 ]
8
9 [section:barriers Barriers -- EXTENSION]
10
11 A barrier is a simple concept. Also known as a ['rendezvous], it is a synchronization point between multiple threads. The barrier is
12 configured for a particular number of threads (`n`), and as threads reach the barrier they must wait until all `n` threads have
13 arrived. Once the `n`-th thread has reached the barrier, all the waiting threads can proceed, and the barrier is reset.
14
15 [section:barrier Class `barrier`]
16
17 #include <boost/thread/barrier.hpp>
18
19 class barrier
20 {
21 public:
22 barrier(barrier const&) = delete;
23 barrier& operator=(barrier const&) = delete;
24
25 barrier(unsigned int count);
26 template <typename F>
27 barrier(unsigned int count, F&&);
28
29 ~barrier();
30
31 bool wait();
32 void count_down_and_wait();
33 };
34
35 Instances of __barrier__ are not copyable or movable.
36
37 [section Constructor `barrier(unsigned int)`]
38
39 barrier(unsigned int count);
40
41 [variablelist
42
43 [[Effects:] [Construct a barrier for `count` threads.]]
44
45 [[Throws:] [__thread_resource_error__ if an error occurs.]]
46
47 ]
48
49 [endsect]
50 [section Constructor `barrier(unsigned int, F&&)`]
51
52 barrier(unsigned int count, F&& completion);
53
54 [variablelist
55
56 [[Requires:] [The result type of the completion function call `completion()` is `void` or `unsigned int`.]]
57
58 [[Effects:] [Construct a barrier for `count` threads and a completion function `completion`.]]
59
60 [[Throws:] [__thread_resource_error__ if an error occurs.]]
61
62 ]
63
64
65 [endsect]
66 [section Destructor `~barrier()`]
67
68 ~barrier();
69
70 [variablelist
71
72 [[Precondition:] [No threads are waiting on `*this`.]]
73
74 [[Effects:] [Destroys `*this`.]]
75
76 [[Throws:] [Nothing.]]
77
78 ]
79
80 [endsect]
81 [section Member Function `wait()`]
82
83 bool wait();
84
85 [variablelist
86
87 [[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.
88 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).]]
89
90 [[Returns:] [`true` for exactly one thread from each batch of waiting threads, `false` otherwise.]]
91
92 [[Throws:] [
93
94 - __thread_resource_error__ if an error occurs.
95
96 - __thread_interrupted__ if the wait was interrupted by a call to
97 __interrupt__ on the __thread__ object associated with the current thread of execution.
98
99 ]]
100
101 [[Notes:] [`wait()` is an ['interruption point].]]
102
103 ]
104
105 [endsect]
106 [section Member Function `count_down_and_wait()`]
107
108 void count_down_and_wait();
109
110 [variablelist
111
112 [[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.
113 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).]]
114
115 [[Throws:] [
116
117 - __thread_resource_error__ if an error occurs.
118
119 - __thread_interrupted__ if the wait was interrupted by a call to
120 __interrupt__ on the __thread__ object associated with the current thread of execution.
121
122 ]]
123
124 [[Notes:] [`count_down_and_wait()` is an ['interruption point].]]
125
126 ]
127
128
129 [endsect]
130 [endsect]
131 [endsect]