3 <meta http-equiv=
"Content-Type" content=
"text/html; charset=US-ASCII">
4 <title>Barriers
</title>
5 <link rel=
"stylesheet" href=
"../../../../../../doc/src/boostbook.css" type=
"text/css">
6 <meta name=
"generator" content=
"DocBook XSL Stylesheets V1.75.2">
7 <link rel=
"home" href=
"../../index.html" title=
"Chapter 1. Fiber">
8 <link rel=
"up" href=
"../synchronization.html" title=
"Synchronization">
9 <link rel=
"prev" href=
"conditions.html" title=
"Condition Variables">
10 <link rel=
"next" href=
"channels.html" title=
"Channels">
12 <body bgcolor=
"white" text=
"black" link=
"#0000FF" vlink=
"#840084" alink=
"#0000FF">
13 <table cellpadding=
"2" width=
"100%"><tr>
14 <td valign=
"top"><img alt=
"Boost C++ Libraries" width=
"277" height=
"86" src=
"../../../../../../boost.png"></td>
15 <td align=
"center"><a href=
"../../../../../../index.html">Home
</a></td>
16 <td align=
"center"><a href=
"../../../../../../libs/libraries.htm">Libraries
</a></td>
17 <td align=
"center"><a href=
"http://www.boost.org/users/people.html">People
</a></td>
18 <td align=
"center"><a href=
"http://www.boost.org/users/faq.html">FAQ
</a></td>
19 <td align=
"center"><a href=
"../../../../../../more/index.htm">More
</a></td>
22 <div class=
"spirit-nav">
23 <a accesskey=
"p" href=
"conditions.html"><img src=
"../../../../../../doc/src/images/prev.png" alt=
"Prev"></a><a accesskey=
"u" href=
"../synchronization.html"><img src=
"../../../../../../doc/src/images/up.png" alt=
"Up"></a><a accesskey=
"h" href=
"../../index.html"><img src=
"../../../../../../doc/src/images/home.png" alt=
"Home"></a><a accesskey=
"n" href=
"channels.html"><img src=
"../../../../../../doc/src/images/next.png" alt=
"Next"></a>
26 <div class=
"titlepage"><div><div><h3 class=
"title">
27 <a name=
"fiber.synchronization.barriers"></a><a class=
"link" href=
"barriers.html" title=
"Barriers">Barriers
</a>
28 </h3></div></div></div>
30 A barrier is a concept also known as a
<span class=
"emphasis"><em>rendezvous
</em></span>, it
31 is a synchronization point between multiple contexts of execution (fibers).
32 The barrier is configured for a particular number of fibers (
<code class=
"computeroutput"><span class=
"identifier">n
</span></code>), and as fibers reach the barrier they
33 must wait until all
<code class=
"computeroutput"><span class=
"identifier">n
</span></code> fibers
34 have arrived. Once the
<code class=
"computeroutput"><span class=
"identifier">n
</span></code>-th
35 fiber has reached the barrier, all the waiting fibers can proceed, and the
39 The fact that the barrier automatically resets is significant. Consider a
40 case in which you launch some number of fibers and want to wait only until
41 the first of them has completed. You might be tempted to use a
<code class=
"computeroutput"><span class=
"identifier">barrier
</span><span class=
"special">(
</span><span class=
"number">2</span><span class=
"special">)
</span></code> as the synchronization
42 mechanism, making each new fiber call its
<a class=
"link" href=
"barriers.html#barrier_wait"><code class=
"computeroutput">barrier::wait()
</code></a> method,
43 then calling
<code class=
"computeroutput"><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>
44 in the launching fiber to wait until the first other fiber completes.
47 That will in fact unblock the launching fiber. The unfortunate part is that
48 it will continue blocking the
<span class=
"emphasis"><em>remaining
</em></span> fibers.
51 Consider the following scenario:
53 <div class=
"orderedlist"><ol class=
"orderedlist" type=
"1">
55 Fiber
<span class=
"quote">“<span class=
"quote">main
</span>”</span> launches fibers A, B, C and D, then calls
56 <code class=
"computeroutput"><span class=
"identifier">barrier
</span><span class=
"special">::
</span><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>.
59 Fiber C finishes first and likewise calls
<code class=
"computeroutput"><span class=
"identifier">barrier
</span><span class=
"special">::
</span><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>.
62 Fiber
<span class=
"quote">“<span class=
"quote">main
</span>”</span> is unblocked, as desired.
65 Fiber B calls
<code class=
"computeroutput"><span class=
"identifier">barrier
</span><span class=
"special">::
</span><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>. Fiber B is
<span class=
"emphasis"><em>blocked!
</em></span>
68 Fiber A calls
<code class=
"computeroutput"><span class=
"identifier">barrier
</span><span class=
"special">::
</span><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>. Fibers A and B are unblocked.
71 Fiber D calls
<code class=
"computeroutput"><span class=
"identifier">barrier
</span><span class=
"special">::
</span><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>. Fiber D is blocked indefinitely.
75 (See also
<a class=
"link" href=
"../when_any/when_any/when_any__simple_completion.html#wait_first_simple_section">when_any, simple completion
</a>.)
77 <div class=
"note"><table border=
"0" summary=
"Note">
79 <td rowspan=
"2" align=
"center" valign=
"top" width=
"25"><img alt=
"[Note]" src=
"../../../../../../doc/src/images/note.png"></td>
80 <th align=
"left">Note
</th>
82 <tr><td align=
"left" valign=
"top"><p>
83 It is unwise to tie the lifespan of a barrier to any one of its participating
84 fibers. Although conceptually all waiting fibers awaken
<span class=
"quote">“<span class=
"quote">simultaneously,
</span>”</span>
85 because of the nature of fibers, in practice they will awaken one by one
86 in indeterminate order.
<sup>[
<a name=
"fiber.synchronization.barriers.f0" href=
"#ftn.fiber.synchronization.barriers.f0" class=
"footnote">1</a>]
</sup> The rest of the waiting fibers will still be blocked in
<code class=
"computeroutput"><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>,
87 which must, before returning, access data members in the barrier object.
93 <a name=
"class_barrier_bridgehead"></a>
94 <span><a name=
"class_barrier"></a></span>
95 <a class=
"link" href=
"barriers.html#class_barrier">Class
<code class=
"computeroutput">barrier
</code></a>
99 <pre class=
"programlisting"><span class=
"preprocessor">#include
</span> <span class=
"special"><</span><span class=
"identifier">boost
</span><span class=
"special">/
</span><span class=
"identifier">fiber
</span><span class=
"special">/
</span><span class=
"identifier">barrier
</span><span class=
"special">.
</span><span class=
"identifier">hpp
</span><span class=
"special">></span>
101 <span class=
"keyword">namespace
</span> <span class=
"identifier">boost
</span> <span class=
"special">{
</span>
102 <span class=
"keyword">namespace
</span> <span class=
"identifier">fibers
</span> <span class=
"special">{
</span>
104 <span class=
"keyword">class
</span> <span class=
"identifier">barrier
</span> <span class=
"special">{
</span>
105 <span class=
"keyword">public
</span><span class=
"special">:
</span>
106 <span class=
"keyword">explicit
</span> <span class=
"identifier">barrier
</span><span class=
"special">(
</span> <span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">size_t
</span><span class=
"special">);
</span>
108 <span class=
"identifier">barrier
</span><span class=
"special">(
</span> <span class=
"identifier">barrier
</span> <span class=
"keyword">const
</span><span class=
"special">&)
</span> <span class=
"special">=
</span> <span class=
"keyword">delete
</span><span class=
"special">;
</span>
109 <span class=
"identifier">barrier
</span> <span class=
"special">&</span> <span class=
"keyword">operator
</span><span class=
"special">=(
</span> <span class=
"identifier">barrier
</span> <span class=
"keyword">const
</span><span class=
"special">&)
</span> <span class=
"special">=
</span> <span class=
"keyword">delete
</span><span class=
"special">;
</span>
111 <span class=
"keyword">bool
</span> <span class=
"identifier">wait
</span><span class=
"special">();
</span>
112 <span class=
"special">};
</span>
114 <span class=
"special">}}
</span>
117 Instances of
<a class=
"link" href=
"barriers.html#class_barrier"><code class=
"computeroutput">barrier
</code></a> are not copyable or movable.
120 <a name=
"fiber.synchronization.barriers.h0"></a>
121 <span><a name=
"fiber.synchronization.barriers.constructor"></a></span><a class=
"link" href=
"barriers.html#fiber.synchronization.barriers.constructor">Constructor
</a>
123 <pre class=
"programlisting"><span class=
"keyword">explicit
</span> <span class=
"identifier">barrier
</span><span class=
"special">(
</span> <span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">size_t
</span> <span class=
"identifier">initial
</span><span class=
"special">);
</span>
125 <div class=
"variablelist">
126 <p class=
"title"><b></b></p>
128 <dt><span class=
"term">Effects:
</span></dt>
130 Construct a barrier for
<code class=
"computeroutput"><span class=
"identifier">initial
</span></code>
133 <dt><span class=
"term">Throws:
</span></dt>
135 <code class=
"computeroutput"><span class=
"identifier">fiber_error
</span></code>
137 <dt><span class=
"term">Error Conditions:
</span></dt>
139 <span class=
"bold"><strong>invalid_argument
</strong></span>: if
<code class=
"computeroutput"><span class=
"identifier">initial
</span></code> is zero.
146 <a name=
"barrier_wait_bridgehead"></a>
147 <span><a name=
"barrier_wait"></a></span>
148 <a class=
"link" href=
"barriers.html#barrier_wait">Member function
<code class=
"computeroutput">wait
</code>()
</a>
152 <pre class=
"programlisting"><span class=
"keyword">bool
</span> <span class=
"identifier">wait
</span><span class=
"special">();
</span>
154 <div class=
"variablelist">
155 <p class=
"title"><b></b></p>
157 <dt><span class=
"term">Effects:
</span></dt>
159 Block until
<code class=
"computeroutput"><span class=
"identifier">initial
</span></code>
160 fibers have called
<code class=
"computeroutput"><span class=
"identifier">wait
</span></code>
161 on
<code class=
"computeroutput"><span class=
"special">*
</span><span class=
"keyword">this
</span></code>.
162 When the
<code class=
"computeroutput"><span class=
"identifier">initial
</span></code>-th
163 fiber calls
<code class=
"computeroutput"><span class=
"identifier">wait
</span></code>, all
164 waiting fibers are unblocked, and the barrier is reset.
166 <dt><span class=
"term">Returns:
</span></dt>
168 <code class=
"computeroutput"><span class=
"keyword">true
</span></code> for exactly one fiber
169 from each batch of waiting fibers,
<code class=
"computeroutput"><span class=
"keyword">false
</span></code>
172 <dt><span class=
"term">Throws:
</span></dt>
174 <code class=
"computeroutput"><span class=
"identifier">fiber_error
</span></code>
178 <div class=
"footnotes">
179 <br><hr width=
"100" align=
"left">
180 <div class=
"footnote"><p><sup>[
<a name=
"ftn.fiber.synchronization.barriers.f0" href=
"#fiber.synchronization.barriers.f0" class=
"para">1</a>]
</sup>
181 The current implementation wakes fibers in FIFO order: the first to call
182 <code class=
"computeroutput"><span class=
"identifier">wait
</span><span class=
"special">()
</span></code>
183 wakes first, and so forth. But it is perilous to rely on the order in
184 which the various fibers will reach the
<code class=
"computeroutput"><span class=
"identifier">wait
</span><span class=
"special">()
</span></code> call.
188 <table xmlns:
rev=
"http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width=
"100%"><tr>
189 <td align=
"left"></td>
190 <td align=
"right"><div class=
"copyright-footer">Copyright
© 2013 Oliver Kowalke
<p>
191 Distributed under the Boost Software License, Version
1.0. (See accompanying
192 file LICENSE_1_0.txt or copy at
<a href=
"http://www.boost.org/LICENSE_1_0.txt" target=
"_top">http://www.boost.org/LICENSE_1_0.txt
</a>)
197 <div class=
"spirit-nav">
198 <a accesskey=
"p" href=
"conditions.html"><img src=
"../../../../../../doc/src/images/prev.png" alt=
"Prev"></a><a accesskey=
"u" href=
"../synchronization.html"><img src=
"../../../../../../doc/src/images/up.png" alt=
"Up"></a><a accesskey=
"h" href=
"../../index.html"><img src=
"../../../../../../doc/src/images/home.png" alt=
"Home"></a><a accesskey=
"n" href=
"channels.html"><img src=
"../../../../../../doc/src/images/next.png" alt=
"Next"></a>