]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> | |
3 | <library id="fiber" name="Fiber" dirname="fiber" last-revision="$Date: 2016/05/22 05:16:53 $" | |
4 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
5 | <libraryinfo> | |
6 | <authorgroup> | |
7 | <author> | |
8 | <firstname>Oliver</firstname> <surname>Kowalke</surname> | |
9 | </author> | |
10 | </authorgroup> | |
11 | <copyright> | |
12 | <year>2013</year> <holder>Oliver Kowalke</holder> | |
13 | </copyright> | |
14 | <legalnotice id="fiber.legal"> | |
15 | <para> | |
16 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
17 | file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>) | |
18 | </para> | |
19 | </legalnotice> | |
20 | <librarypurpose> | |
21 | C++ Library to cooperatively schedule and synchronize micro-threads | |
22 | </librarypurpose> | |
23 | <librarycategory name="category:text"></librarycategory> | |
24 | </libraryinfo> | |
25 | <title>Fiber</title> | |
26 | <section id="fiber.overview"> | |
27 | <title><link linkend="fiber.overview">Overview</link></title> | |
28 | <para> | |
29 | <emphasis role="bold">Boost.Fiber</emphasis> provides a framework for micro-/userland-threads | |
30 | (fibers) scheduled cooperatively. The API contains classes and functions to | |
31 | manage and synchronize fibers similiarly to <ulink url="http://en.cppreference.com/w/cpp/thread">standard | |
32 | thread support library</ulink>. | |
33 | </para> | |
34 | <para> | |
35 | Each fiber has its own stack. | |
36 | </para> | |
37 | <para> | |
38 | A fiber can save the current execution state, including all registers and CPU | |
39 | flags, the instruction pointer, and the stack pointer and later restore this | |
40 | state. The idea is to have multiple execution paths running on a single thread | |
41 | using cooperative scheduling (versus threads, which are preemptively scheduled). | |
42 | The running fiber decides explicitly when it should yield to allow another | |
43 | fiber to run (context switching). <emphasis role="bold">Boost.Fiber</emphasis> | |
44 | internally uses <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink> | |
45 | from <ulink url="http://www.boost.org/doc/libs/release/libs/context/index.html">Boost.Context</ulink>; | |
46 | the classes in this library manage, schedule and, when needed, synchronize | |
47 | those execution contexts. A context switch between threads usually costs thousands | |
48 | of CPU cycles on x86, compared to a fiber switch with less than a hundred cycles. | |
49 | A fiber runs on a single thread at any point in time. | |
50 | </para> | |
51 | <para> | |
52 | In order to use the classes and functions described here, you can either include | |
53 | the specific headers specified by the descriptions of each class or function, | |
54 | or include the master library header: | |
55 | </para> | |
56 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">all</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
57 | </programlisting> | |
58 | <para> | |
59 | which includes all the other headers in turn. | |
60 | </para> | |
61 | <para> | |
62 | The namespaces used are: | |
63 | </para> | |
64 | <programlisting><phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase> | |
65 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase> | |
66 | </programlisting> | |
67 | <bridgehead renderas="sect3" id="fiber.overview.h0"> | |
68 | <phrase id="fiber.overview.fibers_and_threads"/><link linkend="fiber.overview.fibers_and_threads">Fibers | |
69 | and Threads</link> | |
70 | </bridgehead> | |
71 | <para> | |
72 | Control is cooperatively passed between fibers launched on a given thread. | |
73 | At a given moment, on a given thread, at most one fiber is running. | |
74 | </para> | |
75 | <para> | |
76 | Spawning additional fibers on a given thread does not distribute your program | |
77 | across more hardware cores, though it can make more effective use of the core | |
78 | on which it's running. | |
79 | </para> | |
80 | <para> | |
81 | On the other hand, a fiber may safely access any resource exclusively owned | |
82 | by its parent thread without explicitly needing to defend that resource against | |
83 | concurrent access by other fibers on the same thread. You are already guaranteed | |
84 | that no other fiber on that thread is concurrently touching that resource. | |
85 | This can be particularly important when introducing concurrency in legacy code. | |
86 | You can safely spawn fibers running old code, using asynchronous I/O to interleave | |
87 | execution. | |
88 | </para> | |
89 | <para> | |
90 | In effect, fibers provide a natural way to organize concurrent code based on | |
91 | asynchronous I/O. Instead of chaining together completion handlers, code running | |
92 | on a fiber can make what looks like a normal blocking function call. That call | |
93 | can cheaply suspend the calling fiber, allowing other fibers on the same thread | |
94 | to run. When the operation has completed, the suspended fiber resumes, without | |
95 | having to explicitly save or restore its state. Its local stack variables persist | |
96 | across the call. | |
97 | </para> | |
98 | <para> | |
99 | A fiber can be migrated from one thread to another, though the library does | |
100 | not do this by default. It is possible for you to supply a custom scheduler | |
101 | that migrates fibers between threads. You may specify custom fiber properties | |
102 | to help your scheduler decide which fibers are permitted to migrate. Please | |
103 | see <link linkend="migration">Migrating fibers between threads</link> and | |
104 | <link linkend="custom">Customization</link> for more details. | |
105 | </para> | |
106 | <para> | |
107 | A fiber launched on a particular thread continues running on that thread unless | |
108 | migrated. It might be unblocked (see <link linkend="blocking">Blocking</link> | |
109 | below) by some other thread, but that only transitions the fiber from <quote>blocked</quote> | |
110 | to <quote>ready</quote> on its current thread — it does not cause the fiber to | |
111 | resume on the thread that unblocked it. | |
112 | </para> | |
113 | <anchor id="thread_local_storage"/> | |
114 | <bridgehead renderas="sect3" id="fiber.overview.h1"> | |
115 | <phrase id="fiber.overview.thread_local_storage"/><link linkend="fiber.overview.thread_local_storage">thread-local | |
116 | storage</link> | |
117 | </bridgehead> | |
118 | <para> | |
119 | Unless migrated, a fiber may access thread-local storage; however that storage | |
120 | will be shared among all fibers running on the same thread. For fiber-local | |
121 | storage, please see <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link>. | |
122 | </para> | |
123 | <anchor id="cross_thread_sync"/> | |
124 | <bridgehead renderas="sect3" id="fiber.overview.h2"> | |
125 | <phrase id="fiber.overview.boost_fibers_no_atomics"/><link linkend="fiber.overview.boost_fibers_no_atomics">BOOST_FIBERS_NO_ATOMICS</link> | |
126 | </bridgehead> | |
127 | <para> | |
128 | The fiber synchronization objects provided by this library will, by default, | |
129 | safely synchronize fibers running on different threads. However, this level | |
130 | of synchronization can be removed (for performance) by building the library | |
131 | with <emphasis role="bold"><code><phrase role="identifier">BOOST_FIBERS_NO_ATOMICS</phrase></code></emphasis> | |
132 | defined. When the library is built with that macro, you must ensure that all | |
133 | the fibers referencing a particular synchronization object are running in the | |
134 | same thread. Please see <link linkend="synchronization">Synchronization</link>. | |
135 | </para> | |
136 | <anchor id="blocking"/> | |
137 | <bridgehead renderas="sect3" id="fiber.overview.h3"> | |
138 | <phrase id="fiber.overview.blocking"/><link linkend="fiber.overview.blocking">Blocking</link> | |
139 | </bridgehead> | |
140 | <para> | |
141 | Normally, when this documentation states that a particular fiber <emphasis>blocks</emphasis> | |
142 | (or equivalently, <emphasis>suspends),</emphasis> it means that it yields control, | |
143 | allowing other fibers on the same thread to run. The synchronization mechanisms | |
144 | provided by <emphasis role="bold">Boost.Fiber</emphasis> have this behavior. | |
145 | </para> | |
146 | <para> | |
147 | A fiber may, of course, use normal thread synchronization mechanisms; however | |
148 | a fiber that invokes any of these mechanisms will block its entire thread, | |
149 | preventing any other fiber from running on that thread in the meantime. For | |
150 | instance, when a fiber wants to wait for a value from another fiber in the | |
151 | same thread, using <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
152 | role="identifier">future</phrase></code> would be unfortunate: <code><phrase | |
153 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase | |
154 | role="special">::</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
155 | would block the whole thread, preventing the other fiber from delivering its | |
156 | value. Use <link linkend="class_future"><code>future<></code></link> instead. | |
157 | </para> | |
158 | <para> | |
159 | Similarly, a fiber that invokes a normal blocking I/O operation will block | |
160 | its entire thread. Fiber authors are encouraged to consistently use asynchronous | |
161 | I/O. <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink> | |
162 | and other asynchronous I/O operations can straightforwardly be adapted for | |
163 | <emphasis role="bold">Boost.Fiber</emphasis>: see <link linkend="callbacks">Integrating | |
164 | Fibers with Asynchronous Callbacks</link>. | |
165 | </para> | |
166 | <warning> | |
167 | <para> | |
168 | This library is <emphasis>not</emphasis> an official Boost library. | |
169 | </para> | |
170 | </warning> | |
171 | <para> | |
172 | <emphasis role="bold">Boost.Fiber</emphasis> depends upon <ulink url="http://www.boost.org/doc/libs/release/libs/context/index.html">Boost.Context</ulink>. | |
173 | Boost version 1.61.0 or greater is required. | |
174 | </para> | |
175 | <note> | |
176 | <para> | |
177 | This library requires C++11! | |
178 | </para> | |
179 | </note> | |
180 | </section> | |
181 | <section id="fiber.fiber_mgmt"> | |
182 | <title><link linkend="fiber.fiber_mgmt">Fiber management</link></title> | |
183 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h0"> | |
184 | <phrase id="fiber.fiber_mgmt.synopsis"/><link linkend="fiber.fiber_mgmt.synopsis">Synopsis</link> | |
185 | </bridgehead> | |
186 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">all</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
187 | ||
188 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
189 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
190 | ||
191 | <phrase role="keyword">class</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">;</phrase> | |
192 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
193 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
194 | ||
195 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">SchedAlgo</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
196 | <phrase role="keyword">void</phrase> <phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
197 | <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">();</phrase> | |
198 | ||
199 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">algo</phrase> <phrase role="special">{</phrase> | |
200 | ||
201 | <phrase role="keyword">struct</phrase> <phrase role="identifier">algorithm</phrase><phrase role="special">;</phrase> | |
202 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase> | |
203 | <phrase role="keyword">struct</phrase> <phrase role="identifier">algorithm_with_properties</phrase><phrase role="special">;</phrase> | |
204 | <phrase role="keyword">class</phrase> <phrase role="identifier">round_robin</phrase><phrase role="special">;</phrase> | |
205 | <phrase role="keyword">class</phrase> <phrase role="identifier">shared_round_robin</phrase><phrase role="special">;</phrase> | |
206 | ||
207 | <phrase role="special">}</phrase> | |
208 | ||
209 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">this_fiber</phrase> <phrase role="special">{</phrase> | |
210 | ||
211 | <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
212 | <phrase role="keyword">void</phrase> <phrase role="identifier">yield</phrase><phrase role="special">();</phrase> | |
213 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
214 | <phrase role="keyword">void</phrase> <phrase role="identifier">sleep_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> | |
215 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
216 | <phrase role="keyword">void</phrase> <phrase role="identifier">sleep_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">);</phrase> | |
217 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase> | |
218 | <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase> | |
219 | ||
220 | <phrase role="special">}}</phrase> | |
221 | </programlisting> | |
222 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h1"> | |
223 | <phrase id="fiber.fiber_mgmt.tutorial"/><link linkend="fiber.fiber_mgmt.tutorial">Tutorial</link> | |
224 | </bridgehead> | |
225 | <para> | |
226 | Each <link linkend="class_fiber"><code>fiber</code></link> represents a micro-thread which will be launched and managed | |
227 | cooperatively by a scheduler. Objects of type <link linkend="class_fiber"><code>fiber</code></link> are move-only. | |
228 | </para> | |
229 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f1</phrase><phrase role="special">;</phrase> <phrase role="comment">// not-a-fiber</phrase> | |
230 | ||
231 | <phrase role="keyword">void</phrase> <phrase role="identifier">f</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
232 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f2</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase> | |
233 | ||
234 | <phrase role="identifier">f1</phrase> <phrase role="special">=</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">f2</phrase><phrase role="special">);</phrase> <phrase role="comment">// f2 moved to f1</phrase> | |
235 | <phrase role="special">}</phrase> | |
236 | </programlisting> | |
237 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h2"> | |
238 | <phrase id="fiber.fiber_mgmt.launching"/><link linkend="fiber.fiber_mgmt.launching">Launching</link> | |
239 | </bridgehead> | |
240 | <para> | |
241 | A new fiber is launched by passing an object of a callable type that can be | |
242 | invoked with no parameters. If the object must not be copied or moved, then | |
243 | <emphasis>std::ref</emphasis> can be used to pass in a reference to the function | |
244 | object. In this case, the user must ensure that the referenced object outlives | |
245 | the newly-created fiber. | |
246 | </para> | |
247 | <programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">callable</phrase> <phrase role="special">{</phrase> | |
248 | <phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()();</phrase> | |
249 | <phrase role="special">};</phrase> | |
250 | ||
251 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">copies_are_safe</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
252 | <phrase role="identifier">callable</phrase> <phrase role="identifier">x</phrase><phrase role="special">;</phrase> | |
253 | <phrase role="keyword">return</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">x</phrase><phrase role="special">);</phrase> | |
254 | <phrase role="special">}</phrase> <phrase role="comment">// x is destroyed, but the newly-created fiber has a copy, so this is OK</phrase> | |
255 | ||
256 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">oops</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
257 | <phrase role="identifier">callable</phrase> <phrase role="identifier">x</phrase><phrase role="special">;</phrase> | |
258 | <phrase role="keyword">return</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">x</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
259 | <phrase role="special">}</phrase> <phrase role="comment">// x is destroyed, but the newly-created fiber still has a reference</phrase> | |
260 | <phrase role="comment">// this leads to undefined behaviour</phrase> | |
261 | </programlisting> | |
262 | <para> | |
263 | The spawned <link linkend="class_fiber"><code>fiber</code></link> does not immediately start running. It is enqueued | |
264 | in the list of ready-to-run fibers, and will run when the scheduler gets around | |
265 | to it. | |
266 | </para> | |
267 | <anchor id="exceptions"/> | |
268 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h3"> | |
269 | <phrase id="fiber.fiber_mgmt.exceptions"/><link linkend="fiber.fiber_mgmt.exceptions">Exceptions</link> | |
270 | </bridgehead> | |
271 | <para> | |
272 | An exception escaping from the function or callable object passed to the <link linkend="class_fiber"><code>fiber</code></link> | |
273 | constructor | |
274 | calls <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
275 | role="identifier">terminate</phrase><phrase role="special">()</phrase></code>. | |
276 | If you need to know which exception was thrown, use <link linkend="class_future"><code>future<></code></link> or | |
277 | <link linkend="class_packaged_task"><code>packaged_task<></code></link>. | |
278 | </para> | |
279 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h4"> | |
280 | <phrase id="fiber.fiber_mgmt.detaching"/><link linkend="fiber.fiber_mgmt.detaching">Detaching</link> | |
281 | </bridgehead> | |
282 | <para> | |
283 | A <link linkend="class_fiber"><code>fiber</code></link> can be detached by explicitly invoking the <link linkend="fiber_detach"><code>fiber::detach()</code></link> member | |
284 | function. After <link linkend="fiber_detach"><code>fiber::detach()</code></link> is called on a fiber object, that | |
285 | object represents <emphasis>not-a-fiber</emphasis>. The fiber object may then | |
286 | safely be destroyed. | |
287 | </para> | |
288 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
289 | </programlisting> | |
290 | <para> | |
291 | <emphasis role="bold">Boost.Fiber</emphasis> provides a number of ways to wait | |
292 | for a running fiber to complete. You can coordinate even with a detached fiber | |
293 | using a <link linkend="class_mutex"><code>mutex</code></link>, or <link linkend="class_condition_variable"><code>condition_variable</code></link>, or | |
294 | any of the other <link linkend="synchronization">synchronization objects</link> | |
295 | provided by the library. | |
296 | </para> | |
297 | <para> | |
298 | If a detached fiber is still running when the thread’s main fiber terminates, | |
299 | the thread will not shut down. | |
300 | </para> | |
301 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h5"> | |
302 | <phrase id="fiber.fiber_mgmt.joining"/><link linkend="fiber.fiber_mgmt.joining">Joining</link> | |
303 | </bridgehead> | |
304 | <para> | |
305 | In order to wait for a fiber to finish, the <link linkend="fiber_join"><code>fiber::join()</code></link> member function | |
306 | of the <link linkend="class_fiber"><code>fiber</code></link> object can be used. <link linkend="fiber_join"><code>fiber::join()</code></link> will block | |
307 | until the <link linkend="class_fiber"><code>fiber</code></link> object has completed. | |
308 | </para> | |
309 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
310 | <phrase role="special">...</phrase> | |
311 | <phrase role="special">}</phrase> | |
312 | ||
313 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase> | |
314 | <phrase role="special">...</phrase> | |
315 | <phrase role="identifier">f</phrase><phrase role="special">.</phrase><phrase role="identifier">join</phrase><phrase role="special">();</phrase> | |
316 | </programlisting> | |
317 | <para> | |
318 | If the fiber has already completed, then <link linkend="fiber_join"><code>fiber::join()</code></link> returns immediately | |
319 | and the joined <link linkend="class_fiber"><code>fiber</code></link> object becomes <emphasis>not-a-fiber</emphasis>. | |
320 | </para> | |
321 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h6"> | |
322 | <phrase id="fiber.fiber_mgmt.destruction"/><link linkend="fiber.fiber_mgmt.destruction">Destruction</link> | |
323 | </bridgehead> | |
324 | <para> | |
325 | When a <link linkend="class_fiber"><code>fiber</code></link> object representing a valid execution context (the fiber | |
326 | is <link linkend="fiber_joinable"><code>fiber::joinable()</code></link>) is destroyed, the program terminates. If | |
327 | you intend the fiber to outlive the <link linkend="class_fiber"><code>fiber</code></link> object that launched it, | |
328 | use the <link linkend="fiber_detach"><code>fiber::detach()</code></link> method. | |
329 | </para> | |
330 | <programlisting><phrase role="special">{</phrase> | |
331 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase> <phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase> | |
332 | <phrase role="special">}</phrase> <phrase role="comment">// std::terminate() will be called</phrase> | |
333 | ||
334 | <phrase role="special">{</phrase> | |
335 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f</phrase><phrase role="special">(</phrase><phrase role="identifier">some_fn</phrase><phrase role="special">);</phrase> | |
336 | <phrase role="identifier">f</phrase><phrase role="special">.</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
337 | <phrase role="special">}</phrase> <phrase role="comment">// okay, program continues</phrase> | |
338 | </programlisting> | |
339 | <anchor id="class_fiber_id"/> | |
340 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h7"> | |
341 | <phrase id="fiber.fiber_mgmt.fiber_ids"/><link linkend="fiber.fiber_mgmt.fiber_ids">Fiber | |
342 | IDs</link> | |
343 | </bridgehead> | |
344 | <para> | |
345 | Objects of class <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase | |
346 | role="special">::</phrase><phrase role="identifier">id</phrase></code></link> can be | |
347 | used to identify fibers. Each running <link linkend="class_fiber"><code>fiber</code></link> has a unique <link linkend="class_fiber_id"><code><phrase | |
348 | role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase></code></link> obtainable | |
349 | from the corresponding <link linkend="class_fiber"><code>fiber</code></link> | |
350 | by calling the <link linkend="fiber_get_id"><code>fiber::get_id()</code></link> member | |
351 | function. Objects of class <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase | |
352 | role="special">::</phrase><phrase role="identifier">id</phrase></code></link> can be | |
353 | copied, and used as keys in associative containers: the full range of comparison | |
354 | operators is provided. They can also be written to an output stream using the | |
355 | stream insertion operator, though the output format is unspecified. | |
356 | </para> | |
357 | <para> | |
358 | Each instance of <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase | |
359 | role="special">::</phrase><phrase role="identifier">id</phrase></code></link> either | |
360 | refers to some fiber, or <emphasis>not-a-fiber</emphasis>. Instances that refer | |
361 | to <emphasis>not-a-fiber</emphasis> compare equal to each other, but not equal | |
362 | to any instances that refer to an actual fiber. The comparison operators on | |
363 | <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase | |
364 | role="identifier">id</phrase></code></link> yield a total order for every non-equal | |
365 | <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase | |
366 | role="identifier">id</phrase></code></link>. | |
367 | </para> | |
368 | <anchor id="class_launch"/> | |
369 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h8"> | |
370 | <phrase id="fiber.fiber_mgmt.enumeration__code__phrase_role__identifier__launch__phrase___code_"/><link | |
371 | linkend="fiber.fiber_mgmt.enumeration__code__phrase_role__identifier__launch__phrase___code_">Enumeration | |
372 | <code><phrase role="identifier">launch</phrase></code></link> | |
373 | </bridgehead> | |
374 | <para> | |
375 | <code><phrase role="identifier">launch</phrase></code> specifies whether control | |
376 | passes immediately into a newly-launched fiber. | |
377 | </para> | |
378 | <programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">launch</phrase> <phrase role="special">{</phrase> | |
379 | <phrase role="identifier">dispatch</phrase><phrase role="special">,</phrase> | |
380 | <phrase role="identifier">post</phrase> | |
381 | <phrase role="special">};</phrase> | |
382 | </programlisting> | |
383 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h9"> | |
384 | <phrase id="fiber.fiber_mgmt._code__phrase_role__identifier__dispatch__phrase___code_"/><link | |
385 | linkend="fiber.fiber_mgmt._code__phrase_role__identifier__dispatch__phrase___code_"><code><phrase | |
386 | role="identifier">dispatch</phrase></code></link> | |
387 | </bridgehead> | |
388 | <variablelist> | |
389 | <title></title> | |
390 | <varlistentry> | |
391 | <term>Effects:</term> | |
392 | <listitem> | |
393 | <para> | |
394 | A fiber launched with <code><phrase role="identifier">launch</phrase> | |
395 | <phrase role="special">==</phrase> <phrase role="identifier">dispatch</phrase></code> | |
396 | is entered immediately. In other words, launching a fiber with <code><phrase | |
397 | role="identifier">dispatch</phrase></code> suspends the caller (the previously-running | |
398 | fiber) until the fiber scheduler has a chance to resume it later. | |
399 | </para> | |
400 | </listitem> | |
401 | </varlistentry> | |
402 | </variablelist> | |
403 | <bridgehead renderas="sect3" id="fiber.fiber_mgmt.h10"> | |
404 | <phrase id="fiber.fiber_mgmt._code__phrase_role__identifier__post__phrase___code_"/><link | |
405 | linkend="fiber.fiber_mgmt._code__phrase_role__identifier__post__phrase___code_"><code><phrase | |
406 | role="identifier">post</phrase></code></link> | |
407 | </bridgehead> | |
408 | <variablelist> | |
409 | <title></title> | |
410 | <varlistentry> | |
411 | <term>Effects:</term> | |
412 | <listitem> | |
413 | <para> | |
414 | A fiber launched with <code><phrase role="identifier">launch</phrase> | |
415 | <phrase role="special">==</phrase> <phrase role="identifier">post</phrase></code> | |
416 | is passed to the fiber scheduler as ready, but it is not yet entered. | |
417 | The caller (the previously-running fiber) continues executing. The newly-launched | |
418 | fiber will be entered when the fiber scheduler has a chance to resume | |
419 | it later. | |
420 | </para> | |
421 | </listitem> | |
422 | </varlistentry> | |
423 | <varlistentry> | |
424 | <term>Note:</term> | |
425 | <listitem> | |
426 | <para> | |
427 | If <code><phrase role="identifier">launch</phrase></code> is not explicitly | |
428 | specified, <code><phrase role="identifier">post</phrase></code> is the | |
429 | default. | |
430 | </para> | |
431 | </listitem> | |
432 | </varlistentry> | |
433 | </variablelist> | |
434 | <section id="fiber.fiber_mgmt.fiber"> | |
435 | <title><anchor id="class_fiber"/><link linkend="fiber.fiber_mgmt.fiber">Class | |
436 | <code><phrase role="identifier">fiber</phrase></code></link></title> | |
437 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
438 | ||
439 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
440 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
441 | ||
442 | <phrase role="keyword">class</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">{</phrase> | |
443 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
444 | <phrase role="keyword">class</phrase> <phrase role="identifier">id</phrase><phrase role="special">;</phrase> | |
445 | ||
446 | <phrase role="keyword">constexpr</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
447 | ||
448 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
449 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...);</phrase> | |
450 | ||
451 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
452 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <link linkend="class_launch"><code><phrase role="identifier">launch</phrase></code></link><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...);</phrase> | |
453 | ||
454 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
455 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">StackAllocator</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...);</phrase> | |
456 | ||
457 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
458 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <link linkend="class_launch"><code><phrase role="identifier">launch</phrase></code></link><phrase role="special">,</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">StackAllocator</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...);</phrase> | |
459 | ||
460 | <phrase role="special">~</phrase><phrase role="identifier">fiber</phrase><phrase role="special">();</phrase> | |
461 | ||
462 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
463 | ||
464 | <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
465 | ||
466 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
467 | ||
468 | <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
469 | ||
470 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
471 | ||
472 | <phrase role="keyword">bool</phrase> <phrase role="identifier">joinable</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
473 | ||
474 | <phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
475 | ||
476 | <phrase role="keyword">void</phrase> <phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
477 | ||
478 | <phrase role="keyword">void</phrase> <phrase role="identifier">join</phrase><phrase role="special">();</phrase> | |
479 | ||
480 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase> | |
481 | <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase> | |
482 | <phrase role="special">};</phrase> | |
483 | ||
484 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
485 | ||
486 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
487 | ||
488 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">SchedAlgo</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
489 | <phrase role="keyword">void</phrase> <phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
490 | ||
491 | <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
492 | ||
493 | <phrase role="special">}}</phrase> | |
494 | </programlisting> | |
495 | <bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h0"> | |
496 | <phrase id="fiber.fiber_mgmt.fiber.default_constructor"/><link linkend="fiber.fiber_mgmt.fiber.default_constructor">Default | |
497 | constructor</link> | |
498 | </bridgehead> | |
499 | <programlisting><phrase role="keyword">constexpr</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
500 | </programlisting> | |
501 | <variablelist> | |
502 | <title></title> | |
503 | <varlistentry> | |
504 | <term>Effects:</term> | |
505 | <listitem> | |
506 | <para> | |
507 | Constructs a <link linkend="class_fiber"><code>fiber</code></link> instance that refers to <emphasis>not-a-fiber</emphasis>. | |
508 | </para> | |
509 | </listitem> | |
510 | </varlistentry> | |
511 | <varlistentry> | |
512 | <term>Postconditions:</term> | |
513 | <listitem> | |
514 | <para> | |
515 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
516 | role="identifier">get_id</phrase><phrase role="special">()</phrase> | |
517 | <phrase role="special">==</phrase> <phrase role="identifier">fiber</phrase><phrase | |
518 | role="special">::</phrase><phrase role="identifier">id</phrase><phrase | |
519 | role="special">()</phrase></code> | |
520 | </para> | |
521 | </listitem> | |
522 | </varlistentry> | |
523 | <varlistentry> | |
524 | <term>Throws:</term> | |
525 | <listitem> | |
526 | <para> | |
527 | Nothing | |
528 | </para> | |
529 | </listitem> | |
530 | </varlistentry> | |
531 | </variablelist> | |
532 | <anchor id="fiber_fiber"/> | |
533 | <bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h1"> | |
534 | <phrase id="fiber.fiber_mgmt.fiber.constructor"/><link linkend="fiber.fiber_mgmt.fiber.constructor">Constructor</link> | |
535 | </bridgehead> | |
536 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
537 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
538 | ||
539 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
540 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <link linkend="class_launch"><code><phrase role="identifier">launch</phrase></code></link> <phrase role="identifier">policy</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
541 | ||
542 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
543 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">StackAllocator</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
544 | ||
545 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
546 | <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <link linkend="class_launch"><code><phrase role="identifier">launch</phrase></code></link> <phrase role="identifier">policy</phrase><phrase role="special">,</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">StackAllocator</phrase> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> | |
547 | <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
548 | </programlisting> | |
549 | <variablelist> | |
550 | <title></title> | |
551 | <varlistentry> | |
552 | <term>Preconditions:</term> | |
553 | <listitem> | |
554 | <para> | |
555 | <code><phrase role="identifier">Fn</phrase></code> must be copyable | |
556 | or movable. | |
557 | </para> | |
558 | </listitem> | |
559 | </varlistentry> | |
560 | <varlistentry> | |
561 | <term>Effects:</term> | |
562 | <listitem> | |
563 | <para> | |
564 | <code><phrase role="identifier">fn</phrase></code> is copied or moved | |
565 | into internal storage for access by the new fiber. If <link linkend="class_launch"><code>launch</code></link> is | |
566 | specified (or defaulted) to <code><phrase role="identifier">post</phrase></code>, | |
567 | the new fiber is marked <quote>ready</quote> and will be entered at | |
568 | the next opportunity. If <code><phrase role="identifier">launch</phrase></code> | |
569 | is specified as <code><phrase role="identifier">dispatch</phrase></code>, | |
570 | the calling fiber is suspended and the new fiber is entered immediately. | |
571 | </para> | |
572 | </listitem> | |
573 | </varlistentry> | |
574 | <varlistentry> | |
575 | <term>Postconditions:</term> | |
576 | <listitem> | |
577 | <para> | |
578 | <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
579 | refers to the newly created fiber of execution. | |
580 | </para> | |
581 | </listitem> | |
582 | </varlistentry> | |
583 | <varlistentry> | |
584 | <term>Throws:</term> | |
585 | <listitem> | |
586 | <para> | |
587 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
588 | occurs. | |
589 | </para> | |
590 | </listitem> | |
591 | </varlistentry> | |
592 | <varlistentry> | |
593 | <term>Note:</term> | |
594 | <listitem> | |
595 | <para> | |
596 | <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link> | |
597 | is required to allocate a stack for the internal <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink>. | |
598 | If <code><phrase role="identifier">StackAllocator</phrase></code> is | |
599 | not explicitly passed, the default stack allocator depends on <code><phrase | |
600 | role="identifier">BOOST_USE_SEGMENTED_STACKS</phrase></code>: if defined, | |
601 | you will get a <link linkend="class_segmented_stack"><code>segmented_stack</code></link>, else a <link linkend="class_fixedsize_stack"><code>fixedsize_stack</code></link>. | |
602 | </para> | |
603 | </listitem> | |
604 | </varlistentry> | |
605 | <varlistentry> | |
606 | <term>See also:</term> | |
607 | <listitem> | |
608 | <para> | |
609 | <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase | |
610 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
611 | role="identifier">allocator_arg_t</phrase></code></ulink>, <link linkend="stack">Stack | |
612 | allocation</link> | |
613 | </para> | |
614 | </listitem> | |
615 | </varlistentry> | |
616 | </variablelist> | |
617 | <bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h2"> | |
618 | <phrase id="fiber.fiber_mgmt.fiber.move_constructor"/><link linkend="fiber.fiber_mgmt.fiber.move_constructor">Move | |
619 | constructor</link> | |
620 | </bridgehead> | |
621 | <programlisting><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
622 | </programlisting> | |
623 | <variablelist> | |
624 | <title></title> | |
625 | <varlistentry> | |
626 | <term>Effects:</term> | |
627 | <listitem> | |
628 | <para> | |
629 | Transfers ownership of the fiber managed by <code><phrase role="identifier">other</phrase></code> | |
630 | to the newly constructed <link linkend="class_fiber"><code>fiber</code></link> instance. | |
631 | </para> | |
632 | </listitem> | |
633 | </varlistentry> | |
634 | <varlistentry> | |
635 | <term>Postconditions:</term> | |
636 | <listitem> | |
637 | <para> | |
638 | <code><phrase role="identifier">other</phrase><phrase role="special">.</phrase><phrase | |
639 | role="identifier">get_id</phrase><phrase role="special">()</phrase> | |
640 | <phrase role="special">==</phrase> <phrase role="identifier">fiber</phrase><phrase | |
641 | role="special">::</phrase><phrase role="identifier">id</phrase><phrase | |
642 | role="special">()</phrase></code> and <code><phrase role="identifier">get_id</phrase><phrase | |
643 | role="special">()</phrase></code> returns the value of <code><phrase | |
644 | role="identifier">other</phrase><phrase role="special">.</phrase><phrase | |
645 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
646 | prior to the construction | |
647 | </para> | |
648 | </listitem> | |
649 | </varlistentry> | |
650 | <varlistentry> | |
651 | <term>Throws:</term> | |
652 | <listitem> | |
653 | <para> | |
654 | Nothing | |
655 | </para> | |
656 | </listitem> | |
657 | </varlistentry> | |
658 | </variablelist> | |
659 | <bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h3"> | |
660 | <phrase id="fiber.fiber_mgmt.fiber.move_assignment_operator"/><link linkend="fiber.fiber_mgmt.fiber.move_assignment_operator">Move | |
661 | assignment operator</link> | |
662 | </bridgehead> | |
663 | <programlisting><phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
664 | </programlisting> | |
665 | <variablelist> | |
666 | <title></title> | |
667 | <varlistentry> | |
668 | <term>Effects:</term> | |
669 | <listitem> | |
670 | <para> | |
671 | Transfers ownership of the fiber managed by <code><phrase role="identifier">other</phrase></code> | |
672 | (if any) to <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
673 | </para> | |
674 | </listitem> | |
675 | </varlistentry> | |
676 | <varlistentry> | |
677 | <term>Postconditions:</term> | |
678 | <listitem> | |
679 | <para> | |
680 | <code><phrase role="identifier">other</phrase><phrase role="special">-></phrase><phrase | |
681 | role="identifier">get_id</phrase><phrase role="special">()</phrase> | |
682 | <phrase role="special">==</phrase> <phrase role="identifier">fiber</phrase><phrase | |
683 | role="special">::</phrase><phrase role="identifier">id</phrase><phrase | |
684 | role="special">()</phrase></code> and <code><phrase role="identifier">get_id</phrase><phrase | |
685 | role="special">()</phrase></code> returns the value of <code><phrase | |
686 | role="identifier">other</phrase><phrase role="special">.</phrase><phrase | |
687 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
688 | prior to the assignment. | |
689 | </para> | |
690 | </listitem> | |
691 | </varlistentry> | |
692 | <varlistentry> | |
693 | <term>Throws:</term> | |
694 | <listitem> | |
695 | <para> | |
696 | Nothing | |
697 | </para> | |
698 | </listitem> | |
699 | </varlistentry> | |
700 | </variablelist> | |
701 | <bridgehead renderas="sect4" id="fiber.fiber_mgmt.fiber.h4"> | |
702 | <phrase id="fiber.fiber_mgmt.fiber.destructor"/><link linkend="fiber.fiber_mgmt.fiber.destructor">Destructor</link> | |
703 | </bridgehead> | |
704 | <programlisting><phrase role="special">~</phrase><phrase role="identifier">fiber</phrase><phrase role="special">();</phrase> | |
705 | </programlisting> | |
706 | <variablelist> | |
707 | <title></title> | |
708 | <varlistentry> | |
709 | <term>Effects:</term> | |
710 | <listitem> | |
711 | <para> | |
712 | If the fiber is <link linkend="fiber_joinable"><code>fiber::joinable()</code></link>, calls std::terminate. | |
713 | Destroys <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
714 | </para> | |
715 | </listitem> | |
716 | </varlistentry> | |
717 | <varlistentry> | |
718 | <term>Note:</term> | |
719 | <listitem> | |
720 | <para> | |
721 | The programmer must ensure that the destructor is never executed while | |
722 | the fiber is still <link linkend="fiber_joinable"><code>fiber::joinable()</code></link>. Even if you know | |
723 | that the fiber has completed, you must still call either <link linkend="fiber_join"><code>fiber::join()</code></link> or | |
724 | <link linkend="fiber_detach"><code>fiber::detach()</code></link> before destroying the <code><phrase role="identifier">fiber</phrase></code> | |
725 | object. | |
726 | </para> | |
727 | </listitem> | |
728 | </varlistentry> | |
729 | </variablelist> | |
730 | <para> | |
731 | <bridgehead renderas="sect4" id="fiber_joinable_bridgehead"> | |
732 | <phrase id="fiber_joinable"/> | |
733 | <link linkend="fiber_joinable">Member function <code>joinable</code>()</link> | |
734 | </bridgehead> | |
735 | </para> | |
736 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">joinable</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
737 | </programlisting> | |
738 | <variablelist> | |
739 | <title></title> | |
740 | <varlistentry> | |
741 | <term>Returns:</term> | |
742 | <listitem> | |
743 | <para> | |
744 | <code><phrase role="keyword">true</phrase></code> if <code><phrase | |
745 | role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
746 | refers to a fiber of execution, which may or may not have completed; | |
747 | otherwise <code><phrase role="keyword">false</phrase></code>. | |
748 | </para> | |
749 | </listitem> | |
750 | </varlistentry> | |
751 | <varlistentry> | |
752 | <term>Throws:</term> | |
753 | <listitem> | |
754 | <para> | |
755 | Nothing | |
756 | </para> | |
757 | </listitem> | |
758 | </varlistentry> | |
759 | </variablelist> | |
760 | <para> | |
761 | <bridgehead renderas="sect4" id="fiber_join_bridgehead"> | |
762 | <phrase id="fiber_join"/> | |
763 | <link linkend="fiber_join">Member function <code>join</code>()</link> | |
764 | </bridgehead> | |
765 | </para> | |
766 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">join</phrase><phrase role="special">();</phrase> | |
767 | </programlisting> | |
768 | <variablelist> | |
769 | <title></title> | |
770 | <varlistentry> | |
771 | <term>Preconditions:</term> | |
772 | <listitem> | |
773 | <para> | |
774 | the fiber is <link linkend="fiber_joinable"><code>fiber::joinable()</code></link>. | |
775 | </para> | |
776 | </listitem> | |
777 | </varlistentry> | |
778 | <varlistentry> | |
779 | <term>Effects:</term> | |
780 | <listitem> | |
781 | <para> | |
782 | Waits for the referenced fiber of execution to complete. | |
783 | </para> | |
784 | </listitem> | |
785 | </varlistentry> | |
786 | <varlistentry> | |
787 | <term>Postconditions:</term> | |
788 | <listitem> | |
789 | <para> | |
790 | The fiber of execution referenced on entry has completed. <code><phrase | |
791 | role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
792 | no longer refers to any fiber of execution. | |
793 | </para> | |
794 | </listitem> | |
795 | </varlistentry> | |
796 | <varlistentry> | |
797 | <term>Throws:</term> | |
798 | <listitem> | |
799 | <para> | |
800 | <code><phrase role="identifier">fiber_error</phrase></code> | |
801 | </para> | |
802 | </listitem> | |
803 | </varlistentry> | |
804 | <varlistentry> | |
805 | <term>Error Conditions:</term> | |
806 | <listitem> | |
807 | <para> | |
808 | <emphasis role="bold">resource_deadlock_would_occur</emphasis>: if | |
809 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
810 | role="identifier">get_id</phrase><phrase role="special">()</phrase> | |
811 | <phrase role="special">==</phrase> <phrase role="identifier">boost</phrase><phrase | |
812 | role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase | |
813 | role="special">::</phrase><phrase role="identifier">get_id</phrase><phrase | |
814 | role="special">()</phrase></code>. <emphasis role="bold">invalid_argument</emphasis>: | |
815 | if the fiber is not <link linkend="fiber_joinable"><code>fiber::joinable()</code></link>. | |
816 | </para> | |
817 | </listitem> | |
818 | </varlistentry> | |
819 | </variablelist> | |
820 | <para> | |
821 | <bridgehead renderas="sect4" id="fiber_detach_bridgehead"> | |
822 | <phrase id="fiber_detach"/> | |
823 | <link linkend="fiber_detach">Member function <code>detach</code>()</link> | |
824 | </bridgehead> | |
825 | </para> | |
826 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
827 | </programlisting> | |
828 | <variablelist> | |
829 | <title></title> | |
830 | <varlistentry> | |
831 | <term>Preconditions:</term> | |
832 | <listitem> | |
833 | <para> | |
834 | the fiber is <link linkend="fiber_joinable"><code>fiber::joinable()</code></link>. | |
835 | </para> | |
836 | </listitem> | |
837 | </varlistentry> | |
838 | <varlistentry> | |
839 | <term>Effects:</term> | |
840 | <listitem> | |
841 | <para> | |
842 | The fiber of execution becomes detached, and no longer has an associated | |
843 | <link linkend="class_fiber"><code>fiber</code></link> object. | |
844 | </para> | |
845 | </listitem> | |
846 | </varlistentry> | |
847 | <varlistentry> | |
848 | <term>Postconditions:</term> | |
849 | <listitem> | |
850 | <para> | |
851 | <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
852 | no longer refers to any fiber of execution. | |
853 | </para> | |
854 | </listitem> | |
855 | </varlistentry> | |
856 | <varlistentry> | |
857 | <term>Throws:</term> | |
858 | <listitem> | |
859 | <para> | |
860 | <code><phrase role="identifier">fiber_error</phrase></code> | |
861 | </para> | |
862 | </listitem> | |
863 | </varlistentry> | |
864 | <varlistentry> | |
865 | <term>Error Conditions:</term> | |
866 | <listitem> | |
867 | <para> | |
868 | <emphasis role="bold">invalid_argument</emphasis>: if the fiber is | |
869 | not <link linkend="fiber_joinable"><code>fiber::joinable()</code></link>. | |
870 | </para> | |
871 | </listitem> | |
872 | </varlistentry> | |
873 | </variablelist> | |
874 | <para> | |
875 | <bridgehead renderas="sect4" id="fiber_get_id_bridgehead"> | |
876 | <phrase id="fiber_get_id"/> | |
877 | <link linkend="fiber_get_id">Member function <code>get_id</code>()</link> | |
878 | </bridgehead> | |
879 | </para> | |
880 | <programlisting><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
881 | </programlisting> | |
882 | <variablelist> | |
883 | <title></title> | |
884 | <varlistentry> | |
885 | <term>Returns:</term> | |
886 | <listitem> | |
887 | <para> | |
888 | If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
889 | refers to a fiber of execution, an instance of <link linkend="class_fiber_id"><code><phrase | |
890 | role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase | |
891 | role="identifier">id</phrase></code></link> that represents that fiber. Otherwise | |
892 | returns a default-constructed <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase | |
893 | role="special">::</phrase><phrase role="identifier">id</phrase></code></link>. | |
894 | </para> | |
895 | </listitem> | |
896 | </varlistentry> | |
897 | <varlistentry> | |
898 | <term>Throws:</term> | |
899 | <listitem> | |
900 | <para> | |
901 | Nothing | |
902 | </para> | |
903 | </listitem> | |
904 | </varlistentry> | |
905 | <varlistentry> | |
906 | <term>See also:</term> | |
907 | <listitem> | |
908 | <para> | |
909 | <link linkend="this_fiber_get_id"><code>this_fiber::get_id()</code></link> | |
910 | </para> | |
911 | </listitem> | |
912 | </varlistentry> | |
913 | </variablelist> | |
914 | <para> | |
915 | <bridgehead renderas="sect4" id="fiber_properties_bridgehead"> | |
916 | <phrase id="fiber_properties"/> | |
917 | <link linkend="fiber_properties">Templated member | |
918 | function <code>properties</code>()</link> | |
919 | </bridgehead> | |
920 | </para> | |
921 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase> | |
922 | <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase> | |
923 | </programlisting> | |
924 | <variablelist> | |
925 | <title></title> | |
926 | <varlistentry> | |
927 | <term>Preconditions:</term> | |
928 | <listitem> | |
929 | <para> | |
930 | <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
931 | refers to a fiber of execution. <link linkend="use_scheduling_algorithm"><code>use_scheduling_algorithm()</code></link> has | |
932 | been called from this thread with a subclass of <link linkend="class_algorithm_with_properties"><code>algorithm_with_properties<></code></link> with | |
933 | the same template argument <code><phrase role="identifier">PROPS</phrase></code>. | |
934 | </para> | |
935 | </listitem> | |
936 | </varlistentry> | |
937 | <varlistentry> | |
938 | <term>Returns:</term> | |
939 | <listitem> | |
940 | <para> | |
941 | a reference to the scheduler properties instance for <code><phrase | |
942 | role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
943 | </para> | |
944 | </listitem> | |
945 | </varlistentry> | |
946 | <varlistentry> | |
947 | <term>Throws:</term> | |
948 | <listitem> | |
949 | <para> | |
950 | <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
951 | role="identifier">bad_cast</phrase></code> if <code><phrase role="identifier">use_scheduling_algorithm</phrase><phrase | |
952 | role="special">()</phrase></code> was called with a <code><phrase role="identifier">algorithm_with_properties</phrase></code> | |
953 | subclass with some other template parameter than <code><phrase role="identifier">PROPS</phrase></code>. | |
954 | </para> | |
955 | </listitem> | |
956 | </varlistentry> | |
957 | <varlistentry> | |
958 | <term>Note:</term> | |
959 | <listitem> | |
960 | <para> | |
961 | <link linkend="class_algorithm_with_properties"><code>algorithm_with_properties<></code></link> provides | |
962 | a way for a user-coded scheduler to associate extended properties, | |
963 | such as priority, with a fiber instance. This method allows access | |
964 | to those user-provided properties. | |
965 | </para> | |
966 | </listitem> | |
967 | </varlistentry> | |
968 | <varlistentry> | |
969 | <term>See also:</term> | |
970 | <listitem> | |
971 | <para> | |
972 | <link linkend="custom">Customization</link> | |
973 | </para> | |
974 | </listitem> | |
975 | </varlistentry> | |
976 | </variablelist> | |
977 | <para> | |
978 | <bridgehead renderas="sect4" id="fiber_swap_bridgehead"> | |
979 | <phrase id="fiber_swap"/> | |
980 | <link linkend="fiber_swap">Member function <code>swap</code>()</link> | |
981 | </bridgehead> | |
982 | </para> | |
983 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
984 | </programlisting> | |
985 | <variablelist> | |
986 | <title></title> | |
987 | <varlistentry> | |
988 | <term>Effects:</term> | |
989 | <listitem> | |
990 | <para> | |
991 | Exchanges the fiber of execution associated with <code><phrase role="special">*</phrase><phrase | |
992 | role="keyword">this</phrase></code> and <code><phrase role="identifier">other</phrase></code>, | |
993 | so <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
994 | becomes associated with the fiber formerly associated with <code><phrase | |
995 | role="identifier">other</phrase></code>, and vice-versa. | |
996 | </para> | |
997 | </listitem> | |
998 | </varlistentry> | |
999 | <varlistentry> | |
1000 | <term>Postconditions:</term> | |
1001 | <listitem> | |
1002 | <para> | |
1003 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
1004 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
1005 | returns the same value as <code><phrase role="identifier">other</phrase><phrase | |
1006 | role="special">.</phrase><phrase role="identifier">get_id</phrase><phrase | |
1007 | role="special">()</phrase></code> prior to the call. <code><phrase | |
1008 | role="identifier">other</phrase><phrase role="special">.</phrase><phrase | |
1009 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
1010 | returns the same value as <code><phrase role="keyword">this</phrase><phrase | |
1011 | role="special">-></phrase><phrase role="identifier">get_id</phrase><phrase | |
1012 | role="special">()</phrase></code> prior to the call. | |
1013 | </para> | |
1014 | </listitem> | |
1015 | </varlistentry> | |
1016 | <varlistentry> | |
1017 | <term>Throws:</term> | |
1018 | <listitem> | |
1019 | <para> | |
1020 | Nothing | |
1021 | </para> | |
1022 | </listitem> | |
1023 | </varlistentry> | |
1024 | </variablelist> | |
1025 | <para> | |
1026 | <bridgehead renderas="sect4" id="swap_for_fiber_bridgehead"> | |
1027 | <phrase id="swap_for_fiber"/> | |
1028 | <link linkend="swap_for_fiber">Non-member function | |
1029 | <code>swap()</code></link> | |
1030 | </bridgehead> | |
1031 | </para> | |
1032 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1033 | </programlisting> | |
1034 | <variablelist> | |
1035 | <title></title> | |
1036 | <varlistentry> | |
1037 | <term>Effects:</term> | |
1038 | <listitem> | |
1039 | <para> | |
1040 | Same as <code><phrase role="identifier">l</phrase><phrase role="special">.</phrase><phrase | |
1041 | role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase | |
1042 | role="identifier">r</phrase><phrase role="special">)</phrase></code>. | |
1043 | </para> | |
1044 | </listitem> | |
1045 | </varlistentry> | |
1046 | <varlistentry> | |
1047 | <term>Throws:</term> | |
1048 | <listitem> | |
1049 | <para> | |
1050 | Nothing | |
1051 | </para> | |
1052 | </listitem> | |
1053 | </varlistentry> | |
1054 | </variablelist> | |
1055 | <para> | |
1056 | <bridgehead renderas="sect4" id="operator<_bridgehead"> | |
1057 | <phrase id="operator<"/> | |
1058 | <link linkend="operator<">Non-member function <code>operator<()</code></link> | |
1059 | </bridgehead> | |
1060 | </para> | |
1061 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">fiber</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1062 | </programlisting> | |
1063 | <variablelist> | |
1064 | <title></title> | |
1065 | <varlistentry> | |
1066 | <term>Returns:</term> | |
1067 | <listitem> | |
1068 | <para> | |
1069 | <code><phrase role="keyword">true</phrase></code> if <code><phrase | |
1070 | role="identifier">l</phrase><phrase role="special">.</phrase><phrase | |
1071 | role="identifier">get_id</phrase><phrase role="special">()</phrase> | |
1072 | <phrase role="special"><</phrase> <phrase role="identifier">r</phrase><phrase | |
1073 | role="special">.</phrase><phrase role="identifier">get_id</phrase><phrase | |
1074 | role="special">()</phrase></code> is <code><phrase role="keyword">true</phrase></code>, | |
1075 | false otherwise. | |
1076 | </para> | |
1077 | </listitem> | |
1078 | </varlistentry> | |
1079 | <varlistentry> | |
1080 | <term>Throws:</term> | |
1081 | <listitem> | |
1082 | <para> | |
1083 | Nothing. | |
1084 | </para> | |
1085 | </listitem> | |
1086 | </varlistentry> | |
1087 | </variablelist> | |
1088 | <para> | |
1089 | <bridgehead renderas="sect4" id="use_scheduling_algorithm_bridgehead"> | |
1090 | <phrase id="use_scheduling_algorithm"/> | |
1091 | <link linkend="use_scheduling_algorithm">Non-member | |
1092 | function <code>use_scheduling_algorithm()</code></link> | |
1093 | </bridgehead> | |
1094 | </para> | |
1095 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">SchedAlgo</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
1096 | <phrase role="keyword">void</phrase> <phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special">(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1097 | </programlisting> | |
1098 | <variablelist> | |
1099 | <title></title> | |
1100 | <varlistentry> | |
1101 | <term>Effects:</term> | |
1102 | <listitem> | |
1103 | <para> | |
1104 | Directs <emphasis role="bold">Boost.Fiber</emphasis> to use <code><phrase | |
1105 | role="identifier">SchedAlgo</phrase></code>, which must be a concrete | |
1106 | subclass of <link linkend="class_algorithm"><code>algorithm</code></link>, as the scheduling algorithm for | |
1107 | all fibers in the current thread. Pass any required <code><phrase role="identifier">SchedAlgo</phrase></code> | |
1108 | constructor arguments as <code><phrase role="identifier">args</phrase></code>. | |
1109 | </para> | |
1110 | </listitem> | |
1111 | </varlistentry> | |
1112 | <varlistentry> | |
1113 | <term>Note:</term> | |
1114 | <listitem> | |
1115 | <para> | |
1116 | If you want a given thread to use a non-default scheduling algorithm, | |
1117 | make that thread call <code><phrase role="identifier">use_scheduling_algorithm</phrase><phrase | |
1118 | role="special">()</phrase></code> before any other <emphasis role="bold">Boost.Fiber</emphasis> | |
1119 | entry point. If no scheduler has been set for the current thread by | |
1120 | the time <emphasis role="bold">Boost.Fiber</emphasis> needs to use | |
1121 | it, the library will create a default <link linkend="class_round_robin"><code>round_robin</code></link> instance | |
1122 | for this thread. | |
1123 | </para> | |
1124 | </listitem> | |
1125 | </varlistentry> | |
1126 | <varlistentry> | |
1127 | <term>Throws:</term> | |
1128 | <listitem> | |
1129 | <para> | |
1130 | Nothing | |
1131 | </para> | |
1132 | </listitem> | |
1133 | </varlistentry> | |
1134 | <varlistentry> | |
1135 | <term>See also:</term> | |
1136 | <listitem> | |
1137 | <para> | |
1138 | <link linkend="scheduling">Scheduling</link>, <link linkend="custom">Customization</link> | |
1139 | </para> | |
1140 | </listitem> | |
1141 | </varlistentry> | |
1142 | </variablelist> | |
1143 | <para> | |
1144 | <bridgehead renderas="sect4" id="has_ready_fibers_bridgehead"> | |
1145 | <phrase id="has_ready_fibers"/> | |
1146 | <link linkend="has_ready_fibers">Non-member function | |
1147 | <code>has_ready_fibers()</code></link> | |
1148 | </bridgehead> | |
1149 | </para> | |
1150 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1151 | </programlisting> | |
1152 | <variablelist> | |
1153 | <title></title> | |
1154 | <varlistentry> | |
1155 | <term>Returns:</term> | |
1156 | <listitem> | |
1157 | <para> | |
1158 | <code><phrase role="keyword">true</phrase></code> if scheduler has | |
1159 | fibers ready to run. | |
1160 | </para> | |
1161 | </listitem> | |
1162 | </varlistentry> | |
1163 | <varlistentry> | |
1164 | <term>Throws:</term> | |
1165 | <listitem> | |
1166 | <para> | |
1167 | Nothing | |
1168 | </para> | |
1169 | </listitem> | |
1170 | </varlistentry> | |
1171 | <varlistentry> | |
1172 | <term>Note:</term> | |
1173 | <listitem> | |
1174 | <para> | |
1175 | Can be used for work-stealing to find an idle scheduler. | |
1176 | </para> | |
1177 | </listitem> | |
1178 | </varlistentry> | |
1179 | </variablelist> | |
1180 | </section> | |
1181 | <section id="fiber.fiber_mgmt.id"> | |
1182 | <title><anchor id="class_id"/><link linkend="fiber.fiber_mgmt.id">Class fiber::id</link></title> | |
1183 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
1184 | ||
1185 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1186 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
1187 | ||
1188 | <phrase role="keyword">class</phrase> <phrase role="identifier">id</phrase> <phrase role="special">{</phrase> | |
1189 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
1190 | <phrase role="keyword">constexpr</phrase> <phrase role="identifier">id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1191 | ||
1192 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">==(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1193 | ||
1194 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1195 | ||
1196 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1197 | ||
1198 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1199 | ||
1200 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1201 | ||
1202 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1203 | ||
1204 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> | |
1205 | <phrase role="keyword">friend</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> | |
1206 | <phrase role="keyword">operator</phrase><phrase role="special"><<(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&,</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> | |
1207 | <phrase role="special">};</phrase> | |
1208 | ||
1209 | <phrase role="special">}}</phrase> | |
1210 | </programlisting> | |
1211 | <bridgehead renderas="sect4" id="fiber.fiber_mgmt.id.h0"> | |
1212 | <phrase id="fiber.fiber_mgmt.id.constructor"/><link linkend="fiber.fiber_mgmt.id.constructor">Constructor</link> | |
1213 | </bridgehead> | |
1214 | <programlisting><phrase role="keyword">constexpr</phrase> <phrase role="identifier">id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1215 | </programlisting> | |
1216 | <variablelist> | |
1217 | <title></title> | |
1218 | <varlistentry> | |
1219 | <term>Effects:</term> | |
1220 | <listitem> | |
1221 | <para> | |
1222 | Represents an instance of <emphasis>not-a-fiber</emphasis>. | |
1223 | </para> | |
1224 | </listitem> | |
1225 | </varlistentry> | |
1226 | <varlistentry> | |
1227 | <term>Throws:</term> | |
1228 | <listitem> | |
1229 | <para> | |
1230 | Nothing. | |
1231 | </para> | |
1232 | </listitem> | |
1233 | </varlistentry> | |
1234 | </variablelist> | |
1235 | <para> | |
1236 | <bridgehead renderas="sect4" id="id_operator_equal_bridgehead"> | |
1237 | <phrase id="id_operator_equal"/> | |
1238 | <link linkend="id_operator_equal">Member function | |
1239 | <code>operator==</code>()</link> | |
1240 | </bridgehead> | |
1241 | </para> | |
1242 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">==(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1243 | </programlisting> | |
1244 | <variablelist> | |
1245 | <title></title> | |
1246 | <varlistentry> | |
1247 | <term>Returns:</term> | |
1248 | <listitem> | |
1249 | <para> | |
1250 | <code><phrase role="keyword">true</phrase></code> if <code><phrase | |
1251 | role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
1252 | and <code><phrase role="identifier">other</phrase></code> represent | |
1253 | the same fiber, or both represent <emphasis>not-a-fiber</emphasis>, | |
1254 | <code><phrase role="keyword">false</phrase></code> otherwise. | |
1255 | </para> | |
1256 | </listitem> | |
1257 | </varlistentry> | |
1258 | <varlistentry> | |
1259 | <term>Throws:</term> | |
1260 | <listitem> | |
1261 | <para> | |
1262 | Nothing. | |
1263 | </para> | |
1264 | </listitem> | |
1265 | </varlistentry> | |
1266 | </variablelist> | |
1267 | <para> | |
1268 | <bridgehead renderas="sect4" id="id_operator_not_equal_bridgehead"> | |
1269 | <phrase id="id_operator_not_equal"/> | |
1270 | <link linkend="id_operator_not_equal">Member | |
1271 | function <code>operator!=</code>()</link> | |
1272 | </bridgehead> | |
1273 | </para> | |
1274 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">!=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1275 | </programlisting> | |
1276 | <variablelist> | |
1277 | <title></title> | |
1278 | <varlistentry> | |
1279 | <term>Returns:</term> | |
1280 | <listitem> | |
1281 | <para> | |
1282 | <code>! (other == * this)</code> | |
1283 | </para> | |
1284 | </listitem> | |
1285 | </varlistentry> | |
1286 | <varlistentry> | |
1287 | <term>Throws:</term> | |
1288 | <listitem> | |
1289 | <para> | |
1290 | Nothing. | |
1291 | </para> | |
1292 | </listitem> | |
1293 | </varlistentry> | |
1294 | </variablelist> | |
1295 | <para> | |
1296 | <bridgehead renderas="sect4" id="id_operator_less_bridgehead"> | |
1297 | <phrase id="id_operator_less"/> | |
1298 | <link linkend="id_operator_less">Member function | |
1299 | <code>operator<</code>()</link> | |
1300 | </bridgehead> | |
1301 | </para> | |
1302 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1303 | </programlisting> | |
1304 | <variablelist> | |
1305 | <title></title> | |
1306 | <varlistentry> | |
1307 | <term>Returns:</term> | |
1308 | <listitem> | |
1309 | <para> | |
1310 | <code><phrase role="keyword">true</phrase></code> if <code><phrase | |
1311 | role="special">*</phrase><phrase role="keyword">this</phrase> <phrase | |
1312 | role="special">!=</phrase> <phrase role="identifier">other</phrase></code> | |
1313 | is true and the implementation-defined total order of <code><phrase | |
1314 | role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase | |
1315 | role="identifier">id</phrase></code> values places <code><phrase role="special">*</phrase><phrase | |
1316 | role="keyword">this</phrase></code> before <code><phrase role="identifier">other</phrase></code>, | |
1317 | false otherwise. | |
1318 | </para> | |
1319 | </listitem> | |
1320 | </varlistentry> | |
1321 | <varlistentry> | |
1322 | <term>Throws:</term> | |
1323 | <listitem> | |
1324 | <para> | |
1325 | Nothing. | |
1326 | </para> | |
1327 | </listitem> | |
1328 | </varlistentry> | |
1329 | </variablelist> | |
1330 | <para> | |
1331 | <bridgehead renderas="sect4" id="id_operator_greater_bridgehead"> | |
1332 | <phrase id="id_operator_greater"/> | |
1333 | <link linkend="id_operator_greater">Member | |
1334 | function <code>operator></code>()</link> | |
1335 | </bridgehead> | |
1336 | </para> | |
1337 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1338 | </programlisting> | |
1339 | <variablelist> | |
1340 | <title></title> | |
1341 | <varlistentry> | |
1342 | <term>Returns:</term> | |
1343 | <listitem> | |
1344 | <para> | |
1345 | <code><phrase role="identifier">other</phrase> <phrase role="special"><</phrase> | |
1346 | <phrase role="special">*</phrase> <phrase role="keyword">this</phrase></code> | |
1347 | </para> | |
1348 | </listitem> | |
1349 | </varlistentry> | |
1350 | <varlistentry> | |
1351 | <term>Throws:</term> | |
1352 | <listitem> | |
1353 | <para> | |
1354 | Nothing. | |
1355 | </para> | |
1356 | </listitem> | |
1357 | </varlistentry> | |
1358 | </variablelist> | |
1359 | <para> | |
1360 | <bridgehead renderas="sect4" id="id_operator_less_equal_bridgehead"> | |
1361 | <phrase id="id_operator_less_equal"/> | |
1362 | <link linkend="id_operator_less_equal">Member | |
1363 | function <code>operator<=</code>()</link> | |
1364 | </bridgehead> | |
1365 | </para> | |
1366 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1367 | </programlisting> | |
1368 | <variablelist> | |
1369 | <title></title> | |
1370 | <varlistentry> | |
1371 | <term>Returns:</term> | |
1372 | <listitem> | |
1373 | <para> | |
1374 | <code><phrase role="special">!</phrase> <phrase role="special">(</phrase><phrase | |
1375 | role="identifier">other</phrase> <phrase role="special"><</phrase> | |
1376 | <phrase role="special">*</phrase> <phrase role="keyword">this</phrase><phrase | |
1377 | role="special">)</phrase></code> | |
1378 | </para> | |
1379 | </listitem> | |
1380 | </varlistentry> | |
1381 | <varlistentry> | |
1382 | <term>Throws:</term> | |
1383 | <listitem> | |
1384 | <para> | |
1385 | Nothing. | |
1386 | </para> | |
1387 | </listitem> | |
1388 | </varlistentry> | |
1389 | </variablelist> | |
1390 | <para> | |
1391 | <bridgehead renderas="sect4" id="id_operator_greater_equal_bridgehead"> | |
1392 | <phrase id="id_operator_greater_equal"/> | |
1393 | <link linkend="id_operator_greater_equal">Member | |
1394 | function <code>operator>=</code>()</link> | |
1395 | </bridgehead> | |
1396 | </para> | |
1397 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special">>=(</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1398 | </programlisting> | |
1399 | <variablelist> | |
1400 | <title></title> | |
1401 | <varlistentry> | |
1402 | <term>Returns:</term> | |
1403 | <listitem> | |
1404 | <para> | |
1405 | <code><phrase role="special">!</phrase> <phrase role="special">(*</phrase> | |
1406 | <phrase role="keyword">this</phrase> <phrase role="special"><</phrase> | |
1407 | <phrase role="identifier">other</phrase><phrase role="special">)</phrase></code> | |
1408 | </para> | |
1409 | </listitem> | |
1410 | </varlistentry> | |
1411 | <varlistentry> | |
1412 | <term>Throws:</term> | |
1413 | <listitem> | |
1414 | <para> | |
1415 | Nothing. | |
1416 | </para> | |
1417 | </listitem> | |
1418 | </varlistentry> | |
1419 | </variablelist> | |
1420 | <bridgehead renderas="sect4" id="fiber.fiber_mgmt.id.h1"> | |
1421 | <phrase id="fiber.fiber_mgmt.id.operator_lt__lt_"/><link linkend="fiber.fiber_mgmt.id.operator_lt__lt_">operator<<</link> | |
1422 | </bridgehead> | |
1423 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> | |
1424 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> | |
1425 | <phrase role="keyword">operator</phrase><phrase role="special"><<(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">basic_ostream</phrase><phrase role="special"><</phrase> <phrase role="identifier">charT</phrase><phrase role="special">,</phrase> <phrase role="identifier">traitsT</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">os</phrase><phrase role="special">,</phrase> <phrase role="identifier">id</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">);</phrase> | |
1426 | </programlisting> | |
1427 | <variablelist> | |
1428 | <title></title> | |
1429 | <varlistentry> | |
1430 | <term>Efects:</term> | |
1431 | <listitem> | |
1432 | <para> | |
1433 | Writes the representation of <code><phrase role="identifier">other</phrase></code> | |
1434 | to stream <code><phrase role="identifier">os</phrase></code>. The representation | |
1435 | is unspecified. | |
1436 | </para> | |
1437 | </listitem> | |
1438 | </varlistentry> | |
1439 | <varlistentry> | |
1440 | <term>Returns:</term> | |
1441 | <listitem> | |
1442 | <para> | |
1443 | <code><phrase role="identifier">os</phrase></code> | |
1444 | </para> | |
1445 | </listitem> | |
1446 | </varlistentry> | |
1447 | </variablelist> | |
1448 | </section> | |
1449 | <section id="fiber.fiber_mgmt.this_fiber"> | |
1450 | <title><link linkend="fiber.fiber_mgmt.this_fiber">Namespace this_fiber</link></title> | |
1451 | <para> | |
1452 | In general, <code><phrase role="identifier">this_fiber</phrase></code> operations | |
1453 | may be called from the <quote>main</quote> fiber — the fiber on which function | |
1454 | <code><phrase role="identifier">main</phrase><phrase role="special">()</phrase></code> | |
1455 | is entered — as well as from an explicitly-launched thread’s thread-function. | |
1456 | That is, in many respects the main fiber on each thread can be treated like | |
1457 | an explicitly-launched fiber. | |
1458 | </para> | |
1459 | <programlisting><phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1460 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">this_fiber</phrase> <phrase role="special">{</phrase> | |
1461 | ||
1462 | <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1463 | <phrase role="keyword">void</phrase> <phrase role="identifier">yield</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1464 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
1465 | <phrase role="keyword">void</phrase> <phrase role="identifier">sleep_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> | |
1466 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
1467 | <phrase role="keyword">void</phrase> <phrase role="identifier">sleep_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> | |
1468 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase> | |
1469 | <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase> | |
1470 | ||
1471 | <phrase role="special">}}</phrase> | |
1472 | </programlisting> | |
1473 | <para> | |
1474 | <bridgehead renderas="sect4" id="this_fiber_get_id_bridgehead"> | |
1475 | <phrase id="this_fiber_get_id"/> | |
1476 | <link linkend="this_fiber_get_id">Non-member | |
1477 | function <code>this_fiber::get_id()</code></link> | |
1478 | </bridgehead> | |
1479 | </para> | |
1480 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
1481 | ||
1482 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1483 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
1484 | ||
1485 | <phrase role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1486 | ||
1487 | <phrase role="special">}}</phrase> | |
1488 | </programlisting> | |
1489 | <variablelist> | |
1490 | <title></title> | |
1491 | <varlistentry> | |
1492 | <term>Returns:</term> | |
1493 | <listitem> | |
1494 | <para> | |
1495 | An instance of <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase | |
1496 | role="special">::</phrase><phrase role="identifier">id</phrase></code></link> that | |
1497 | represents the currently executing fiber. | |
1498 | </para> | |
1499 | </listitem> | |
1500 | </varlistentry> | |
1501 | <varlistentry> | |
1502 | <term>Throws:</term> | |
1503 | <listitem> | |
1504 | <para> | |
1505 | Nothing. | |
1506 | </para> | |
1507 | </listitem> | |
1508 | </varlistentry> | |
1509 | </variablelist> | |
1510 | <para> | |
1511 | <bridgehead renderas="sect4" id="this_fiber_sleep_until_bridgehead"> | |
1512 | <phrase id="this_fiber_sleep_until"/> | |
1513 | <link linkend="this_fiber_sleep_until">Non-member | |
1514 | function <code>this_fiber::sleep_until()</code></link> | |
1515 | </bridgehead> | |
1516 | </para> | |
1517 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
1518 | ||
1519 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1520 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
1521 | ||
1522 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
1523 | <phrase role="keyword">void</phrase> <phrase role="identifier">sleep_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">);</phrase> | |
1524 | ||
1525 | <phrase role="special">}}</phrase> | |
1526 | </programlisting> | |
1527 | <variablelist> | |
1528 | <title></title> | |
1529 | <varlistentry> | |
1530 | <term>Effects:</term> | |
1531 | <listitem> | |
1532 | <para> | |
1533 | Suspends the current fiber until the time point specified by <code><phrase | |
1534 | role="identifier">abs_time</phrase></code> has been reached. | |
1535 | </para> | |
1536 | </listitem> | |
1537 | </varlistentry> | |
1538 | <varlistentry> | |
1539 | <term>Throws:</term> | |
1540 | <listitem> | |
1541 | <para> | |
1542 | timeout-related exceptions. | |
1543 | </para> | |
1544 | </listitem> | |
1545 | </varlistentry> | |
1546 | <varlistentry> | |
1547 | <term>Note:</term> | |
1548 | <listitem> | |
1549 | <para> | |
1550 | The current fiber will not resume before <code><phrase role="identifier">abs_time</phrase></code>, | |
1551 | but there are no guarantees about how soon after <code><phrase role="identifier">abs_time</phrase></code> | |
1552 | it might resume. | |
1553 | </para> | |
1554 | </listitem> | |
1555 | </varlistentry> | |
1556 | <varlistentry> | |
1557 | <term>Note:</term> | |
1558 | <listitem> | |
1559 | <para> | |
1560 | <quote>timeout-related exceptions</quote> are as defined in the C++ | |
1561 | Standard, section <emphasis role="bold">30.2.4 Timing specifications | |
1562 | [thread.req.timing]</emphasis>: <quote>A function that takes an argument | |
1563 | which specifies a timeout will throw if, during its execution, a clock, | |
1564 | time point, or time duration throws an exception. Such exceptions are | |
1565 | referred to as <emphasis>timeout-related exceptions.</emphasis></quote> | |
1566 | </para> | |
1567 | </listitem> | |
1568 | </varlistentry> | |
1569 | </variablelist> | |
1570 | <para> | |
1571 | <bridgehead renderas="sect4" id="this_fiber_sleep_for_bridgehead"> | |
1572 | <phrase id="this_fiber_sleep_for"/> | |
1573 | <link linkend="this_fiber_sleep_for">Non-member | |
1574 | function <code>this_fiber::sleep_for()</code></link> | |
1575 | </bridgehead> | |
1576 | </para> | |
1577 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
1578 | ||
1579 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1580 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
1581 | ||
1582 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
1583 | <phrase role="keyword">void</phrase> <phrase role="identifier">sleep_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">);</phrase> | |
1584 | ||
1585 | <phrase role="special">}}</phrase> | |
1586 | </programlisting> | |
1587 | <variablelist> | |
1588 | <title></title> | |
1589 | <varlistentry> | |
1590 | <term>Effects:</term> | |
1591 | <listitem> | |
1592 | <para> | |
1593 | Suspends the current fiber until the time duration specified by <code><phrase | |
1594 | role="identifier">rel_time</phrase></code> has elapsed. | |
1595 | </para> | |
1596 | </listitem> | |
1597 | </varlistentry> | |
1598 | <varlistentry> | |
1599 | <term>Throws:</term> | |
1600 | <listitem> | |
1601 | <para> | |
1602 | timeout-related exceptions. | |
1603 | </para> | |
1604 | </listitem> | |
1605 | </varlistentry> | |
1606 | <varlistentry> | |
1607 | <term>Note:</term> | |
1608 | <listitem> | |
1609 | <para> | |
1610 | The current fiber will not resume before <code><phrase role="identifier">rel_time</phrase></code> | |
1611 | has elapsed, but there are no guarantees about how soon after that | |
1612 | it might resume. | |
1613 | </para> | |
1614 | </listitem> | |
1615 | </varlistentry> | |
1616 | </variablelist> | |
1617 | <para> | |
1618 | <bridgehead renderas="sect4" id="this_fiber_yield_bridgehead"> | |
1619 | <phrase id="this_fiber_yield"/> | |
1620 | <link linkend="this_fiber_yield">Non-member function | |
1621 | <code>this_fiber::yield()</code></link> | |
1622 | </bridgehead> | |
1623 | </para> | |
1624 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
1625 | ||
1626 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1627 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
1628 | ||
1629 | <phrase role="keyword">void</phrase> <phrase role="identifier">yield</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
1630 | ||
1631 | <phrase role="special">}}</phrase> | |
1632 | </programlisting> | |
1633 | <variablelist> | |
1634 | <title></title> | |
1635 | <varlistentry> | |
1636 | <term>Effects:</term> | |
1637 | <listitem> | |
1638 | <para> | |
1639 | Reliquishes execution control, allowing other fibers to run. | |
1640 | </para> | |
1641 | </listitem> | |
1642 | </varlistentry> | |
1643 | <varlistentry> | |
1644 | <term>Throws:</term> | |
1645 | <listitem> | |
1646 | <para> | |
1647 | Nothing. | |
1648 | </para> | |
1649 | </listitem> | |
1650 | </varlistentry> | |
1651 | <varlistentry> | |
1652 | <term>Note:</term> | |
1653 | <listitem> | |
1654 | <para> | |
1655 | A fiber that calls <code><phrase role="identifier">yield</phrase><phrase | |
1656 | role="special">()</phrase></code> is not suspended: it is immediately | |
1657 | passed to the scheduler as ready to run. | |
1658 | </para> | |
1659 | </listitem> | |
1660 | </varlistentry> | |
1661 | </variablelist> | |
1662 | <para> | |
1663 | <bridgehead renderas="sect4" id="this_fiber_properties_bridgehead"> | |
1664 | <phrase id="this_fiber_properties"/> | |
1665 | <link linkend="this_fiber_properties">Non-member | |
1666 | function <code>this_fiber::properties()</code></link> | |
1667 | </bridgehead> | |
1668 | </para> | |
1669 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">operations</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
1670 | ||
1671 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1672 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
1673 | ||
1674 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase> | |
1675 | <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">();</phrase> | |
1676 | ||
1677 | <phrase role="special">}}</phrase> | |
1678 | </programlisting> | |
1679 | <variablelist> | |
1680 | <title></title> | |
1681 | <varlistentry> | |
1682 | <term>Preconditions:</term> | |
1683 | <listitem> | |
1684 | <para> | |
1685 | <link linkend="use_scheduling_algorithm"><code>use_scheduling_algorithm()</code></link> has been called from | |
1686 | this thread with a subclass of <link linkend="class_algorithm_with_properties"><code>algorithm_with_properties<></code></link> with | |
1687 | the same template argument <code><phrase role="identifier">PROPS</phrase></code>. | |
1688 | </para> | |
1689 | </listitem> | |
1690 | </varlistentry> | |
1691 | <varlistentry> | |
1692 | <term>Returns:</term> | |
1693 | <listitem> | |
1694 | <para> | |
1695 | a reference to the scheduler properties instance for the currently | |
1696 | running fiber. | |
1697 | </para> | |
1698 | </listitem> | |
1699 | </varlistentry> | |
1700 | <varlistentry> | |
1701 | <term>Throws:</term> | |
1702 | <listitem> | |
1703 | <para> | |
1704 | <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
1705 | role="identifier">bad_cast</phrase></code> if <code><phrase role="identifier">use_scheduling_algorithm</phrase><phrase | |
1706 | role="special">()</phrase></code> was called with an <code><phrase | |
1707 | role="identifier">algorithm_with_properties</phrase></code> subclass | |
1708 | with some other template parameter than <code><phrase role="identifier">PROPS</phrase></code>. | |
1709 | </para> | |
1710 | </listitem> | |
1711 | </varlistentry> | |
1712 | <varlistentry> | |
1713 | <term>Note:</term> | |
1714 | <listitem> | |
1715 | <para> | |
1716 | <link linkend="class_algorithm_with_properties"><code>algorithm_with_properties<></code></link> provides | |
1717 | a way for a user-coded scheduler to associate extended properties, | |
1718 | such as priority, with a fiber instance. This function allows access | |
1719 | to those user-provided properties. | |
1720 | </para> | |
1721 | </listitem> | |
1722 | </varlistentry> | |
1723 | <varlistentry> | |
1724 | <term>Note:</term> | |
1725 | <listitem> | |
1726 | <para> | |
1727 | The first time this function is called from the main fiber of a thread, | |
1728 | it may internally yield, permitting other fibers to run. | |
1729 | </para> | |
1730 | </listitem> | |
1731 | </varlistentry> | |
1732 | <varlistentry> | |
1733 | <term>See also:</term> | |
1734 | <listitem> | |
1735 | <para> | |
1736 | <link linkend="custom">Customization</link> | |
1737 | </para> | |
1738 | </listitem> | |
1739 | </varlistentry> | |
1740 | </variablelist> | |
1741 | </section> | |
1742 | </section> | |
1743 | <section id="fiber.scheduling"> | |
1744 | <title><anchor id="scheduling"/><link linkend="fiber.scheduling">Scheduling</link></title> | |
1745 | <para> | |
1746 | The fibers in a thread are coordinated by a fiber manager. Fibers trade control | |
1747 | cooperatively, rather than preemptively: the currently-running fiber retains | |
1748 | control until it invokes some operation that passes control to the manager. | |
1749 | Each time a fiber suspends (or yields), the fiber manager consults a scheduler | |
1750 | to determine which fiber will run next. | |
1751 | </para> | |
1752 | <para> | |
1753 | <emphasis role="bold">Boost.Fiber</emphasis> provides the fiber manager, but | |
1754 | the scheduler is a customization point. (See <link linkend="custom">Customization</link>.) | |
1755 | </para> | |
1756 | <para> | |
1757 | Each thread has its own scheduler. Different threads in a process may use different | |
1758 | schedulers. By default, <emphasis role="bold">Boost.Fiber</emphasis> implicitly | |
1759 | instantiates <link linkend="class_round_robin"><code>round_robin</code></link> as the scheduler for each thread. | |
1760 | </para> | |
1761 | <para> | |
1762 | You are explicitly permitted to code your own <link linkend="class_algorithm"><code>algorithm</code></link> subclass. | |
1763 | For the most part, your <code><phrase role="identifier">algorithm</phrase></code> | |
1764 | subclass need not defend against cross-thread calls: the fiber manager intercepts | |
1765 | and defers such calls. Most <code><phrase role="identifier">algorithm</phrase></code> | |
1766 | methods are only ever directly called from the thread whose fibers it is managing | |
1767 | — with exceptions as documented below. | |
1768 | </para> | |
1769 | <para> | |
1770 | Your <code><phrase role="identifier">algorithm</phrase></code> subclass is | |
1771 | engaged on a particular thread by calling <link linkend="use_scheduling_algorithm"><code>use_scheduling_algorithm()</code></link>: | |
1772 | </para> | |
1773 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">thread_fn</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
1774 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special"><</phrase> <phrase role="identifier">my_fiber_scheduler</phrase> <phrase role="special">>();</phrase> | |
1775 | <phrase role="special">...</phrase> | |
1776 | <phrase role="special">}</phrase> | |
1777 | </programlisting> | |
1778 | <para> | |
1779 | A scheduler class must implement interface <link linkend="class_algorithm"><code>algorithm</code></link>. <emphasis | |
1780 | role="bold">Boost.Fiber</emphasis> provides one scheduler: <link linkend="class_round_robin"><code>round_robin</code></link>. | |
1781 | </para> | |
1782 | <para> | |
1783 | <bridgehead renderas="sect4" id="class_algorithm_bridgehead"> | |
1784 | <phrase id="class_algorithm"/> | |
1785 | <link linkend="class_algorithm">Class <code>algorithm</code></link> | |
1786 | </bridgehead> | |
1787 | </para> | |
1788 | <para> | |
1789 | <code><phrase role="identifier">algorithm</phrase></code> is the abstract base | |
1790 | class defining the interface that a fiber scheduler must implement. | |
1791 | </para> | |
1792 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">algo</phrase><phrase role="special">/</phrase><phrase role="identifier">algorithm</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
1793 | ||
1794 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
1795 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
1796 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">algo</phrase> <phrase role="special">{</phrase> | |
1797 | ||
1798 | <phrase role="keyword">struct</phrase> <phrase role="identifier">algorithm</phrase> <phrase role="special">{</phrase> | |
1799 | <phrase role="keyword">virtual</phrase> <phrase role="special">~</phrase><phrase role="identifier">algorithm</phrase><phrase role="special">();</phrase> | |
1800 | ||
1801 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1802 | ||
1803 | <phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1804 | ||
1805 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1806 | ||
1807 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1808 | ||
1809 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1810 | <phrase role="special">};</phrase> | |
1811 | ||
1812 | <phrase role="special">}}}</phrase> | |
1813 | </programlisting> | |
1814 | <para> | |
1815 | <bridgehead renderas="sect4" id="algorithm_awakened_bridgehead"> | |
1816 | <phrase id="algorithm_awakened"/> | |
1817 | <link linkend="algorithm_awakened">Member function | |
1818 | <code>awakened</code>()</link> | |
1819 | </bridgehead> | |
1820 | </para> | |
1821 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1822 | </programlisting> | |
1823 | <variablelist> | |
1824 | <title></title> | |
1825 | <varlistentry> | |
1826 | <term>Effects:</term> | |
1827 | <listitem> | |
1828 | <para> | |
1829 | Informs the scheduler that fiber <code><phrase role="identifier">f</phrase></code> | |
1830 | is ready to run. Fiber <code><phrase role="identifier">f</phrase></code> | |
1831 | might be newly launched, or it might have been blocked but has just been | |
1832 | awakened, or it might have called <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link>. | |
1833 | </para> | |
1834 | </listitem> | |
1835 | </varlistentry> | |
1836 | <varlistentry> | |
1837 | <term>Note:</term> | |
1838 | <listitem> | |
1839 | <para> | |
1840 | This method advises the scheduler to add fiber <code><phrase role="identifier">f</phrase></code> | |
1841 | to its collection of fibers ready to run. A typical scheduler implementation | |
1842 | places <code><phrase role="identifier">f</phrase></code> into a queue. | |
1843 | </para> | |
1844 | </listitem> | |
1845 | </varlistentry> | |
1846 | <varlistentry> | |
1847 | <term>See also:</term> | |
1848 | <listitem> | |
1849 | <para> | |
1850 | <link linkend="class_round_robin"><code>round_robin</code></link> | |
1851 | </para> | |
1852 | </listitem> | |
1853 | </varlistentry> | |
1854 | </variablelist> | |
1855 | <para> | |
1856 | <bridgehead renderas="sect4" id="algorithm_pick_next_bridgehead"> | |
1857 | <phrase id="algorithm_pick_next"/> | |
1858 | <link linkend="algorithm_pick_next">Member | |
1859 | function <code>pick_next</code>()</link> | |
1860 | </bridgehead> | |
1861 | </para> | |
1862 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1863 | </programlisting> | |
1864 | <variablelist> | |
1865 | <title></title> | |
1866 | <varlistentry> | |
1867 | <term>Returns:</term> | |
1868 | <listitem> | |
1869 | <para> | |
1870 | the fiber which is to be resumed next, or <code><phrase role="keyword">nullptr</phrase></code> | |
1871 | if there is no ready fiber. | |
1872 | </para> | |
1873 | </listitem> | |
1874 | </varlistentry> | |
1875 | <varlistentry> | |
1876 | <term>Note:</term> | |
1877 | <listitem> | |
1878 | <para> | |
1879 | This is where the scheduler actually specifies the fiber which is to | |
1880 | run next. A typical scheduler implementation chooses the head of the | |
1881 | ready queue. | |
1882 | </para> | |
1883 | </listitem> | |
1884 | </varlistentry> | |
1885 | <varlistentry> | |
1886 | <term>See also:</term> | |
1887 | <listitem> | |
1888 | <para> | |
1889 | <link linkend="class_round_robin"><code>round_robin</code></link> | |
1890 | </para> | |
1891 | </listitem> | |
1892 | </varlistentry> | |
1893 | </variablelist> | |
1894 | <para> | |
1895 | <bridgehead renderas="sect4" id="algorithm_has_ready_fibers_bridgehead"> | |
1896 | <phrase id="algorithm_has_ready_fibers"/> | |
1897 | <link linkend="algorithm_has_ready_fibers">Member | |
1898 | function <code>has_ready_fibers</code>()</link> | |
1899 | </bridgehead> | |
1900 | </para> | |
1901 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1902 | </programlisting> | |
1903 | <variablelist> | |
1904 | <title></title> | |
1905 | <varlistentry> | |
1906 | <term>Returns:</term> | |
1907 | <listitem> | |
1908 | <para> | |
1909 | <code><phrase role="keyword">true</phrase></code> if scheduler has fibers | |
1910 | ready to run. | |
1911 | </para> | |
1912 | </listitem> | |
1913 | </varlistentry> | |
1914 | </variablelist> | |
1915 | <para> | |
1916 | <bridgehead renderas="sect4" id="algorithm_suspend_until_bridgehead"> | |
1917 | <phrase id="algorithm_suspend_until"/> | |
1918 | <link linkend="algorithm_suspend_until">Member | |
1919 | function <code>suspend_until</code>()</link> | |
1920 | </bridgehead> | |
1921 | </para> | |
1922 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1923 | </programlisting> | |
1924 | <variablelist> | |
1925 | <title></title> | |
1926 | <varlistentry> | |
1927 | <term>Effects:</term> | |
1928 | <listitem> | |
1929 | <para> | |
1930 | Informs the scheduler that no fiber will be ready until time-point <code><phrase | |
1931 | role="identifier">abs_time</phrase></code>. | |
1932 | </para> | |
1933 | </listitem> | |
1934 | </varlistentry> | |
1935 | <varlistentry> | |
1936 | <term>Note:</term> | |
1937 | <listitem> | |
1938 | <para> | |
1939 | This method allows a custom scheduler to yield control to the containing | |
1940 | environment in whatever way makes sense. The fiber manager is stating | |
1941 | that <code><phrase role="identifier">suspend_until</phrase><phrase role="special">()</phrase></code> | |
1942 | need not return until <code><phrase role="identifier">abs_time</phrase></code> | |
1943 | — or <link linkend="algorithm_notify"><code>algorithm::notify()</code></link> is called — whichever comes first. | |
1944 | The interaction with <code><phrase role="identifier">notify</phrase><phrase | |
1945 | role="special">()</phrase></code> means that, for instance, calling | |
1946 | <ulink url="http://en.cppreference.com/w/cpp/thread/sleep_until"><code><phrase | |
1947 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
1948 | role="identifier">this_thread</phrase><phrase role="special">::</phrase><phrase | |
1949 | role="identifier">sleep_until</phrase><phrase role="special">(</phrase><phrase | |
1950 | role="identifier">abs_time</phrase><phrase role="special">)</phrase></code></ulink> | |
1951 | would be too simplistic. <link linkend="round_robin_suspend_until"><code>round_robin::suspend_until()</code></link> uses | |
1952 | a <ulink url="http://en.cppreference.com/w/cpp/thread/condition_variable"><code><phrase | |
1953 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
1954 | role="identifier">condition_variable</phrase></code></ulink> to coordinate | |
1955 | with <link linkend="round_robin_notify"><code>round_robin::notify()</code></link>. | |
1956 | </para> | |
1957 | </listitem> | |
1958 | </varlistentry> | |
1959 | <varlistentry> | |
1960 | <term>Note:</term> | |
1961 | <listitem> | |
1962 | <para> | |
1963 | Given that <code><phrase role="identifier">notify</phrase><phrase role="special">()</phrase></code> | |
1964 | might be called from another thread, your <code><phrase role="identifier">suspend_until</phrase><phrase | |
1965 | role="special">()</phrase></code> implementation — like the rest of your | |
1966 | <code><phrase role="identifier">algorithm</phrase></code> implementation | |
1967 | — must guard any data it shares with your <code><phrase role="identifier">notify</phrase><phrase | |
1968 | role="special">()</phrase></code> implementation. | |
1969 | </para> | |
1970 | </listitem> | |
1971 | </varlistentry> | |
1972 | </variablelist> | |
1973 | <para> | |
1974 | <bridgehead renderas="sect4" id="algorithm_notify_bridgehead"> | |
1975 | <phrase id="algorithm_notify"/> | |
1976 | <link linkend="algorithm_notify">Member function | |
1977 | <code>notify</code>()</link> | |
1978 | </bridgehead> | |
1979 | </para> | |
1980 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
1981 | </programlisting> | |
1982 | <variablelist> | |
1983 | <title></title> | |
1984 | <varlistentry> | |
1985 | <term>Effects:</term> | |
1986 | <listitem> | |
1987 | <para> | |
1988 | Requests the scheduler to return from a pending call to <link linkend="algorithm_suspend_until"><code>algorithm::suspend_until()</code></link>. | |
1989 | </para> | |
1990 | </listitem> | |
1991 | </varlistentry> | |
1992 | <varlistentry> | |
1993 | <term>Note:</term> | |
1994 | <listitem> | |
1995 | <para> | |
1996 | Alone among the <code><phrase role="identifier">algorithm</phrase></code> | |
1997 | methods, <code><phrase role="identifier">notify</phrase><phrase role="special">()</phrase></code> | |
1998 | may be called from another thread. Your <code><phrase role="identifier">notify</phrase><phrase | |
1999 | role="special">()</phrase></code> implementation must guard any data | |
2000 | it shares with the rest of your <code><phrase role="identifier">algorithm</phrase></code> | |
2001 | implementation. | |
2002 | </para> | |
2003 | </listitem> | |
2004 | </varlistentry> | |
2005 | </variablelist> | |
2006 | <para> | |
2007 | <bridgehead renderas="sect4" id="class_round_robin_bridgehead"> | |
2008 | <phrase id="class_round_robin"/> | |
2009 | <link linkend="class_round_robin">Class <code>round_robin</code></link> | |
2010 | </bridgehead> | |
2011 | </para> | |
2012 | <para> | |
2013 | This class implements <link linkend="class_algorithm"><code>algorithm</code></link>, scheduling fibers in round-robin | |
2014 | fashion. | |
2015 | </para> | |
2016 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">algo</phrase><phrase role="special">/</phrase><phrase role="identifier">round_robin</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
2017 | ||
2018 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
2019 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
2020 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">algo</phrase> <phrase role="special">{</phrase> | |
2021 | ||
2022 | <phrase role="keyword">class</phrase> <phrase role="identifier">round_robin</phrase> <phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">algorithm</phrase> <phrase role="special">{</phrase> | |
2023 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2024 | ||
2025 | <phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2026 | ||
2027 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2028 | ||
2029 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2030 | ||
2031 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2032 | <phrase role="special">};</phrase> | |
2033 | ||
2034 | <phrase role="special">}}}</phrase> | |
2035 | </programlisting> | |
2036 | <para> | |
2037 | <bridgehead renderas="sect4" id="round_robin_awakened_bridgehead"> | |
2038 | <phrase id="round_robin_awakened"/> | |
2039 | <link linkend="round_robin_awakened">Member | |
2040 | function <code>awakened</code>()</link> | |
2041 | </bridgehead> | |
2042 | </para> | |
2043 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2044 | </programlisting> | |
2045 | <variablelist> | |
2046 | <title></title> | |
2047 | <varlistentry> | |
2048 | <term>Effects:</term> | |
2049 | <listitem> | |
2050 | <para> | |
2051 | Enqueues fiber <code><phrase role="identifier">f</phrase></code> onto | |
2052 | a ready queue. | |
2053 | </para> | |
2054 | </listitem> | |
2055 | </varlistentry> | |
2056 | <varlistentry> | |
2057 | <term>Throws:</term> | |
2058 | <listitem> | |
2059 | <para> | |
2060 | Nothing. | |
2061 | </para> | |
2062 | </listitem> | |
2063 | </varlistentry> | |
2064 | </variablelist> | |
2065 | <para> | |
2066 | <bridgehead renderas="sect4" id="round_robin_pick_next_bridgehead"> | |
2067 | <phrase id="round_robin_pick_next"/> | |
2068 | <link linkend="round_robin_pick_next">Member | |
2069 | function <code>pick_next</code>()</link> | |
2070 | </bridgehead> | |
2071 | </para> | |
2072 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2073 | </programlisting> | |
2074 | <variablelist> | |
2075 | <title></title> | |
2076 | <varlistentry> | |
2077 | <term>Returns:</term> | |
2078 | <listitem> | |
2079 | <para> | |
2080 | the fiber at the head of the ready queue, or <code><phrase role="keyword">nullptr</phrase></code> | |
2081 | if the queue is empty. | |
2082 | </para> | |
2083 | </listitem> | |
2084 | </varlistentry> | |
2085 | <varlistentry> | |
2086 | <term>Throws:</term> | |
2087 | <listitem> | |
2088 | <para> | |
2089 | Nothing. | |
2090 | </para> | |
2091 | </listitem> | |
2092 | </varlistentry> | |
2093 | <varlistentry> | |
2094 | <term>Note:</term> | |
2095 | <listitem> | |
2096 | <para> | |
2097 | Placing ready fibers onto the tail of a queue, and returning them from | |
2098 | the head of that queue, shares the thread between ready fibers in round-robin | |
2099 | fashion. | |
2100 | </para> | |
2101 | </listitem> | |
2102 | </varlistentry> | |
2103 | </variablelist> | |
2104 | <para> | |
2105 | <bridgehead renderas="sect4" id="round_robin_has_ready_fibers_bridgehead"> | |
2106 | <phrase id="round_robin_has_ready_fibers"/> | |
2107 | <link linkend="round_robin_has_ready_fibers">Member | |
2108 | function <code>has_ready_fibers</code>()</link> | |
2109 | </bridgehead> | |
2110 | </para> | |
2111 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2112 | </programlisting> | |
2113 | <variablelist> | |
2114 | <title></title> | |
2115 | <varlistentry> | |
2116 | <term>Returns:</term> | |
2117 | <listitem> | |
2118 | <para> | |
2119 | <code><phrase role="keyword">true</phrase></code> if scheduler has fibers | |
2120 | ready to run. | |
2121 | </para> | |
2122 | </listitem> | |
2123 | </varlistentry> | |
2124 | <varlistentry> | |
2125 | <term>Throws:</term> | |
2126 | <listitem> | |
2127 | <para> | |
2128 | Nothing. | |
2129 | </para> | |
2130 | </listitem> | |
2131 | </varlistentry> | |
2132 | </variablelist> | |
2133 | <para> | |
2134 | <bridgehead renderas="sect4" id="round_robin_suspend_until_bridgehead"> | |
2135 | <phrase id="round_robin_suspend_until"/> | |
2136 | <link linkend="round_robin_suspend_until">Member | |
2137 | function <code>suspend_until</code>()</link> | |
2138 | </bridgehead> | |
2139 | </para> | |
2140 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2141 | </programlisting> | |
2142 | <variablelist> | |
2143 | <title></title> | |
2144 | <varlistentry> | |
2145 | <term>Effects:</term> | |
2146 | <listitem> | |
2147 | <para> | |
2148 | Informs <code><phrase role="identifier">round_robin</phrase></code> that | |
2149 | no ready fiber will be available until time-point <code><phrase role="identifier">abs_time</phrase></code>. | |
2150 | This implementation blocks in <ulink url="http://en.cppreference.com/w/cpp/thread/condition_variable/wait_until"><code><phrase | |
2151 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
2152 | role="identifier">condition_variable</phrase><phrase role="special">::</phrase><phrase | |
2153 | role="identifier">wait_until</phrase><phrase role="special">()</phrase></code></ulink>. | |
2154 | </para> | |
2155 | </listitem> | |
2156 | </varlistentry> | |
2157 | <varlistentry> | |
2158 | <term>Throws:</term> | |
2159 | <listitem> | |
2160 | <para> | |
2161 | Nothing. | |
2162 | </para> | |
2163 | </listitem> | |
2164 | </varlistentry> | |
2165 | </variablelist> | |
2166 | <para> | |
2167 | <bridgehead renderas="sect4" id="round_robin_notify_bridgehead"> | |
2168 | <phrase id="round_robin_notify"/> | |
2169 | <link linkend="round_robin_notify">Member function | |
2170 | <code>notify</code>()</link> | |
2171 | </bridgehead> | |
2172 | </para> | |
2173 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
2174 | </programlisting> | |
2175 | <variablelist> | |
2176 | <title></title> | |
2177 | <varlistentry> | |
2178 | <term>Effects:</term> | |
2179 | <listitem> | |
2180 | <para> | |
2181 | Wake up a pending call to <link linkend="round_robin_suspend_until"><code>round_robin::suspend_until()</code></link>, | |
2182 | some fibers might be ready. This implementation wakes <code><phrase role="identifier">suspend_until</phrase><phrase | |
2183 | role="special">()</phrase></code> via <ulink url="http://en.cppreference.com/w/cpp/thread/condition_variable/notify_all"><code><phrase | |
2184 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
2185 | role="identifier">condition_variable</phrase><phrase role="special">::</phrase><phrase | |
2186 | role="identifier">notify_all</phrase><phrase role="special">()</phrase></code></ulink>. | |
2187 | </para> | |
2188 | </listitem> | |
2189 | </varlistentry> | |
2190 | <varlistentry> | |
2191 | <term>Throws:</term> | |
2192 | <listitem> | |
2193 | <para> | |
2194 | Nothing. | |
2195 | </para> | |
2196 | </listitem> | |
2197 | </varlistentry> | |
2198 | </variablelist> | |
2199 | <para> | |
2200 | <bridgehead renderas="sect4" id="class_shared_work_bridgehead"> | |
2201 | <phrase id="class_shared_work"/> | |
2202 | <link linkend="class_shared_work">Class <code>shared_work</code></link> | |
2203 | </bridgehead> | |
2204 | </para> | |
2205 | <para> | |
2206 | This class implements <link linkend="class_algorithm"><code>algorithm</code></link>; ready fibers are shared between | |
2207 | all instances (running on different threads) of shared_work. | |
2208 | </para> | |
2209 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">algo</phrase><phrase role="special">/</phrase><phrase role="identifier">shared_work</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
2210 | ||
2211 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
2212 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
2213 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">algo</phrase> <phrase role="special">{</phrase> | |
2214 | ||
2215 | <phrase role="keyword">class</phrase> <phrase role="identifier">shared_work</phrase> <phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">algorithm</phrase> <phrase role="special">{</phrase> | |
2216 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2217 | ||
2218 | <phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2219 | ||
2220 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2221 | ||
2222 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2223 | ||
2224 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2225 | <phrase role="special">};</phrase> | |
2226 | ||
2227 | <phrase role="special">}}}</phrase> | |
2228 | </programlisting> | |
2229 | <para> | |
2230 | <bridgehead renderas="sect4" id="shared_work_awakened_bridgehead"> | |
2231 | <phrase id="shared_work_awakened"/> | |
2232 | <link linkend="shared_work_awakened">Member | |
2233 | function <code>awakened</code>()</link> | |
2234 | </bridgehead> | |
2235 | </para> | |
2236 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2237 | </programlisting> | |
2238 | <variablelist> | |
2239 | <title></title> | |
2240 | <varlistentry> | |
2241 | <term>Effects:</term> | |
2242 | <listitem> | |
2243 | <para> | |
2244 | Enqueues fiber <code><phrase role="identifier">f</phrase></code> onto | |
2245 | the shared ready queue. | |
2246 | </para> | |
2247 | </listitem> | |
2248 | </varlistentry> | |
2249 | <varlistentry> | |
2250 | <term>Throws:</term> | |
2251 | <listitem> | |
2252 | <para> | |
2253 | Nothing. | |
2254 | </para> | |
2255 | </listitem> | |
2256 | </varlistentry> | |
2257 | </variablelist> | |
2258 | <para> | |
2259 | <bridgehead renderas="sect4" id="shared_work_pick_next_bridgehead"> | |
2260 | <phrase id="shared_work_pick_next"/> | |
2261 | <link linkend="shared_work_pick_next">Member | |
2262 | function <code>pick_next</code>()</link> | |
2263 | </bridgehead> | |
2264 | </para> | |
2265 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2266 | </programlisting> | |
2267 | <variablelist> | |
2268 | <title></title> | |
2269 | <varlistentry> | |
2270 | <term>Returns:</term> | |
2271 | <listitem> | |
2272 | <para> | |
2273 | the fiber at the head of the ready queue, or <code><phrase role="keyword">nullptr</phrase></code> | |
2274 | if the queue is empty. | |
2275 | </para> | |
2276 | </listitem> | |
2277 | </varlistentry> | |
2278 | <varlistentry> | |
2279 | <term>Throws:</term> | |
2280 | <listitem> | |
2281 | <para> | |
2282 | Nothing. | |
2283 | </para> | |
2284 | </listitem> | |
2285 | </varlistentry> | |
2286 | <varlistentry> | |
2287 | <term>Note:</term> | |
2288 | <listitem> | |
2289 | <para> | |
2290 | Placing ready fibers onto the tail of the shared queue, and returning | |
2291 | them from the head of that queue, shares the thread between ready fibers | |
2292 | in round-robin fashion. | |
2293 | </para> | |
2294 | </listitem> | |
2295 | </varlistentry> | |
2296 | </variablelist> | |
2297 | <para> | |
2298 | <bridgehead renderas="sect4" id="shared_work_has_ready_fibers_bridgehead"> | |
2299 | <phrase id="shared_work_has_ready_fibers"/> | |
2300 | <link linkend="shared_work_has_ready_fibers">Member | |
2301 | function <code>has_ready_fibers</code>()</link> | |
2302 | </bridgehead> | |
2303 | </para> | |
2304 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2305 | </programlisting> | |
2306 | <variablelist> | |
2307 | <title></title> | |
2308 | <varlistentry> | |
2309 | <term>Returns:</term> | |
2310 | <listitem> | |
2311 | <para> | |
2312 | <code><phrase role="keyword">true</phrase></code> if scheduler has fibers | |
2313 | ready to run. | |
2314 | </para> | |
2315 | </listitem> | |
2316 | </varlistentry> | |
2317 | <varlistentry> | |
2318 | <term>Throws:</term> | |
2319 | <listitem> | |
2320 | <para> | |
2321 | Nothing. | |
2322 | </para> | |
2323 | </listitem> | |
2324 | </varlistentry> | |
2325 | </variablelist> | |
2326 | <para> | |
2327 | <bridgehead renderas="sect4" id="shared_work_suspend_until_bridgehead"> | |
2328 | <phrase id="shared_work_suspend_until"/> | |
2329 | <link linkend="shared_work_suspend_until">Member | |
2330 | function <code>suspend_until</code>()</link> | |
2331 | </bridgehead> | |
2332 | </para> | |
2333 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2334 | </programlisting> | |
2335 | <variablelist> | |
2336 | <title></title> | |
2337 | <varlistentry> | |
2338 | <term>Effects:</term> | |
2339 | <listitem> | |
2340 | <para> | |
2341 | Informs <code><phrase role="identifier">shared_work</phrase></code> that | |
2342 | no ready fiber will be available until time-point <code><phrase role="identifier">abs_time</phrase></code>. | |
2343 | This implementation blocks in <ulink url="http://en.cppreference.com/w/cpp/thread/condition_variable/wait_until"><code><phrase | |
2344 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
2345 | role="identifier">condition_variable</phrase><phrase role="special">::</phrase><phrase | |
2346 | role="identifier">wait_until</phrase><phrase role="special">()</phrase></code></ulink>. | |
2347 | </para> | |
2348 | </listitem> | |
2349 | </varlistentry> | |
2350 | <varlistentry> | |
2351 | <term>Throws:</term> | |
2352 | <listitem> | |
2353 | <para> | |
2354 | Nothing. | |
2355 | </para> | |
2356 | </listitem> | |
2357 | </varlistentry> | |
2358 | </variablelist> | |
2359 | <para> | |
2360 | <bridgehead renderas="sect4" id="shared_work_notify_bridgehead"> | |
2361 | <phrase id="shared_work_notify"/> | |
2362 | <link linkend="shared_work_notify">Member function | |
2363 | <code>notify</code>()</link> | |
2364 | </bridgehead> | |
2365 | </para> | |
2366 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
2367 | </programlisting> | |
2368 | <variablelist> | |
2369 | <title></title> | |
2370 | <varlistentry> | |
2371 | <term>Effects:</term> | |
2372 | <listitem> | |
2373 | <para> | |
2374 | Wake up a pending call to <link linkend="shared_work_suspend_until"><code>shared_work::suspend_until()</code></link>, | |
2375 | some fibers might be ready. This implementation wakes <code><phrase role="identifier">suspend_until</phrase><phrase | |
2376 | role="special">()</phrase></code> via <ulink url="http://en.cppreference.com/w/cpp/thread/condition_variable/notify_all"><code><phrase | |
2377 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
2378 | role="identifier">condition_variable</phrase><phrase role="special">::</phrase><phrase | |
2379 | role="identifier">notify_all</phrase><phrase role="special">()</phrase></code></ulink>. | |
2380 | </para> | |
2381 | </listitem> | |
2382 | </varlistentry> | |
2383 | <varlistentry> | |
2384 | <term>Throws:</term> | |
2385 | <listitem> | |
2386 | <para> | |
2387 | Nothing. | |
2388 | </para> | |
2389 | </listitem> | |
2390 | </varlistentry> | |
2391 | </variablelist> | |
2392 | <bridgehead renderas="sect3" id="fiber.scheduling.h0"> | |
2393 | <phrase id="fiber.scheduling.custom_scheduler_fiber_properties"/><link linkend="fiber.scheduling.custom_scheduler_fiber_properties">Custom | |
2394 | Scheduler Fiber Properties</link> | |
2395 | </bridgehead> | |
2396 | <para> | |
2397 | A scheduler class directly derived from <link linkend="class_algorithm"><code>algorithm</code></link> can use any | |
2398 | information available from <link linkend="class_context"><code>context</code></link> to implement the <code><phrase | |
2399 | role="identifier">algorithm</phrase></code> interface. But a custom scheduler | |
2400 | might need to track additional properties for a fiber. For instance, a priority-based | |
2401 | scheduler would need to track a fiber’s priority. | |
2402 | </para> | |
2403 | <para> | |
2404 | <emphasis role="bold">Boost.Fiber</emphasis> provides a mechanism by which | |
2405 | your custom scheduler can associate custom properties with each fiber. | |
2406 | </para> | |
2407 | <para> | |
2408 | <bridgehead renderas="sect4" id="class_fiber_properties_bridgehead"> | |
2409 | <phrase id="class_fiber_properties"/> | |
2410 | <link linkend="class_fiber_properties">Class | |
2411 | <code>fiber_properties</code></link> | |
2412 | </bridgehead> | |
2413 | </para> | |
2414 | <para> | |
2415 | A custom fiber properties class must be derived from <code><phrase role="identifier">fiber_properties</phrase></code>. | |
2416 | </para> | |
2417 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">properties</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
2418 | ||
2419 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
2420 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
2421 | ||
2422 | <phrase role="keyword">class</phrase> <phrase role="identifier">fiber_properties</phrase> <phrase role="special">{</phrase> | |
2423 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
2424 | <phrase role="identifier">fiber_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2425 | ||
2426 | <phrase role="keyword">virtual</phrase> <phrase role="special">~</phrase><phrase role="identifier">fiber_properties</phrase><phrase role="special">();</phrase> | |
2427 | ||
2428 | <phrase role="keyword">protected</phrase><phrase role="special">:</phrase> | |
2429 | <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2430 | <phrase role="special">};</phrase> | |
2431 | ||
2432 | <phrase role="special">}}</phrase> | |
2433 | </programlisting> | |
2434 | <bridgehead renderas="sect3" id="fiber.scheduling.h1"> | |
2435 | <phrase id="fiber.scheduling.constructor"/><link linkend="fiber.scheduling.constructor">Constructor</link> | |
2436 | </bridgehead> | |
2437 | <programlisting><phrase role="identifier">fiber_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2438 | </programlisting> | |
2439 | <variablelist> | |
2440 | <title></title> | |
2441 | <varlistentry> | |
2442 | <term>Effects:</term> | |
2443 | <listitem> | |
2444 | <para> | |
2445 | Constructs base-class component of custom subclass. | |
2446 | </para> | |
2447 | </listitem> | |
2448 | </varlistentry> | |
2449 | <varlistentry> | |
2450 | <term>Throws:</term> | |
2451 | <listitem> | |
2452 | <para> | |
2453 | Nothing. | |
2454 | </para> | |
2455 | </listitem> | |
2456 | </varlistentry> | |
2457 | <varlistentry> | |
2458 | <term>Note:</term> | |
2459 | <listitem> | |
2460 | <para> | |
2461 | Your subclass constructor must accept a <code><phrase role="identifier">context</phrase><phrase | |
2462 | role="special">*</phrase></code> and pass it to the base-class <code><phrase | |
2463 | role="identifier">fiber_properties</phrase></code> constructor. | |
2464 | </para> | |
2465 | </listitem> | |
2466 | </varlistentry> | |
2467 | </variablelist> | |
2468 | <para> | |
2469 | <bridgehead renderas="sect4" id="fiber_properties_notify_bridgehead"> | |
2470 | <phrase id="fiber_properties_notify"/> | |
2471 | <link linkend="fiber_properties_notify">Member | |
2472 | function <code>notify</code>()</link> | |
2473 | </bridgehead> | |
2474 | </para> | |
2475 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2476 | </programlisting> | |
2477 | <variablelist> | |
2478 | <title></title> | |
2479 | <varlistentry> | |
2480 | <term>Effects:</term> | |
2481 | <listitem> | |
2482 | <para> | |
2483 | Pass control to the custom <link linkend="class_algorithm_with_properties"><code>algorithm_with_properties<></code></link> subclass’s | |
2484 | <link linkend="algorithm_with_properties_property_change"><code>algorithm_with_properties::property_change()</code></link> method. | |
2485 | </para> | |
2486 | </listitem> | |
2487 | </varlistentry> | |
2488 | <varlistentry> | |
2489 | <term>Throws:</term> | |
2490 | <listitem> | |
2491 | <para> | |
2492 | Nothing. | |
2493 | </para> | |
2494 | </listitem> | |
2495 | </varlistentry> | |
2496 | <varlistentry> | |
2497 | <term>Note:</term> | |
2498 | <listitem> | |
2499 | <para> | |
2500 | A custom scheduler’s <link linkend="algorithm_with_properties_pick_next"><code>algorithm_with_properties::pick_next()</code></link> method | |
2501 | might dynamically select from the ready fibers, or <link linkend="algorithm_with_properties_awakened"><code>algorithm_with_properties::awakened()</code></link> might | |
2502 | instead insert each ready fiber into some form of ready queue for <code><phrase | |
2503 | role="identifier">pick_next</phrase><phrase role="special">()</phrase></code>. | |
2504 | In the latter case, if application code modifies a fiber property (e.g. | |
2505 | priority) that should affect that fiber’s relationship to other ready | |
2506 | fibers, the custom scheduler must be given the opportunity to reorder | |
2507 | its ready queue. The custom property subclass should implement an access | |
2508 | method to modify such a property; that access method should call <code><phrase | |
2509 | role="identifier">notify</phrase><phrase role="special">()</phrase></code> | |
2510 | once the new property value has been stored. This passes control to the | |
2511 | custom scheduler’s <code><phrase role="identifier">property_change</phrase><phrase | |
2512 | role="special">()</phrase></code> method, allowing the custom scheduler | |
2513 | to reorder its ready queue appropriately. Use at your discretion. Of | |
2514 | course, if you define a property which does not affect the behavior of | |
2515 | the <code><phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase></code> | |
2516 | method, you need not call <code><phrase role="identifier">notify</phrase><phrase | |
2517 | role="special">()</phrase></code> when that property is modified. | |
2518 | </para> | |
2519 | </listitem> | |
2520 | </varlistentry> | |
2521 | </variablelist> | |
2522 | <para> | |
2523 | <bridgehead renderas="sect4" id="class_algorithm_with_properties_bridgehead"> | |
2524 | <phrase id="class_algorithm_with_properties"/> | |
2525 | <link linkend="class_algorithm_with_properties">Template | |
2526 | <code>algorithm_with_properties<></code></link> | |
2527 | </bridgehead> | |
2528 | </para> | |
2529 | <para> | |
2530 | A custom scheduler that depends on a custom properties class <code><phrase | |
2531 | role="identifier">PROPS</phrase></code> should be derived from <code><phrase | |
2532 | role="identifier">algorithm_with_properties</phrase><phrase role="special"><</phrase><phrase | |
2533 | role="identifier">PROPS</phrase><phrase role="special">></phrase></code>. | |
2534 | <code><phrase role="identifier">PROPS</phrase></code> should be derived from | |
2535 | <link linkend="class_fiber_properties"><code>fiber_properties</code></link>. | |
2536 | </para> | |
2537 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">algorithm</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
2538 | ||
2539 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
2540 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
2541 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">algo</phrase> <phrase role="special">{</phrase> | |
2542 | ||
2543 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">></phrase> | |
2544 | <phrase role="keyword">struct</phrase> <phrase role="identifier">algorithm_with_properties</phrase> <phrase role="special">{</phrase> | |
2545 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
2546 | ||
2547 | <phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2548 | ||
2549 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2550 | ||
2551 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
2552 | ||
2553 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
2554 | ||
2555 | <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2556 | ||
2557 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">property_change</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2558 | ||
2559 | <phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_properties</phrase> <phrase role="special">*</phrase> <phrase role="identifier">new_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*);</phrase> | |
2560 | <phrase role="special">};</phrase> | |
2561 | ||
2562 | <phrase role="special">}}}</phrase> | |
2563 | </programlisting> | |
2564 | <para> | |
2565 | <bridgehead renderas="sect4" id="algorithm_with_properties_awakened_bridgehead"> | |
2566 | <phrase id="algorithm_with_properties_awakened"/> | |
2567 | <link linkend="algorithm_with_properties_awakened">Member | |
2568 | function <code>awakened</code>()</link> | |
2569 | </bridgehead> | |
2570 | </para> | |
2571 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2572 | </programlisting> | |
2573 | <variablelist> | |
2574 | <title></title> | |
2575 | <varlistentry> | |
2576 | <term>Effects:</term> | |
2577 | <listitem> | |
2578 | <para> | |
2579 | Informs the scheduler that fiber <code><phrase role="identifier">f</phrase></code> | |
2580 | is ready to run, like <link linkend="algorithm_awakened"><code>algorithm::awakened()</code></link>. Passes | |
2581 | the fiber’s associated <code><phrase role="identifier">PROPS</phrase></code> | |
2582 | instance. | |
2583 | </para> | |
2584 | </listitem> | |
2585 | </varlistentry> | |
2586 | <varlistentry> | |
2587 | <term>Throws:</term> | |
2588 | <listitem> | |
2589 | <para> | |
2590 | Nothing. | |
2591 | </para> | |
2592 | </listitem> | |
2593 | </varlistentry> | |
2594 | <varlistentry> | |
2595 | <term>Note:</term> | |
2596 | <listitem> | |
2597 | <para> | |
2598 | An <code><phrase role="identifier">algorithm_with_properties</phrase><phrase | |
2599 | role="special"><></phrase></code> subclass must override this method | |
2600 | instead of <code><phrase role="identifier">algorithm</phrase><phrase | |
2601 | role="special">::</phrase><phrase role="identifier">awakened</phrase><phrase | |
2602 | role="special">()</phrase></code>. | |
2603 | </para> | |
2604 | </listitem> | |
2605 | </varlistentry> | |
2606 | </variablelist> | |
2607 | <para> | |
2608 | <bridgehead renderas="sect4" id="algorithm_with_properties_pick_next_bridgehead"> | |
2609 | <phrase id="algorithm_with_properties_pick_next"/> | |
2610 | <link linkend="algorithm_with_properties_pick_next">Member | |
2611 | function <code>pick_next</code>()</link> | |
2612 | </bridgehead> | |
2613 | </para> | |
2614 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2615 | </programlisting> | |
2616 | <variablelist> | |
2617 | <title></title> | |
2618 | <varlistentry> | |
2619 | <term>Returns:</term> | |
2620 | <listitem> | |
2621 | <para> | |
2622 | the fiber which is to be resumed next, or <code><phrase role="keyword">nullptr</phrase></code> | |
2623 | if there is no ready fiber. | |
2624 | </para> | |
2625 | </listitem> | |
2626 | </varlistentry> | |
2627 | <varlistentry> | |
2628 | <term>Throws:</term> | |
2629 | <listitem> | |
2630 | <para> | |
2631 | Nothing. | |
2632 | </para> | |
2633 | </listitem> | |
2634 | </varlistentry> | |
2635 | <varlistentry> | |
2636 | <term>Note:</term> | |
2637 | <listitem> | |
2638 | <para> | |
2639 | same as <link linkend="algorithm_pick_next"><code>algorithm::pick_next()</code></link> | |
2640 | </para> | |
2641 | </listitem> | |
2642 | </varlistentry> | |
2643 | </variablelist> | |
2644 | <para> | |
2645 | <bridgehead renderas="sect4" id="algorithm_with_properties_has_ready_fibers_bridgehead"> | |
2646 | <phrase id="algorithm_with_properties_has_ready_fibers"/> | |
2647 | <link linkend="algorithm_with_properties_has_ready_fibers">Member | |
2648 | function <code>has_ready_fibers</code>()</link> | |
2649 | </bridgehead> | |
2650 | </para> | |
2651 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2652 | </programlisting> | |
2653 | <variablelist> | |
2654 | <title></title> | |
2655 | <varlistentry> | |
2656 | <term>Returns:</term> | |
2657 | <listitem> | |
2658 | <para> | |
2659 | <code><phrase role="keyword">true</phrase></code> if scheduler has fibers | |
2660 | ready to run. | |
2661 | </para> | |
2662 | </listitem> | |
2663 | </varlistentry> | |
2664 | <varlistentry> | |
2665 | <term>Throws:</term> | |
2666 | <listitem> | |
2667 | <para> | |
2668 | Nothing. | |
2669 | </para> | |
2670 | </listitem> | |
2671 | </varlistentry> | |
2672 | <varlistentry> | |
2673 | <term>Note:</term> | |
2674 | <listitem> | |
2675 | <para> | |
2676 | same as <link linkend="algorithm_has_ready_fibers"><code>algorithm::has_ready_fibers()</code></link> | |
2677 | </para> | |
2678 | </listitem> | |
2679 | </varlistentry> | |
2680 | </variablelist> | |
2681 | <para> | |
2682 | <bridgehead renderas="sect4" id="algorithm_with_properties_suspend_until_bridgehead"> | |
2683 | <phrase id="algorithm_with_properties_suspend_until"/> | |
2684 | <link linkend="algorithm_with_properties_suspend_until">Member | |
2685 | function <code>suspend_until</code>()</link> | |
2686 | </bridgehead> | |
2687 | </para> | |
2688 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
2689 | </programlisting> | |
2690 | <variablelist> | |
2691 | <title></title> | |
2692 | <varlistentry> | |
2693 | <term>Effects:</term> | |
2694 | <listitem> | |
2695 | <para> | |
2696 | Informs the scheduler that no fiber will be ready until time-point <code><phrase | |
2697 | role="identifier">abs_time</phrase></code>. | |
2698 | </para> | |
2699 | </listitem> | |
2700 | </varlistentry> | |
2701 | <varlistentry> | |
2702 | <term>Note:</term> | |
2703 | <listitem> | |
2704 | <para> | |
2705 | same as <link linkend="algorithm_suspend_until"><code>algorithm::suspend_until()</code></link> | |
2706 | </para> | |
2707 | </listitem> | |
2708 | </varlistentry> | |
2709 | </variablelist> | |
2710 | <para> | |
2711 | <bridgehead renderas="sect4" id="algorithm_with_properties_notify_bridgehead"> | |
2712 | <phrase id="algorithm_with_properties_notify"/> | |
2713 | <link linkend="algorithm_with_properties_notify">Member | |
2714 | function <code>notify</code>()</link> | |
2715 | </bridgehead> | |
2716 | </para> | |
2717 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
2718 | </programlisting> | |
2719 | <variablelist> | |
2720 | <title></title> | |
2721 | <varlistentry> | |
2722 | <term>Effects:</term> | |
2723 | <listitem> | |
2724 | <para> | |
2725 | Requests the scheduler to return from a pending call to <link linkend="algorithm_with_properties_suspend_until"><code>algorithm_with_properties::suspend_until()</code></link>. | |
2726 | </para> | |
2727 | </listitem> | |
2728 | </varlistentry> | |
2729 | <varlistentry> | |
2730 | <term>Note:</term> | |
2731 | <listitem> | |
2732 | <para> | |
2733 | same as <link linkend="algorithm_notify"><code>algorithm::notify()</code></link> | |
2734 | </para> | |
2735 | </listitem> | |
2736 | </varlistentry> | |
2737 | </variablelist> | |
2738 | <para> | |
2739 | <bridgehead renderas="sect4" id="algorithm_with_properties_properties_bridgehead"> | |
2740 | <phrase id="algorithm_with_properties_properties"/> | |
2741 | <link linkend="algorithm_with_properties_properties">Member | |
2742 | function <code>properties</code>()</link> | |
2743 | </bridgehead> | |
2744 | </para> | |
2745 | <programlisting><phrase role="identifier">PROPS</phrase><phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2746 | </programlisting> | |
2747 | <variablelist> | |
2748 | <title></title> | |
2749 | <varlistentry> | |
2750 | <term>Returns:</term> | |
2751 | <listitem> | |
2752 | <para> | |
2753 | the <code><phrase role="identifier">PROPS</phrase></code> instance associated | |
2754 | with fiber <code><phrase role="identifier">f</phrase></code>. | |
2755 | </para> | |
2756 | </listitem> | |
2757 | </varlistentry> | |
2758 | <varlistentry> | |
2759 | <term>Throws:</term> | |
2760 | <listitem> | |
2761 | <para> | |
2762 | Nothing. | |
2763 | </para> | |
2764 | </listitem> | |
2765 | </varlistentry> | |
2766 | <varlistentry> | |
2767 | <term>Note:</term> | |
2768 | <listitem> | |
2769 | <para> | |
2770 | The fiber’s associated <code><phrase role="identifier">PROPS</phrase></code> | |
2771 | instance is already passed to <link linkend="algorithm_with_properties_awakened"><code>algorithm_with_properties::awakened()</code></link> and | |
2772 | <link linkend="algorithm_with_properties_property_change"><code>algorithm_with_properties::property_change()</code></link>. | |
2773 | However, every <link linkend="class_algorithm"><code>algorithm</code></link> subclass is expected to track | |
2774 | a collection of ready <link linkend="class_context"><code>context</code></link> instances. This method allows | |
2775 | your custom scheduler to retrieve the <link linkend="class_fiber_properties"><code>fiber_properties</code></link> subclass | |
2776 | instance for any <code><phrase role="identifier">context</phrase></code> | |
2777 | in its collection. | |
2778 | </para> | |
2779 | </listitem> | |
2780 | </varlistentry> | |
2781 | </variablelist> | |
2782 | <para> | |
2783 | <bridgehead renderas="sect4" id="algorithm_with_properties_property_change_bridgehead"> | |
2784 | <phrase id="algorithm_with_properties_property_change"/> | |
2785 | <link linkend="algorithm_with_properties_property_change">Member | |
2786 | function <code>property_change</code>()</link> | |
2787 | </bridgehead> | |
2788 | </para> | |
2789 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">property_change</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">,</phrase> <phrase role="identifier">PROPS</phrase> <phrase role="special">&</phrase> <phrase role="identifier">properties</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2790 | </programlisting> | |
2791 | <variablelist> | |
2792 | <title></title> | |
2793 | <varlistentry> | |
2794 | <term>Effects:</term> | |
2795 | <listitem> | |
2796 | <para> | |
2797 | Notify the custom scheduler of a possibly-relevant change to a property | |
2798 | belonging to fiber <code><phrase role="identifier">f</phrase></code>. | |
2799 | <code><phrase role="identifier">properties</phrase></code> contains the | |
2800 | new values of all relevant properties. | |
2801 | </para> | |
2802 | </listitem> | |
2803 | </varlistentry> | |
2804 | <varlistentry> | |
2805 | <term>Throws:</term> | |
2806 | <listitem> | |
2807 | <para> | |
2808 | Nothing. | |
2809 | </para> | |
2810 | </listitem> | |
2811 | </varlistentry> | |
2812 | <varlistentry> | |
2813 | <term>Note:</term> | |
2814 | <listitem> | |
2815 | <para> | |
2816 | This method is only called when a custom <link linkend="class_fiber_properties"><code>fiber_properties</code></link> subclass | |
2817 | explicitly calls <link linkend="fiber_properties_notify"><code>fiber_properties::notify()</code></link>. | |
2818 | </para> | |
2819 | </listitem> | |
2820 | </varlistentry> | |
2821 | </variablelist> | |
2822 | <para> | |
2823 | <bridgehead renderas="sect4" id="algorithm_with_properties_new_properties_bridgehead"> | |
2824 | <phrase id="algorithm_with_properties_new_properties"/> | |
2825 | <link linkend="algorithm_with_properties_new_properties">Member | |
2826 | function <code>new_properties</code>()</link> | |
2827 | </bridgehead> | |
2828 | </para> | |
2829 | <programlisting><phrase role="keyword">virtual</phrase> <phrase role="identifier">fiber_properties</phrase> <phrase role="special">*</phrase> <phrase role="identifier">new_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">);</phrase> | |
2830 | </programlisting> | |
2831 | <variablelist> | |
2832 | <title></title> | |
2833 | <varlistentry> | |
2834 | <term>Returns:</term> | |
2835 | <listitem> | |
2836 | <para> | |
2837 | A new instance of <link linkend="class_fiber_properties"><code>fiber_properties</code></link> subclass <code><phrase | |
2838 | role="identifier">PROPS</phrase></code>. | |
2839 | </para> | |
2840 | </listitem> | |
2841 | </varlistentry> | |
2842 | <varlistentry> | |
2843 | <term>Note:</term> | |
2844 | <listitem> | |
2845 | <para> | |
2846 | By default, <code><phrase role="identifier">algorithm_with_properties</phrase><phrase | |
2847 | role="special"><>::</phrase><phrase role="identifier">new_properties</phrase><phrase | |
2848 | role="special">()</phrase></code> simply returns <code><phrase role="keyword">new</phrase> | |
2849 | <phrase role="identifier">PROPS</phrase><phrase role="special">(</phrase><phrase | |
2850 | role="identifier">f</phrase><phrase role="special">)</phrase></code>, | |
2851 | placing the <code><phrase role="identifier">PROPS</phrase></code> instance | |
2852 | on the heap. Override this method to allocate <code><phrase role="identifier">PROPS</phrase></code> | |
2853 | some other way. The returned <code><phrase role="identifier">fiber_properties</phrase></code> | |
2854 | pointer must point to the <code><phrase role="identifier">PROPS</phrase></code> | |
2855 | instance to be associated with fiber <code><phrase role="identifier">f</phrase></code>. | |
2856 | </para> | |
2857 | </listitem> | |
2858 | </varlistentry> | |
2859 | </variablelist> | |
2860 | <para> | |
2861 | <anchor id="context"/><bridgehead renderas="sect4" id="class_context_bridgehead"> | |
2862 | <phrase id="class_context"/> | |
2863 | <link linkend="class_context">Class | |
2864 | <code>context</code></link> | |
2865 | </bridgehead> | |
2866 | </para> | |
2867 | <para> | |
2868 | While you are free to treat <code><phrase role="identifier">context</phrase><phrase | |
2869 | role="special">*</phrase></code> as an opaque token, certain <code><phrase | |
2870 | role="identifier">context</phrase></code> members may be useful to a custom | |
2871 | scheduler implementation. | |
2872 | </para> | |
2873 | <para> | |
2874 | <anchor id="ready_queue_t"/>Of particular note is the fact that <code><phrase | |
2875 | role="identifier">context</phrase></code> contains a hook to participate in | |
2876 | a <ulink url="http://www.boost.org/doc/libs/release/doc/html/intrusive/list.html"><code><phrase | |
2877 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">intrusive</phrase><phrase | |
2878 | role="special">::</phrase><phrase role="identifier">list</phrase></code></ulink> | |
2879 | <literal>typedef</literal>’ed as <code><phrase role="identifier">boost</phrase><phrase | |
2880 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
2881 | role="special">::</phrase><phrase role="identifier">scheduler</phrase><phrase | |
2882 | role="special">::</phrase><phrase role="identifier">ready_queue_t</phrase></code>. | |
2883 | This hook is reserved for use by <link linkend="class_algorithm"><code>algorithm</code></link> implementations. (For | |
2884 | instance, <link linkend="class_round_robin"><code>round_robin</code></link> contains a <code><phrase role="identifier">ready_queue_t</phrase></code> | |
2885 | instance to manage its ready fibers.) See <link linkend="context_ready_is_linked"><code>context::ready_is_linked()</code></link>, | |
2886 | <link linkend="context_ready_link"><code>context::ready_link()</code></link>, <link linkend="context_ready_unlink"><code>context::ready_unlink()</code></link>. | |
2887 | </para> | |
2888 | <para> | |
2889 | Your <code><phrase role="identifier">algorithm</phrase></code> implementation | |
2890 | may use any container you desire to manage passed <code><phrase role="identifier">context</phrase></code> | |
2891 | instances. <code><phrase role="identifier">ready_queue_t</phrase></code> avoids | |
2892 | some of the overhead of typical STL containers. | |
2893 | </para> | |
2894 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">context</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
2895 | ||
2896 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
2897 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
2898 | ||
2899 | <phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">type</phrase> <phrase role="special">{</phrase> | |
2900 | <phrase role="identifier">none</phrase> <phrase role="special">=</phrase> <emphasis>unspecified</emphasis><phrase role="special">,</phrase> | |
2901 | <phrase role="identifier">main_context</phrase> <phrase role="special">=</phrase> <emphasis>unspecified</emphasis><phrase role="special">,</phrase> <phrase role="comment">// fiber associated with thread's stack</phrase> | |
2902 | <phrase role="identifier">dispatcher_context</phrase> <phrase role="special">=</phrase> <emphasis>unspecified</emphasis><phrase role="special">,</phrase> <phrase role="comment">// special fiber for maintenance operations</phrase> | |
2903 | <phrase role="identifier">worker_context</phrase> <phrase role="special">=</phrase> <emphasis>unspecified</emphasis><phrase role="special">,</phrase> <phrase role="comment">// fiber not special to the library</phrase> | |
2904 | <phrase role="identifier">pinned_context</phrase> <phrase role="special">=</phrase> <emphasis>unspecified</emphasis> <phrase role="comment">// fiber must not be migrated to another thread</phrase> | |
2905 | <phrase role="special">};</phrase> | |
2906 | ||
2907 | <phrase role="keyword">class</phrase> <phrase role="identifier">context</phrase> <phrase role="special">{</phrase> | |
2908 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
2909 | <phrase role="keyword">class</phrase> <phrase role="identifier">id</phrase><phrase role="special">;</phrase> | |
2910 | ||
2911 | <phrase role="keyword">static</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">active</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2912 | ||
2913 | <phrase role="identifier">context</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
2914 | <phrase role="identifier">context</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">context</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
2915 | ||
2916 | <phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2917 | ||
2918 | <phrase role="keyword">void</phrase> <phrase role="identifier">detach</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2919 | <phrase role="keyword">void</phrase> <phrase role="identifier">attach</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2920 | ||
2921 | <phrase role="keyword">bool</phrase> <phrase role="identifier">is_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">type</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2922 | ||
2923 | <phrase role="keyword">bool</phrase> <phrase role="identifier">is_terminated</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2924 | ||
2925 | <phrase role="keyword">bool</phrase> <phrase role="identifier">ready_is_linked</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2926 | <phrase role="keyword">bool</phrase> <phrase role="identifier">remote_ready_is_linked</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2927 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_is_linked</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2928 | ||
2929 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">List</phrase> <phrase role="special">></phrase> | |
2930 | <phrase role="keyword">void</phrase> <phrase role="identifier">ready_link</phrase><phrase role="special">(</phrase> <phrase role="identifier">List</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2931 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">List</phrase> <phrase role="special">></phrase> | |
2932 | <phrase role="keyword">void</phrase> <phrase role="identifier">remote_ready_link</phrase><phrase role="special">(</phrase> <phrase role="identifier">List</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2933 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">List</phrase> <phrase role="special">></phrase> | |
2934 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_link</phrase><phrase role="special">(</phrase> <phrase role="identifier">List</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2935 | ||
2936 | <phrase role="keyword">void</phrase> <phrase role="identifier">ready_unlink</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2937 | <phrase role="keyword">void</phrase> <phrase role="identifier">remote_ready_unlink</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2938 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_unlink</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2939 | ||
2940 | <phrase role="keyword">void</phrase> <phrase role="identifier">suspend</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2941 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_ready</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2942 | <phrase role="special">};</phrase> | |
2943 | ||
2944 | <phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">context</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">context</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2945 | ||
2946 | <phrase role="special">}}</phrase> | |
2947 | </programlisting> | |
2948 | <para> | |
2949 | <bridgehead renderas="sect4" id="context_active_bridgehead"> | |
2950 | <phrase id="context_active"/> | |
2951 | <link linkend="context_active">Static member function | |
2952 | <code>active</code>()</link> | |
2953 | </bridgehead> | |
2954 | </para> | |
2955 | <programlisting><phrase role="keyword">static</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">active</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2956 | </programlisting> | |
2957 | <variablelist> | |
2958 | <title></title> | |
2959 | <varlistentry> | |
2960 | <term>Returns:</term> | |
2961 | <listitem> | |
2962 | <para> | |
2963 | Pointer to instance of current fiber. | |
2964 | </para> | |
2965 | </listitem> | |
2966 | </varlistentry> | |
2967 | <varlistentry> | |
2968 | <term>Throws:</term> | |
2969 | <listitem> | |
2970 | <para> | |
2971 | Nothing | |
2972 | </para> | |
2973 | </listitem> | |
2974 | </varlistentry> | |
2975 | </variablelist> | |
2976 | <para> | |
2977 | <bridgehead renderas="sect4" id="context_get_id_bridgehead"> | |
2978 | <phrase id="context_get_id"/> | |
2979 | <link linkend="context_get_id">Member function <code>get_id</code>()</link> | |
2980 | </bridgehead> | |
2981 | </para> | |
2982 | <programlisting><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
2983 | </programlisting> | |
2984 | <variablelist> | |
2985 | <title></title> | |
2986 | <varlistentry> | |
2987 | <term>Returns:</term> | |
2988 | <listitem> | |
2989 | <para> | |
2990 | If <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
2991 | refers to a fiber of execution, an instance of <link linkend="class_fiber_id"><code><phrase | |
2992 | role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase | |
2993 | role="identifier">id</phrase></code></link> that represents that fiber. Otherwise | |
2994 | returns a default-constructed <link linkend="class_fiber_id"><code><phrase role="identifier">fiber</phrase><phrase | |
2995 | role="special">::</phrase><phrase role="identifier">id</phrase></code></link>. | |
2996 | </para> | |
2997 | </listitem> | |
2998 | </varlistentry> | |
2999 | <varlistentry> | |
3000 | <term>Throws:</term> | |
3001 | <listitem> | |
3002 | <para> | |
3003 | Nothing | |
3004 | </para> | |
3005 | </listitem> | |
3006 | </varlistentry> | |
3007 | <varlistentry> | |
3008 | <term>See also:</term> | |
3009 | <listitem> | |
3010 | <para> | |
3011 | <link linkend="fiber_get_id"><code>fiber::get_id()</code></link> | |
3012 | </para> | |
3013 | </listitem> | |
3014 | </varlistentry> | |
3015 | </variablelist> | |
3016 | <para> | |
3017 | <bridgehead renderas="sect4" id="context_attach_bridgehead"> | |
3018 | <phrase id="context_attach"/> | |
3019 | <link linkend="context_attach">Member function <code>attach</code>()</link> | |
3020 | </bridgehead> | |
3021 | </para> | |
3022 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">attach</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">f</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3023 | </programlisting> | |
3024 | <variablelist> | |
3025 | <title></title> | |
3026 | <varlistentry> | |
3027 | <term>Precondition:</term> | |
3028 | <listitem> | |
3029 | <para> | |
3030 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
3031 | role="identifier">get_scheduler</phrase><phrase role="special">()</phrase> | |
3032 | <phrase role="special">==</phrase> <phrase role="keyword">nullptr</phrase></code> | |
3033 | </para> | |
3034 | </listitem> | |
3035 | </varlistentry> | |
3036 | <varlistentry> | |
3037 | <term>Effects:</term> | |
3038 | <listitem> | |
3039 | <para> | |
3040 | Attach fiber <code><phrase role="identifier">f</phrase></code> to scheduler | |
3041 | running <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
3042 | </para> | |
3043 | </listitem> | |
3044 | </varlistentry> | |
3045 | <varlistentry> | |
3046 | <term>Postcondition:</term> | |
3047 | <listitem> | |
3048 | <para> | |
3049 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
3050 | role="identifier">get_scheduler</phrase><phrase role="special">()</phrase> | |
3051 | <phrase role="special">!=</phrase> <phrase role="keyword">nullptr</phrase></code> | |
3052 | </para> | |
3053 | </listitem> | |
3054 | </varlistentry> | |
3055 | <varlistentry> | |
3056 | <term>Throws:</term> | |
3057 | <listitem> | |
3058 | <para> | |
3059 | Nothing | |
3060 | </para> | |
3061 | </listitem> | |
3062 | </varlistentry> | |
3063 | <varlistentry> | |
3064 | <term>Note:</term> | |
3065 | <listitem> | |
3066 | <para> | |
3067 | A typical call: <code><phrase role="identifier">boost</phrase><phrase | |
3068 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
3069 | role="special">::</phrase><phrase role="identifier">context</phrase><phrase | |
3070 | role="special">::</phrase><phrase role="identifier">active</phrase><phrase | |
3071 | role="special">()-></phrase><phrase role="identifier">attach</phrase><phrase | |
3072 | role="special">(</phrase><phrase role="identifier">f</phrase><phrase | |
3073 | role="special">);</phrase></code> | |
3074 | </para> | |
3075 | </listitem> | |
3076 | </varlistentry> | |
3077 | <varlistentry> | |
3078 | <term>Note:</term> | |
3079 | <listitem> | |
3080 | <para> | |
3081 | <code><phrase role="identifier">f</phrase></code> must not be the running | |
3082 | fiber’s context. It must not be <link linkend="blocking"><emphasis>blocked</emphasis></link> | |
3083 | or terminated. It must not be a <code><phrase role="identifier">pinned_context</phrase></code>. | |
3084 | It must be currently detached. It must not currently be linked into an | |
3085 | <link linkend="class_algorithm"><code>algorithm</code></link> implementation’s ready queue. Most of these conditions | |
3086 | are implied by <code><phrase role="identifier">f</phrase></code> being | |
3087 | owned by an <code><phrase role="identifier">algorithm</phrase></code> | |
3088 | implementation: that is, it has been passed to <link linkend="algorithm_awakened"><code>algorithm::awakened()</code></link> but | |
3089 | has not yet been returned by <link linkend="algorithm_pick_next"><code>algorithm::pick_next()</code></link>. | |
3090 | Typically a <code><phrase role="identifier">pick_next</phrase><phrase | |
3091 | role="special">()</phrase></code> implementation would call <code><phrase | |
3092 | role="identifier">attach</phrase><phrase role="special">()</phrase></code> | |
3093 | with the <code><phrase role="identifier">context</phrase><phrase role="special">*</phrase></code> | |
3094 | it is about to return. It must first remove <code><phrase role="identifier">f</phrase></code> | |
3095 | from its ready queue. You should never pass a <code><phrase role="identifier">pinned_context</phrase></code> | |
3096 | to <code><phrase role="identifier">attach</phrase><phrase role="special">()</phrase></code> | |
3097 | because you should never have called its <code><phrase role="identifier">detach</phrase><phrase | |
3098 | role="special">()</phrase></code> method in the first place. | |
3099 | </para> | |
3100 | </listitem> | |
3101 | </varlistentry> | |
3102 | </variablelist> | |
3103 | <para> | |
3104 | <bridgehead renderas="sect4" id="context_detach_bridgehead"> | |
3105 | <phrase id="context_detach"/> | |
3106 | <link linkend="context_detach">Member function <code>detach</code>()</link> | |
3107 | </bridgehead> | |
3108 | </para> | |
3109 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">detach</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3110 | </programlisting> | |
3111 | <variablelist> | |
3112 | <title></title> | |
3113 | <varlistentry> | |
3114 | <term>Precondition:</term> | |
3115 | <listitem> | |
3116 | <para> | |
3117 | <code><phrase role="special">(</phrase><phrase role="keyword">this</phrase><phrase | |
3118 | role="special">-></phrase><phrase role="identifier">get_scheduler</phrase><phrase | |
3119 | role="special">()</phrase> <phrase role="special">!=</phrase> <phrase | |
3120 | role="keyword">nullptr</phrase><phrase role="special">)</phrase> <phrase | |
3121 | role="special">&&</phrase> <phrase role="special">!</phrase> | |
3122 | <phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
3123 | role="identifier">is_context</phrase><phrase role="special">(</phrase><phrase | |
3124 | role="identifier">pinned_context</phrase><phrase role="special">)</phrase></code> | |
3125 | </para> | |
3126 | </listitem> | |
3127 | </varlistentry> | |
3128 | <varlistentry> | |
3129 | <term>Effects:</term> | |
3130 | <listitem> | |
3131 | <para> | |
3132 | Detach fiber <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3133 | from its scheduler running <code><phrase role="special">*</phrase><phrase | |
3134 | role="keyword">this</phrase></code>. | |
3135 | </para> | |
3136 | </listitem> | |
3137 | </varlistentry> | |
3138 | <varlistentry> | |
3139 | <term>Throws:</term> | |
3140 | <listitem> | |
3141 | <para> | |
3142 | Nothing | |
3143 | </para> | |
3144 | </listitem> | |
3145 | </varlistentry> | |
3146 | <varlistentry> | |
3147 | <term>Postcondition:</term> | |
3148 | <listitem> | |
3149 | <para> | |
3150 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
3151 | role="identifier">get_scheduler</phrase><phrase role="special">()</phrase> | |
3152 | <phrase role="special">==</phrase> <phrase role="keyword">nullptr</phrase></code> | |
3153 | </para> | |
3154 | </listitem> | |
3155 | </varlistentry> | |
3156 | <varlistentry> | |
3157 | <term>Note:</term> | |
3158 | <listitem> | |
3159 | <para> | |
3160 | This method must be called on the thread with which the fiber is currently | |
3161 | associated. <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3162 | must not be the running fiber’s context. It must not be <link linkend="blocking"><emphasis>blocked</emphasis></link> | |
3163 | or terminated. It must not be a <code><phrase role="identifier">pinned_context</phrase></code>. | |
3164 | It must not be detached already. It must not already be linked into an | |
3165 | <link linkend="class_algorithm"><code>algorithm</code></link> implementation’s ready queue. Most of these conditions | |
3166 | are implied by <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3167 | being passed to <link linkend="algorithm_awakened"><code>algorithm::awakened()</code></link>; an <code><phrase | |
3168 | role="identifier">awakened</phrase><phrase role="special">()</phrase></code> | |
3169 | implementation must, however, test for <code><phrase role="identifier">pinned_context</phrase></code>. | |
3170 | It must call <code><phrase role="identifier">detach</phrase><phrase role="special">()</phrase></code> | |
3171 | <emphasis>before</emphasis> linking <code><phrase role="special">*</phrase><phrase | |
3172 | role="keyword">this</phrase></code> into its ready queue. | |
3173 | </para> | |
3174 | </listitem> | |
3175 | </varlistentry> | |
3176 | <varlistentry> | |
3177 | <term>Note:</term> | |
3178 | <listitem> | |
3179 | <para> | |
3180 | In particular, it is erroneous to attempt to migrate a fiber from one | |
3181 | thread to another by calling both <code><phrase role="identifier">detach</phrase><phrase | |
3182 | role="special">()</phrase></code> and <code><phrase role="identifier">attach</phrase><phrase | |
3183 | role="special">()</phrase></code> in the <link linkend="algorithm_pick_next"><code>algorithm::pick_next()</code></link> method. | |
3184 | <code><phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase></code> | |
3185 | is called on the intended destination thread. <code><phrase role="identifier">detach</phrase><phrase | |
3186 | role="special">()</phrase></code> must be called on the fiber’s original | |
3187 | thread. You must call <code><phrase role="identifier">detach</phrase><phrase | |
3188 | role="special">()</phrase></code> in the corresponding <code><phrase | |
3189 | role="identifier">awakened</phrase><phrase role="special">()</phrase></code> | |
3190 | method. | |
3191 | </para> | |
3192 | </listitem> | |
3193 | </varlistentry> | |
3194 | <varlistentry> | |
3195 | <term>Note:</term> | |
3196 | <listitem> | |
3197 | <para> | |
3198 | Unless you intend make a fiber available for potential migration to a | |
3199 | different thread, you should call neither <code><phrase role="identifier">detach</phrase><phrase | |
3200 | role="special">()</phrase></code> nor <code><phrase role="identifier">attach</phrase><phrase | |
3201 | role="special">()</phrase></code> with its <code><phrase role="identifier">context</phrase></code>. | |
3202 | </para> | |
3203 | </listitem> | |
3204 | </varlistentry> | |
3205 | </variablelist> | |
3206 | <para> | |
3207 | <bridgehead renderas="sect4" id="context_is_context_bridgehead"> | |
3208 | <phrase id="context_is_context"/> | |
3209 | <link linkend="context_is_context">Member function | |
3210 | <code>is_context</code>()</link> | |
3211 | </bridgehead> | |
3212 | </para> | |
3213 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">is_context</phrase><phrase role="special">(</phrase> <phrase role="identifier">type</phrase> <phrase role="identifier">t</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3214 | </programlisting> | |
3215 | <variablelist> | |
3216 | <title></title> | |
3217 | <varlistentry> | |
3218 | <term>Returns:</term> | |
3219 | <listitem> | |
3220 | <para> | |
3221 | <code><phrase role="keyword">true</phrase></code> if <code><phrase role="special">*</phrase><phrase | |
3222 | role="keyword">this</phrase></code> is of the specified type. | |
3223 | </para> | |
3224 | </listitem> | |
3225 | </varlistentry> | |
3226 | <varlistentry> | |
3227 | <term>Throws:</term> | |
3228 | <listitem> | |
3229 | <para> | |
3230 | Nothing | |
3231 | </para> | |
3232 | </listitem> | |
3233 | </varlistentry> | |
3234 | <varlistentry> | |
3235 | <term>Note:</term> | |
3236 | <listitem> | |
3237 | <para> | |
3238 | <code><phrase role="identifier">type</phrase><phrase role="special">::</phrase><phrase | |
3239 | role="identifier">worker_context</phrase></code> here means any fiber | |
3240 | not special to the library. For <code><phrase role="identifier">type</phrase><phrase | |
3241 | role="special">::</phrase><phrase role="identifier">main_context</phrase></code> | |
3242 | the <code><phrase role="identifier">context</phrase></code> is associated | |
3243 | with the <quote>main</quote> fiber of the thread: the one implicitly | |
3244 | created by the thread itself, rather than one explicitly created by | |
3245 | <emphasis role="bold">Boost.Fiber</emphasis>. For <code><phrase role="identifier">type</phrase><phrase | |
3246 | role="special">::</phrase><phrase role="identifier">dispatcher_context</phrase></code> | |
3247 | the <code><phrase role="identifier">context</phrase></code> is associated | |
3248 | with a <quote>dispatching</quote> fiber, responsible for dispatching | |
3249 | awakened fibers to a scheduler’s ready-queue. The <quote>dispatching</quote> | |
3250 | fiber is an implementation detail of the fiber manager. The context of | |
3251 | the <quote>main</quote> or <quote>dispatching</quote> fiber — any fiber | |
3252 | for which <code><phrase role="identifier">is_context</phrase><phrase | |
3253 | role="special">(</phrase><phrase role="identifier">pinned_context</phrase><phrase | |
3254 | role="special">)</phrase></code> is <code><phrase role="keyword">true</phrase></code> | |
3255 | — must never be passed to <link linkend="context_detach"><code>context::detach()</code></link>. | |
3256 | </para> | |
3257 | </listitem> | |
3258 | </varlistentry> | |
3259 | </variablelist> | |
3260 | <para> | |
3261 | <bridgehead renderas="sect4" id="context_is_terminated_bridgehead"> | |
3262 | <phrase id="context_is_terminated"/> | |
3263 | <link linkend="context_is_terminated">Member | |
3264 | function <code>is_terminated</code>()</link> | |
3265 | </bridgehead> | |
3266 | </para> | |
3267 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">is_terminated</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3268 | </programlisting> | |
3269 | <variablelist> | |
3270 | <title></title> | |
3271 | <varlistentry> | |
3272 | <term>Returns:</term> | |
3273 | <listitem> | |
3274 | <para> | |
3275 | <code><phrase role="keyword">true</phrase></code> if <code><phrase role="special">*</phrase><phrase | |
3276 | role="keyword">this</phrase></code> is no longer a valid context. | |
3277 | </para> | |
3278 | </listitem> | |
3279 | </varlistentry> | |
3280 | <varlistentry> | |
3281 | <term>Throws:</term> | |
3282 | <listitem> | |
3283 | <para> | |
3284 | Nothing | |
3285 | </para> | |
3286 | </listitem> | |
3287 | </varlistentry> | |
3288 | <varlistentry> | |
3289 | <term>Note:</term> | |
3290 | <listitem> | |
3291 | <para> | |
3292 | The <code><phrase role="identifier">context</phrase></code> has returned | |
3293 | from its fiber-function and is no longer considered a valid context. | |
3294 | </para> | |
3295 | </listitem> | |
3296 | </varlistentry> | |
3297 | </variablelist> | |
3298 | <para> | |
3299 | <bridgehead renderas="sect4" id="context_ready_is_linked_bridgehead"> | |
3300 | <phrase id="context_ready_is_linked"/> | |
3301 | <link linkend="context_ready_is_linked">Member | |
3302 | function <code>ready_is_linked</code>()</link> | |
3303 | </bridgehead> | |
3304 | </para> | |
3305 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">ready_is_linked</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3306 | </programlisting> | |
3307 | <variablelist> | |
3308 | <title></title> | |
3309 | <varlistentry> | |
3310 | <term>Returns:</term> | |
3311 | <listitem> | |
3312 | <para> | |
3313 | <code><phrase role="keyword">true</phrase></code> if <code><phrase role="special">*</phrase><phrase | |
3314 | role="keyword">this</phrase></code> is stored in an <link linkend="class_algorithm"><code>algorithm</code></link> | |
3315 | implementation’s | |
3316 | ready-queue. | |
3317 | </para> | |
3318 | </listitem> | |
3319 | </varlistentry> | |
3320 | <varlistentry> | |
3321 | <term>Throws:</term> | |
3322 | <listitem> | |
3323 | <para> | |
3324 | Nothing | |
3325 | </para> | |
3326 | </listitem> | |
3327 | </varlistentry> | |
3328 | <varlistentry> | |
3329 | <term>Note:</term> | |
3330 | <listitem> | |
3331 | <para> | |
3332 | Specifically, this method indicates whether <link linkend="context_ready_link"><code>context::ready_link()</code></link> has | |
3333 | been called on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
3334 | <code><phrase role="identifier">ready_is_linked</phrase><phrase role="special">()</phrase></code> | |
3335 | has no information about participation in any other containers. | |
3336 | </para> | |
3337 | </listitem> | |
3338 | </varlistentry> | |
3339 | </variablelist> | |
3340 | <para> | |
3341 | <bridgehead renderas="sect4" id="context_remote_ready_is_linked_bridgehead"> | |
3342 | <phrase id="context_remote_ready_is_linked"/> | |
3343 | <link linkend="context_remote_ready_is_linked">Member | |
3344 | function <code>remote_ready_is_linked</code>()</link> | |
3345 | </bridgehead> | |
3346 | </para> | |
3347 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">remote_ready_is_linked</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3348 | </programlisting> | |
3349 | <variablelist> | |
3350 | <title></title> | |
3351 | <varlistentry> | |
3352 | <term>Returns:</term> | |
3353 | <listitem> | |
3354 | <para> | |
3355 | <code><phrase role="keyword">true</phrase></code> if <code><phrase role="special">*</phrase><phrase | |
3356 | role="keyword">this</phrase></code> is stored in the fiber manager’s remote-ready-queue. | |
3357 | </para> | |
3358 | </listitem> | |
3359 | </varlistentry> | |
3360 | <varlistentry> | |
3361 | <term>Throws:</term> | |
3362 | <listitem> | |
3363 | <para> | |
3364 | Nothing | |
3365 | </para> | |
3366 | </listitem> | |
3367 | </varlistentry> | |
3368 | <varlistentry> | |
3369 | <term>Note:</term> | |
3370 | <listitem> | |
3371 | <para> | |
3372 | A <code><phrase role="identifier">context</phrase></code> signaled as | |
3373 | ready by another thread is first stored in the fiber manager’s remote-ready-queue. | |
3374 | This is the mechanism by which the fiber manager protects an <link linkend="class_algorithm"><code>algorithm</code></link> implementation | |
3375 | from cross-thread <link linkend="algorithm_awakened"><code>algorithm::awakened()</code></link> calls. | |
3376 | </para> | |
3377 | </listitem> | |
3378 | </varlistentry> | |
3379 | </variablelist> | |
3380 | <para> | |
3381 | <bridgehead renderas="sect4" id="context_wait_is_linked_bridgehead"> | |
3382 | <phrase id="context_wait_is_linked"/> | |
3383 | <link linkend="context_wait_is_linked">Member | |
3384 | function <code>wait_is_linked</code>()</link> | |
3385 | </bridgehead> | |
3386 | </para> | |
3387 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">wait_is_linked</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3388 | </programlisting> | |
3389 | <variablelist> | |
3390 | <title></title> | |
3391 | <varlistentry> | |
3392 | <term>Returns:</term> | |
3393 | <listitem> | |
3394 | <para> | |
3395 | <code><phrase role="keyword">true</phrase></code> if <code><phrase role="special">*</phrase><phrase | |
3396 | role="keyword">this</phrase></code> is stored in the wait-queue of some | |
3397 | synchronization object. | |
3398 | </para> | |
3399 | </listitem> | |
3400 | </varlistentry> | |
3401 | <varlistentry> | |
3402 | <term>Throws:</term> | |
3403 | <listitem> | |
3404 | <para> | |
3405 | Nothing | |
3406 | </para> | |
3407 | </listitem> | |
3408 | </varlistentry> | |
3409 | <varlistentry> | |
3410 | <term>Note:</term> | |
3411 | <listitem> | |
3412 | <para> | |
3413 | The <code><phrase role="identifier">context</phrase></code> of a fiber | |
3414 | waiting on a synchronization object (e.g. <code><phrase role="identifier">mutex</phrase></code>, | |
3415 | <code><phrase role="identifier">condition_variable</phrase></code> etc.) | |
3416 | is stored in the wait-queue of that synchronization object. | |
3417 | </para> | |
3418 | </listitem> | |
3419 | </varlistentry> | |
3420 | </variablelist> | |
3421 | <para> | |
3422 | <bridgehead renderas="sect4" id="context_ready_link_bridgehead"> | |
3423 | <phrase id="context_ready_link"/> | |
3424 | <link linkend="context_ready_link">Member function | |
3425 | <code>ready_link</code>()</link> | |
3426 | </bridgehead> | |
3427 | </para> | |
3428 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">List</phrase> <phrase role="special">></phrase> | |
3429 | <phrase role="keyword">void</phrase> <phrase role="identifier">ready_link</phrase><phrase role="special">(</phrase> <phrase role="identifier">List</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lst</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3430 | </programlisting> | |
3431 | <variablelist> | |
3432 | <title></title> | |
3433 | <varlistentry> | |
3434 | <term>Effects:</term> | |
3435 | <listitem> | |
3436 | <para> | |
3437 | Stores <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3438 | in ready-queue <code><phrase role="identifier">lst</phrase></code>. | |
3439 | </para> | |
3440 | </listitem> | |
3441 | </varlistentry> | |
3442 | <varlistentry> | |
3443 | <term>Throws:</term> | |
3444 | <listitem> | |
3445 | <para> | |
3446 | Nothing | |
3447 | </para> | |
3448 | </listitem> | |
3449 | </varlistentry> | |
3450 | <varlistentry> | |
3451 | <term>Note:</term> | |
3452 | <listitem> | |
3453 | <para> | |
3454 | Argument <code><phrase role="identifier">lst</phrase></code> must be | |
3455 | a doubly-linked list from <ulink url="http://www.boost.org/doc/libs/release/libs/intrusive/index.html">Boost.Intrusive</ulink>, | |
3456 | e.g. an instance of <code><phrase role="identifier">boost</phrase><phrase | |
3457 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
3458 | role="special">::</phrase><phrase role="identifier">scheduler</phrase><phrase | |
3459 | role="special">::</phrase><phrase role="identifier">ready_queue_t</phrase></code>. | |
3460 | Specifically, it must be a <ulink url="http://www.boost.org/doc/libs/release/doc/html/intrusive/list.html"><code><phrase | |
3461 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
3462 | role="identifier">intrusive</phrase><phrase role="special">::</phrase><phrase | |
3463 | role="identifier">list</phrase></code></ulink> compatible with the <code><phrase | |
3464 | role="identifier">list_member_hook</phrase></code> stored in the <code><phrase | |
3465 | role="identifier">context</phrase></code> object. | |
3466 | </para> | |
3467 | </listitem> | |
3468 | </varlistentry> | |
3469 | </variablelist> | |
3470 | <para> | |
3471 | <bridgehead renderas="sect4" id="context_remote_ready_link_bridgehead"> | |
3472 | <phrase id="context_remote_ready_link"/> | |
3473 | <link linkend="context_remote_ready_link">Member | |
3474 | function <code>remote_ready_link</code>()</link> | |
3475 | </bridgehead> | |
3476 | </para> | |
3477 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">List</phrase> <phrase role="special">></phrase> | |
3478 | <phrase role="keyword">void</phrase> <phrase role="identifier">remote_ready_link</phrase><phrase role="special">(</phrase> <phrase role="identifier">List</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lst</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3479 | </programlisting> | |
3480 | <variablelist> | |
3481 | <title></title> | |
3482 | <varlistentry> | |
3483 | <term>Effects:</term> | |
3484 | <listitem> | |
3485 | <para> | |
3486 | Stores <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3487 | in remote-ready-queue <code><phrase role="identifier">lst</phrase></code>. | |
3488 | </para> | |
3489 | </listitem> | |
3490 | </varlistentry> | |
3491 | <varlistentry> | |
3492 | <term>Throws:</term> | |
3493 | <listitem> | |
3494 | <para> | |
3495 | Nothing | |
3496 | </para> | |
3497 | </listitem> | |
3498 | </varlistentry> | |
3499 | <varlistentry> | |
3500 | <term>Note:</term> | |
3501 | <listitem> | |
3502 | <para> | |
3503 | Argument <code><phrase role="identifier">lst</phrase></code> must be | |
3504 | a doubly-linked list from <ulink url="http://www.boost.org/doc/libs/release/libs/intrusive/index.html">Boost.Intrusive</ulink>. | |
3505 | </para> | |
3506 | </listitem> | |
3507 | </varlistentry> | |
3508 | </variablelist> | |
3509 | <para> | |
3510 | <bridgehead renderas="sect4" id="context_wait_link_bridgehead"> | |
3511 | <phrase id="context_wait_link"/> | |
3512 | <link linkend="context_wait_link">Member function | |
3513 | <code>wait_link</code>()</link> | |
3514 | </bridgehead> | |
3515 | </para> | |
3516 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">List</phrase> <phrase role="special">></phrase> | |
3517 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_link</phrase><phrase role="special">(</phrase> <phrase role="identifier">List</phrase> <phrase role="special">&</phrase> <phrase role="identifier">lst</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3518 | </programlisting> | |
3519 | <variablelist> | |
3520 | <title></title> | |
3521 | <varlistentry> | |
3522 | <term>Effects:</term> | |
3523 | <listitem> | |
3524 | <para> | |
3525 | Stores <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3526 | in wait-queue <code><phrase role="identifier">lst</phrase></code>. | |
3527 | </para> | |
3528 | </listitem> | |
3529 | </varlistentry> | |
3530 | <varlistentry> | |
3531 | <term>Throws:</term> | |
3532 | <listitem> | |
3533 | <para> | |
3534 | Nothing | |
3535 | </para> | |
3536 | </listitem> | |
3537 | </varlistentry> | |
3538 | <varlistentry> | |
3539 | <term>Note:</term> | |
3540 | <listitem> | |
3541 | <para> | |
3542 | Argument <code><phrase role="identifier">lst</phrase></code> must be | |
3543 | a doubly-linked list from <ulink url="http://www.boost.org/doc/libs/release/libs/intrusive/index.html">Boost.Intrusive</ulink>. | |
3544 | </para> | |
3545 | </listitem> | |
3546 | </varlistentry> | |
3547 | </variablelist> | |
3548 | <para> | |
3549 | <bridgehead renderas="sect4" id="context_ready_unlink_bridgehead"> | |
3550 | <phrase id="context_ready_unlink"/> | |
3551 | <link linkend="context_ready_unlink">Member | |
3552 | function <code>ready_unlink</code>()</link> | |
3553 | </bridgehead> | |
3554 | </para> | |
3555 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">ready_unlink</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3556 | </programlisting> | |
3557 | <variablelist> | |
3558 | <title></title> | |
3559 | <varlistentry> | |
3560 | <term>Effects:</term> | |
3561 | <listitem> | |
3562 | <para> | |
3563 | Removes <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3564 | from ready-queue: undoes the effect of <link linkend="context_ready_link"><code>context::ready_link()</code></link>. | |
3565 | </para> | |
3566 | </listitem> | |
3567 | </varlistentry> | |
3568 | <varlistentry> | |
3569 | <term>Throws:</term> | |
3570 | <listitem> | |
3571 | <para> | |
3572 | Nothing | |
3573 | </para> | |
3574 | </listitem> | |
3575 | </varlistentry> | |
3576 | </variablelist> | |
3577 | <para> | |
3578 | <bridgehead renderas="sect4" id="context_remote_ready_unlink_bridgehead"> | |
3579 | <phrase id="context_remote_ready_unlink"/> | |
3580 | <link linkend="context_remote_ready_unlink">Member | |
3581 | function <code>remote_ready_unlink</code>()</link> | |
3582 | </bridgehead> | |
3583 | </para> | |
3584 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">remote_ready_unlink</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3585 | </programlisting> | |
3586 | <variablelist> | |
3587 | <title></title> | |
3588 | <varlistentry> | |
3589 | <term>Effects:</term> | |
3590 | <listitem> | |
3591 | <para> | |
3592 | Removes <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3593 | from remote-ready-queue. | |
3594 | </para> | |
3595 | </listitem> | |
3596 | </varlistentry> | |
3597 | <varlistentry> | |
3598 | <term>Throws:</term> | |
3599 | <listitem> | |
3600 | <para> | |
3601 | Nothing | |
3602 | </para> | |
3603 | </listitem> | |
3604 | </varlistentry> | |
3605 | </variablelist> | |
3606 | <para> | |
3607 | <bridgehead renderas="sect4" id="context_wait_unlink_bridgehead"> | |
3608 | <phrase id="context_wait_unlink"/> | |
3609 | <link linkend="context_wait_unlink">Member | |
3610 | function <code>wait_unlink</code>()</link> | |
3611 | </bridgehead> | |
3612 | </para> | |
3613 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">wait_unlink</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3614 | </programlisting> | |
3615 | <variablelist> | |
3616 | <title></title> | |
3617 | <varlistentry> | |
3618 | <term>Effects:</term> | |
3619 | <listitem> | |
3620 | <para> | |
3621 | Removes <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3622 | from wait-queue. | |
3623 | </para> | |
3624 | </listitem> | |
3625 | </varlistentry> | |
3626 | <varlistentry> | |
3627 | <term>Throws:</term> | |
3628 | <listitem> | |
3629 | <para> | |
3630 | Nothing | |
3631 | </para> | |
3632 | </listitem> | |
3633 | </varlistentry> | |
3634 | </variablelist> | |
3635 | <para> | |
3636 | <bridgehead renderas="sect4" id="context_suspend_bridgehead"> | |
3637 | <phrase id="context_suspend"/> | |
3638 | <link linkend="context_suspend">Member function <code>suspend</code>()</link> | |
3639 | </bridgehead> | |
3640 | </para> | |
3641 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">suspend</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3642 | </programlisting> | |
3643 | <variablelist> | |
3644 | <title></title> | |
3645 | <varlistentry> | |
3646 | <term>Effects:</term> | |
3647 | <listitem> | |
3648 | <para> | |
3649 | Suspends the running fiber (the fiber associated with <code><phrase role="special">*</phrase><phrase | |
3650 | role="keyword">this</phrase></code>) until some other fiber passes <code><phrase | |
3651 | role="keyword">this</phrase></code> to <link linkend="context_set_ready"><code>context::set_ready()</code></link>. | |
3652 | <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
3653 | is marked as not-ready, and control passes to the scheduler to select | |
3654 | another fiber to run. | |
3655 | </para> | |
3656 | </listitem> | |
3657 | </varlistentry> | |
3658 | <varlistentry> | |
3659 | <term>Throws:</term> | |
3660 | <listitem> | |
3661 | <para> | |
3662 | Nothing | |
3663 | </para> | |
3664 | </listitem> | |
3665 | </varlistentry> | |
3666 | <varlistentry> | |
3667 | <term>Note:</term> | |
3668 | <listitem> | |
3669 | <para> | |
3670 | This is a low-level API potentially useful for integration with other | |
3671 | frameworks. It is not intended to be directly invoked by a typical application | |
3672 | program. | |
3673 | </para> | |
3674 | </listitem> | |
3675 | </varlistentry> | |
3676 | <varlistentry> | |
3677 | <term>Note:</term> | |
3678 | <listitem> | |
3679 | <para> | |
3680 | The burden is on the caller to arrange for a call to <code><phrase role="identifier">set_ready</phrase><phrase | |
3681 | role="special">()</phrase></code> with a pointer to <code><phrase role="keyword">this</phrase></code> | |
3682 | at some future time. | |
3683 | </para> | |
3684 | </listitem> | |
3685 | </varlistentry> | |
3686 | </variablelist> | |
3687 | <para> | |
3688 | <bridgehead renderas="sect4" id="context_set_ready_bridgehead"> | |
3689 | <phrase id="context_set_ready"/> | |
3690 | <link linkend="context_set_ready">Member function | |
3691 | <code>set_ready</code>()</link> | |
3692 | </bridgehead> | |
3693 | </para> | |
3694 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">set_ready</phrase><phrase role="special">(</phrase> <phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ctx</phrase> <phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3695 | </programlisting> | |
3696 | <variablelist> | |
3697 | <title></title> | |
3698 | <varlistentry> | |
3699 | <term>Effects:</term> | |
3700 | <listitem> | |
3701 | <para> | |
3702 | Mark the fiber associated with context <code><phrase role="special">*</phrase><phrase | |
3703 | role="identifier">ctx</phrase></code> as being ready to run. This does | |
3704 | not immediately resume that fiber; rather it passes the fiber to the | |
3705 | scheduler for subsequent resumption. If the scheduler is idle (has not | |
3706 | returned from a call to <link linkend="algorithm_suspend_until"><code>algorithm::suspend_until()</code></link>), | |
3707 | <link linkend="algorithm_notify"><code>algorithm::notify()</code></link> is called to wake it up. | |
3708 | </para> | |
3709 | </listitem> | |
3710 | </varlistentry> | |
3711 | <varlistentry> | |
3712 | <term>Throws:</term> | |
3713 | <listitem> | |
3714 | <para> | |
3715 | Nothing | |
3716 | </para> | |
3717 | </listitem> | |
3718 | </varlistentry> | |
3719 | <varlistentry> | |
3720 | <term>Note:</term> | |
3721 | <listitem> | |
3722 | <para> | |
3723 | This is a low-level API potentially useful for integration with other | |
3724 | frameworks. It is not intended to be directly invoked by a typical application | |
3725 | program. | |
3726 | </para> | |
3727 | </listitem> | |
3728 | </varlistentry> | |
3729 | <varlistentry> | |
3730 | <term>Note:</term> | |
3731 | <listitem> | |
3732 | <para> | |
3733 | It is explicitly supported to call <code><phrase role="identifier">set_ready</phrase><phrase | |
3734 | role="special">(</phrase><phrase role="identifier">ctx</phrase><phrase | |
3735 | role="special">)</phrase></code> from a thread other than the one on | |
3736 | which <code><phrase role="special">*</phrase><phrase role="identifier">ctx</phrase></code> | |
3737 | is currently suspended. The corresponding fiber will be resumed on its | |
3738 | original thread in due course. | |
3739 | </para> | |
3740 | </listitem> | |
3741 | </varlistentry> | |
3742 | </variablelist> | |
3743 | <para> | |
3744 | <bridgehead renderas="sect4" id="context_less_bridgehead"> | |
3745 | <phrase id="context_less"/> | |
3746 | <link linkend="context_less">Non-member function <code>operator<()</code></link> | |
3747 | </bridgehead> | |
3748 | </para> | |
3749 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><(</phrase> <phrase role="identifier">context</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">context</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
3750 | </programlisting> | |
3751 | <variablelist> | |
3752 | <title></title> | |
3753 | <varlistentry> | |
3754 | <term>Returns:</term> | |
3755 | <listitem> | |
3756 | <para> | |
3757 | <code><phrase role="keyword">true</phrase></code> if <code><phrase role="identifier">l</phrase><phrase | |
3758 | role="special">.</phrase><phrase role="identifier">get_id</phrase><phrase | |
3759 | role="special">()</phrase> <phrase role="special"><</phrase> <phrase | |
3760 | role="identifier">r</phrase><phrase role="special">.</phrase><phrase | |
3761 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
3762 | is <code><phrase role="keyword">true</phrase></code>, <code><phrase role="keyword">false</phrase></code> | |
3763 | otherwise. | |
3764 | </para> | |
3765 | </listitem> | |
3766 | </varlistentry> | |
3767 | <varlistentry> | |
3768 | <term>Throws:</term> | |
3769 | <listitem> | |
3770 | <para> | |
3771 | Nothing. | |
3772 | </para> | |
3773 | </listitem> | |
3774 | </varlistentry> | |
3775 | </variablelist> | |
3776 | </section> | |
3777 | <section id="fiber.stack"> | |
3778 | <title><anchor id="stack"/><link linkend="fiber.stack">Stack allocation</link></title> | |
3779 | <para> | |
3780 | A <link linkend="class_fiber"><code>fiber</code></link> uses internally an <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink> | |
3781 | which manages a set of registers and a stack. The memory used by the stack | |
3782 | is allocated/deallocated via a <emphasis>stack_allocator</emphasis> which is | |
3783 | required to model a <link linkend="stack_allocator_concept"><emphasis>stack-allocator | |
3784 | concept</emphasis></link>. | |
3785 | </para> | |
3786 | <para> | |
3787 | A <emphasis>stack_allocator</emphasis> can be passed to <link linkend="fiber_fiber"><code><phrase | |
3788 | role="identifier">fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase | |
3789 | role="special">()</phrase></code></link> or to <link linkend="fibers_async"><code>fibers::async()</code></link>. | |
3790 | </para> | |
3791 | <anchor id="stack_allocator_concept"/> | |
3792 | <bridgehead renderas="sect3" id="fiber.stack.h0"> | |
3793 | <phrase id="fiber.stack.stack_allocator_concept"/><link linkend="fiber.stack.stack_allocator_concept">stack-allocator | |
3794 | concept</link> | |
3795 | </bridgehead> | |
3796 | <para> | |
3797 | A <emphasis>stack_allocator</emphasis> must satisfy the <emphasis>stack-allocator | |
3798 | concept</emphasis> requirements shown in the following table, in which <code><phrase | |
3799 | role="identifier">a</phrase></code> is an object of a <emphasis>stack_allocator</emphasis> | |
3800 | type, <code><phrase role="identifier">sctx</phrase></code> is a <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html"><code><phrase | |
3801 | role="identifier">stack_context</phrase></code></ulink>, and <code><phrase | |
3802 | role="identifier">size</phrase></code> is a <code><phrase role="identifier">std</phrase><phrase | |
3803 | role="special">::</phrase><phrase role="identifier">size_t</phrase></code>: | |
3804 | </para> | |
3805 | <informaltable frame="all"> | |
3806 | <tgroup cols="3"> | |
3807 | <thead> | |
3808 | <row> | |
3809 | <entry> | |
3810 | <para> | |
3811 | expression | |
3812 | </para> | |
3813 | </entry> | |
3814 | <entry> | |
3815 | <para> | |
3816 | return type | |
3817 | </para> | |
3818 | </entry> | |
3819 | <entry> | |
3820 | <para> | |
3821 | notes | |
3822 | </para> | |
3823 | </entry> | |
3824 | </row> | |
3825 | </thead> | |
3826 | <tbody> | |
3827 | <row> | |
3828 | <entry> | |
3829 | <para> | |
3830 | <code><phrase role="identifier">a</phrase><phrase role="special">(</phrase><phrase | |
3831 | role="identifier">size</phrase><phrase role="special">)</phrase></code> | |
3832 | </para> | |
3833 | </entry> | |
3834 | <entry> | |
3835 | </entry> | |
3836 | <entry> | |
3837 | <para> | |
3838 | creates a stack allocator | |
3839 | </para> | |
3840 | </entry> | |
3841 | </row> | |
3842 | <row> | |
3843 | <entry> | |
3844 | <para> | |
3845 | <code><phrase role="identifier">a</phrase><phrase role="special">.</phrase><phrase | |
3846 | role="identifier">allocate</phrase><phrase role="special">()</phrase></code> | |
3847 | </para> | |
3848 | </entry> | |
3849 | <entry> | |
3850 | <para> | |
3851 | <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html"><code><phrase | |
3852 | role="identifier">stack_context</phrase></code></ulink> | |
3853 | </para> | |
3854 | </entry> | |
3855 | <entry> | |
3856 | <para> | |
3857 | creates a stack | |
3858 | </para> | |
3859 | </entry> | |
3860 | </row> | |
3861 | <row> | |
3862 | <entry> | |
3863 | <para> | |
3864 | <code><phrase role="identifier">a</phrase><phrase role="special">.</phrase><phrase | |
3865 | role="identifier">deallocate</phrase><phrase role="special">(</phrase> | |
3866 | <phrase role="identifier">sctx</phrase><phrase role="special">)</phrase></code> | |
3867 | </para> | |
3868 | </entry> | |
3869 | <entry> | |
3870 | <para> | |
3871 | <code><phrase role="keyword">void</phrase></code> | |
3872 | </para> | |
3873 | </entry> | |
3874 | <entry> | |
3875 | <para> | |
3876 | deallocates the stack created by <code><phrase role="identifier">a</phrase><phrase | |
3877 | role="special">.</phrase><phrase role="identifier">allocate</phrase><phrase | |
3878 | role="special">()</phrase></code> | |
3879 | </para> | |
3880 | </entry> | |
3881 | </row> | |
3882 | </tbody> | |
3883 | </tgroup> | |
3884 | </informaltable> | |
3885 | <important> | |
3886 | <para> | |
3887 | The implementation of <code><phrase role="identifier">allocate</phrase><phrase | |
3888 | role="special">()</phrase></code> might include logic to protect against | |
3889 | exceeding the context's available stack size rather than leaving it as undefined | |
3890 | behaviour. | |
3891 | </para> | |
3892 | </important> | |
3893 | <important> | |
3894 | <para> | |
3895 | Calling <code><phrase role="identifier">deallocate</phrase><phrase role="special">()</phrase></code> | |
3896 | with a <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_context.html"><code><phrase | |
3897 | role="identifier">stack_context</phrase></code></ulink> not obtained from | |
3898 | <code><phrase role="identifier">allocate</phrase><phrase role="special">()</phrase></code> | |
3899 | results in undefined behaviour. | |
3900 | </para> | |
3901 | </important> | |
3902 | <note> | |
3903 | <para> | |
3904 | The memory for the stack is not required to be aligned; alignment takes place | |
3905 | inside <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/econtext.html"><emphasis>execution_context</emphasis></ulink>. | |
3906 | </para> | |
3907 | </note> | |
3908 | <para> | |
3909 | See also <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack.html">Boost.Context | |
3910 | stack allocation</ulink>. In particular, <code><phrase role="identifier">traits_type</phrase></code> | |
3911 | methods are as described for <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_traits.html"><code><phrase | |
3912 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase | |
3913 | role="special">::</phrase><phrase role="identifier">stack_traits</phrase></code></ulink>. | |
3914 | </para> | |
3915 | <para> | |
3916 | <bridgehead renderas="sect4" id="class_protected_fixedsize_stack_bridgehead"> | |
3917 | <phrase id="class_protected_fixedsize_stack"/> | |
3918 | <link linkend="class_protected_fixedsize_stack">Class | |
3919 | <code>protected_fixedsize_stack</code></link> | |
3920 | </bridgehead> | |
3921 | </para> | |
3922 | <para> | |
3923 | <emphasis role="bold">Boost.Fiber</emphasis> provides the class <link linkend="class_protected_fixedsize_stack"><code>protected_fixedsize_stack</code></link> which | |
3924 | models the <link linkend="stack_allocator_concept"><emphasis>stack-allocator | |
3925 | concept</emphasis></link>. It appends a guard page at the end of each stack | |
3926 | to protect against exceeding the stack. If the guard page is accessed (read | |
3927 | or write operation) a segmentation fault/access violation is generated by the | |
3928 | operating system. | |
3929 | </para> | |
3930 | <important> | |
3931 | <para> | |
3932 | Using <link linkend="class_protected_fixedsize_stack"><code>protected_fixedsize_stack</code></link> is expensive. | |
3933 | Launching a new fiber with a stack of this type incurs the overhead of setting | |
3934 | the memory protection; once allocated, this stack is just as efficient to | |
3935 | use as <link linkend="class_fixedsize_stack"><code>fixedsize_stack</code></link>. | |
3936 | </para> | |
3937 | </important> | |
3938 | <note> | |
3939 | <para> | |
3940 | The appended <code><phrase role="identifier">guard</phrase> <phrase role="identifier">page</phrase></code> | |
3941 | is <emphasis role="bold">not</emphasis> mapped to physical memory, only virtual | |
3942 | addresses are used. | |
3943 | </para> | |
3944 | </note> | |
3945 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">protected_fixedsize</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
3946 | ||
3947 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
3948 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
3949 | ||
3950 | <phrase role="keyword">struct</phrase> <phrase role="identifier">protected_fixedsize</phrase> <phrase role="special">{</phrase> | |
3951 | <phrase role="identifier">protected_fixesize</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase role="identifier">default_size</phrase><phrase role="special">());</phrase> | |
3952 | ||
3953 | <phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
3954 | ||
3955 | <phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&);</phrase> | |
3956 | <phrase role="special">}</phrase> | |
3957 | ||
3958 | <phrase role="special">}}</phrase> | |
3959 | </programlisting> | |
3960 | <para> | |
3961 | <bridgehead renderas="sect4" id="protected_fixedsize_allocate_bridgehead"> | |
3962 | <phrase id="protected_fixedsize_allocate"/> | |
3963 | <link linkend="protected_fixedsize_allocate">Member | |
3964 | function <code>allocate</code>()</link> | |
3965 | </bridgehead> | |
3966 | </para> | |
3967 | <programlisting><phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
3968 | </programlisting> | |
3969 | <variablelist> | |
3970 | <title></title> | |
3971 | <varlistentry> | |
3972 | <term>Preconditions:</term> | |
3973 | <listitem> | |
3974 | <para> | |
3975 | <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
3976 | role="identifier">minimum_size</phrase><phrase role="special">()</phrase> | |
3977 | <phrase role="special"><=</phrase> <phrase role="identifier">size</phrase></code> | |
3978 | and <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
3979 | role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> | |
3980 | <phrase role="special">||</phrase> <phrase role="special">(</phrase> | |
3981 | <phrase role="identifier">size</phrase> <phrase role="special"><=</phrase> | |
3982 | <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
3983 | role="identifier">maximum_size</phrase><phrase role="special">()</phrase> | |
3984 | <phrase role="special">)</phrase></code>. | |
3985 | </para> | |
3986 | </listitem> | |
3987 | </varlistentry> | |
3988 | <varlistentry> | |
3989 | <term>Effects:</term> | |
3990 | <listitem> | |
3991 | <para> | |
3992 | Allocates memory of at least <code><phrase role="identifier">size</phrase></code> | |
3993 | bytes and stores a pointer to the stack and its actual size in <code><phrase | |
3994 | role="identifier">sctx</phrase></code>. Depending on the architecture | |
3995 | (the stack grows downwards/upwards) the stored address is the highest/lowest | |
3996 | address of the stack. | |
3997 | </para> | |
3998 | </listitem> | |
3999 | </varlistentry> | |
4000 | </variablelist> | |
4001 | <para> | |
4002 | <bridgehead renderas="sect4" id="protected_fixesize_deallocate_bridgehead"> | |
4003 | <phrase id="protected_fixesize_deallocate"/> | |
4004 | <link linkend="protected_fixesize_deallocate">Member | |
4005 | function <code>deallocate</code>()</link> | |
4006 | </bridgehead> | |
4007 | </para> | |
4008 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">);</phrase> | |
4009 | </programlisting> | |
4010 | <variablelist> | |
4011 | <title></title> | |
4012 | <varlistentry> | |
4013 | <term>Preconditions:</term> | |
4014 | <listitem> | |
4015 | <para> | |
4016 | <code><phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4017 | role="identifier">sp</phrase></code> is valid, <code><phrase role="identifier">traits_type</phrase><phrase | |
4018 | role="special">::</phrase><phrase role="identifier">minimum_size</phrase><phrase | |
4019 | role="special">()</phrase> <phrase role="special"><=</phrase> <phrase | |
4020 | role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4021 | role="identifier">size</phrase></code> and <code><phrase role="identifier">traits_type</phrase><phrase | |
4022 | role="special">::</phrase><phrase role="identifier">is_unbounded</phrase><phrase | |
4023 | role="special">()</phrase> <phrase role="special">||</phrase> <phrase | |
4024 | role="special">(</phrase> <phrase role="identifier">sctx</phrase><phrase | |
4025 | role="special">.</phrase><phrase role="identifier">size</phrase> <phrase | |
4026 | role="special"><=</phrase> <phrase role="identifier">traits_type</phrase><phrase | |
4027 | role="special">::</phrase><phrase role="identifier">maximum_size</phrase><phrase | |
4028 | role="special">()</phrase> <phrase role="special">)</phrase></code>. | |
4029 | </para> | |
4030 | </listitem> | |
4031 | </varlistentry> | |
4032 | <varlistentry> | |
4033 | <term>Effects:</term> | |
4034 | <listitem> | |
4035 | <para> | |
4036 | Deallocates the stack space. | |
4037 | </para> | |
4038 | </listitem> | |
4039 | </varlistentry> | |
4040 | </variablelist> | |
4041 | <para> | |
4042 | <bridgehead renderas="sect4" id="class_pooled_fixedsize_stack_bridgehead"> | |
4043 | <phrase id="class_pooled_fixedsize_stack"/> | |
4044 | <link linkend="class_pooled_fixedsize_stack">Class | |
4045 | <code>pooled_fixedsize_stack</code></link> | |
4046 | </bridgehead> | |
4047 | </para> | |
4048 | <para> | |
4049 | <emphasis role="bold">Boost.Fiber</emphasis> provides the class <link linkend="class_pooled_fixedsize_stack"><code>pooled_fixedsize_stack</code></link> which | |
4050 | models the <link linkend="stack_allocator_concept"><emphasis>stack-allocator | |
4051 | concept</emphasis></link>. In contrast to <link linkend="class_protected_fixedsize_stack"><code>protected_fixedsize_stack</code></link> it | |
4052 | does not append a guard page at the end of each stack. The memory is managed | |
4053 | internally by <ulink url="http://www.boost.org/doc/libs/release/libs/pool/doc/html/boost/pool.html"><code><phrase | |
4054 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">pool</phrase><phrase | |
4055 | role="special"><></phrase></code></ulink>. | |
4056 | </para> | |
4057 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">pooled_fixedsize_stack</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
4058 | ||
4059 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
4060 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
4061 | ||
4062 | <phrase role="keyword">struct</phrase> <phrase role="identifier">pooled_fixedsize_stack</phrase> <phrase role="special">{</phrase> | |
4063 | <phrase role="identifier">pooled_fixedsize_stack</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">stack_size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase role="identifier">default_size</phrase><phrase role="special">(),</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">next_size</phrase> <phrase role="special">=</phrase> <phrase role="number">32</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">max_size</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">);</phrase> | |
4064 | ||
4065 | <phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
4066 | ||
4067 | <phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&);</phrase> | |
4068 | <phrase role="special">}</phrase> | |
4069 | ||
4070 | <phrase role="special">}}</phrase> | |
4071 | </programlisting> | |
4072 | <para> | |
4073 | <bridgehead renderas="sect4" id="pooled_fixedsize_bridgehead"> | |
4074 | <phrase id="pooled_fixedsize"/> | |
4075 | <link linkend="pooled_fixedsize">Constructor</link> | |
4076 | </bridgehead> | |
4077 | </para> | |
4078 | <programlisting><phrase role="identifier">pooled_fixedsize_stack</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">stack_size</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">next_size</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">max_size</phrase><phrase role="special">);</phrase> | |
4079 | </programlisting> | |
4080 | <variablelist> | |
4081 | <title></title> | |
4082 | <varlistentry> | |
4083 | <term>Preconditions:</term> | |
4084 | <listitem> | |
4085 | <para> | |
4086 | <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4087 | role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> | |
4088 | <phrase role="special">||</phrase> <phrase role="special">(</phrase> | |
4089 | <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4090 | role="identifier">maximum_size</phrase><phrase role="special">()</phrase> | |
4091 | <phrase role="special">>=</phrase> <phrase role="identifier">stack_size</phrase><phrase | |
4092 | role="special">)</phrase></code> and <code><phrase role="number">0</phrase> | |
4093 | <phrase role="special"><</phrase> <phrase role="identifier">next_size</phrase></code>. | |
4094 | </para> | |
4095 | </listitem> | |
4096 | </varlistentry> | |
4097 | <varlistentry> | |
4098 | <term>Effects:</term> | |
4099 | <listitem> | |
4100 | <para> | |
4101 | Allocates memory of at least <code><phrase role="identifier">stack_size</phrase></code> | |
4102 | bytes and stores a pointer to the stack and its actual size in <code><phrase | |
4103 | role="identifier">sctx</phrase></code>. Depending on the architecture | |
4104 | (the stack grows downwards/upwards) the stored address is the highest/lowest | |
4105 | address of the stack. Argument <code><phrase role="identifier">next_size</phrase></code> | |
4106 | determines the number of stacks to request from the system the first | |
4107 | time that <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
4108 | needs to allocate system memory. The third argument <code><phrase role="identifier">max_size</phrase></code> | |
4109 | controls how much memory might be allocated for stacks — a value of zero | |
4110 | means no upper limit. | |
4111 | </para> | |
4112 | </listitem> | |
4113 | </varlistentry> | |
4114 | </variablelist> | |
4115 | <para> | |
4116 | <bridgehead renderas="sect4" id="pooled_fixedsize_allocate_bridgehead"> | |
4117 | <phrase id="pooled_fixedsize_allocate"/> | |
4118 | <link linkend="pooled_fixedsize_allocate">Member | |
4119 | function <code>allocate</code>()</link> | |
4120 | </bridgehead> | |
4121 | </para> | |
4122 | <programlisting><phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
4123 | </programlisting> | |
4124 | <variablelist> | |
4125 | <title></title> | |
4126 | <varlistentry> | |
4127 | <term>Preconditions:</term> | |
4128 | <listitem> | |
4129 | <para> | |
4130 | <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4131 | role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> | |
4132 | <phrase role="special">||</phrase> <phrase role="special">(</phrase> | |
4133 | <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4134 | role="identifier">maximum_size</phrase><phrase role="special">()</phrase> | |
4135 | <phrase role="special">>=</phrase> <phrase role="identifier">stack_size</phrase><phrase | |
4136 | role="special">)</phrase></code>. | |
4137 | </para> | |
4138 | </listitem> | |
4139 | </varlistentry> | |
4140 | <varlistentry> | |
4141 | <term>Effects:</term> | |
4142 | <listitem> | |
4143 | <para> | |
4144 | Allocates memory of at least <code><phrase role="identifier">stack_size</phrase></code> | |
4145 | bytes and stores a pointer to the stack and its actual size in <code><phrase | |
4146 | role="identifier">sctx</phrase></code>. Depending on the architecture | |
4147 | (the stack grows downwards/upwards) the stored address is the highest/lowest | |
4148 | address of the stack. | |
4149 | </para> | |
4150 | </listitem> | |
4151 | </varlistentry> | |
4152 | </variablelist> | |
4153 | <para> | |
4154 | <bridgehead renderas="sect4" id="pooled_fixesize_deallocate_bridgehead"> | |
4155 | <phrase id="pooled_fixesize_deallocate"/> | |
4156 | <link linkend="pooled_fixesize_deallocate">Member | |
4157 | function <code>deallocate</code>()</link> | |
4158 | </bridgehead> | |
4159 | </para> | |
4160 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">);</phrase> | |
4161 | </programlisting> | |
4162 | <variablelist> | |
4163 | <title></title> | |
4164 | <varlistentry> | |
4165 | <term>Preconditions:</term> | |
4166 | <listitem> | |
4167 | <para> | |
4168 | <code><phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4169 | role="identifier">sp</phrase></code> is valid, <code><phrase role="identifier">traits_type</phrase><phrase | |
4170 | role="special">::</phrase><phrase role="identifier">is_unbounded</phrase><phrase | |
4171 | role="special">()</phrase> <phrase role="special">||</phrase> <phrase | |
4172 | role="special">(</phrase> <phrase role="identifier">traits_type</phrase><phrase | |
4173 | role="special">::</phrase><phrase role="identifier">maximum_size</phrase><phrase | |
4174 | role="special">()</phrase> <phrase role="special">>=</phrase> <phrase | |
4175 | role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4176 | role="identifier">size</phrase><phrase role="special">)</phrase></code>. | |
4177 | </para> | |
4178 | </listitem> | |
4179 | </varlistentry> | |
4180 | <varlistentry> | |
4181 | <term>Effects:</term> | |
4182 | <listitem> | |
4183 | <para> | |
4184 | Deallocates the stack space. | |
4185 | </para> | |
4186 | </listitem> | |
4187 | </varlistentry> | |
4188 | </variablelist> | |
4189 | <note> | |
4190 | <para> | |
4191 | This stack allocator is not thread safe. | |
4192 | </para> | |
4193 | </note> | |
4194 | <para> | |
4195 | <bridgehead renderas="sect4" id="class_fixedsize_stack_bridgehead"> | |
4196 | <phrase id="class_fixedsize_stack"/> | |
4197 | <link linkend="class_fixedsize_stack">Class | |
4198 | <code>fixedsize_stack</code></link> | |
4199 | </bridgehead> | |
4200 | </para> | |
4201 | <para> | |
4202 | <emphasis role="bold">Boost.Fiber</emphasis> provides the class <link linkend="class_fixedsize_stack"><code>fixedsize_stack</code></link> which | |
4203 | models the <link linkend="stack_allocator_concept"><emphasis>stack-allocator | |
4204 | concept</emphasis></link>. In contrast to <link linkend="class_protected_fixedsize_stack"><code>protected_fixedsize_stack</code></link> it | |
4205 | does not append a guard page at the end of each stack. The memory is simply | |
4206 | managed by <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
4207 | role="identifier">malloc</phrase><phrase role="special">()</phrase></code> | |
4208 | and <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
4209 | role="identifier">free</phrase><phrase role="special">()</phrase></code>. | |
4210 | </para> | |
4211 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">context</phrase><phrase role="special">/</phrase><phrase role="identifier">fixedsize_stack</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
4212 | ||
4213 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
4214 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
4215 | ||
4216 | <phrase role="keyword">struct</phrase> <phrase role="identifier">fixedsize_stack</phrase> <phrase role="special">{</phrase> | |
4217 | <phrase role="identifier">fixedsize_stack</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase role="identifier">default_size</phrase><phrase role="special">());</phrase> | |
4218 | ||
4219 | <phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
4220 | ||
4221 | <phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&);</phrase> | |
4222 | <phrase role="special">}</phrase> | |
4223 | ||
4224 | <phrase role="special">}}</phrase> | |
4225 | </programlisting> | |
4226 | <para> | |
4227 | <bridgehead renderas="sect4" id="fixedsize_allocate_bridgehead"> | |
4228 | <phrase id="fixedsize_allocate"/> | |
4229 | <link linkend="fixedsize_allocate">Member function | |
4230 | <code>allocate</code>()</link> | |
4231 | </bridgehead> | |
4232 | </para> | |
4233 | <programlisting><phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
4234 | </programlisting> | |
4235 | <variablelist> | |
4236 | <title></title> | |
4237 | <varlistentry> | |
4238 | <term>Preconditions:</term> | |
4239 | <listitem> | |
4240 | <para> | |
4241 | <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4242 | role="identifier">minimum_size</phrase><phrase role="special">()</phrase> | |
4243 | <phrase role="special"><=</phrase> <phrase role="identifier">size</phrase></code> | |
4244 | and <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4245 | role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> | |
4246 | <phrase role="special">||</phrase> <phrase role="special">(</phrase> | |
4247 | <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4248 | role="identifier">maximum_size</phrase><phrase role="special">()</phrase> | |
4249 | <phrase role="special">>=</phrase> <phrase role="identifier">size</phrase><phrase | |
4250 | role="special">)</phrase></code>. | |
4251 | </para> | |
4252 | </listitem> | |
4253 | </varlistentry> | |
4254 | <varlistentry> | |
4255 | <term>Effects:</term> | |
4256 | <listitem> | |
4257 | <para> | |
4258 | Allocates memory of at least <code><phrase role="identifier">size</phrase></code> | |
4259 | bytes and stores a pointer to the stack and its actual size in <code><phrase | |
4260 | role="identifier">sctx</phrase></code>. Depending on the architecture | |
4261 | (the stack grows downwards/upwards) the stored address is the highest/lowest | |
4262 | address of the stack. | |
4263 | </para> | |
4264 | </listitem> | |
4265 | </varlistentry> | |
4266 | </variablelist> | |
4267 | <para> | |
4268 | <bridgehead renderas="sect4" id="fixesize_deallocate_bridgehead"> | |
4269 | <phrase id="fixesize_deallocate"/> | |
4270 | <link linkend="fixesize_deallocate">Member | |
4271 | function <code>deallocate</code>()</link> | |
4272 | </bridgehead> | |
4273 | </para> | |
4274 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">);</phrase> | |
4275 | </programlisting> | |
4276 | <variablelist> | |
4277 | <title></title> | |
4278 | <varlistentry> | |
4279 | <term>Preconditions:</term> | |
4280 | <listitem> | |
4281 | <para> | |
4282 | <code><phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4283 | role="identifier">sp</phrase></code> is valid, <code><phrase role="identifier">traits_type</phrase><phrase | |
4284 | role="special">::</phrase><phrase role="identifier">minimum_size</phrase><phrase | |
4285 | role="special">()</phrase> <phrase role="special"><=</phrase> <phrase | |
4286 | role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4287 | role="identifier">size</phrase></code> and <code><phrase role="identifier">traits_type</phrase><phrase | |
4288 | role="special">::</phrase><phrase role="identifier">is_unbounded</phrase><phrase | |
4289 | role="special">()</phrase> <phrase role="special">||</phrase> <phrase | |
4290 | role="special">(</phrase> <phrase role="identifier">traits_type</phrase><phrase | |
4291 | role="special">::</phrase><phrase role="identifier">maximum_size</phrase><phrase | |
4292 | role="special">()</phrase> <phrase role="special">>=</phrase> <phrase | |
4293 | role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4294 | role="identifier">size</phrase><phrase role="special">)</phrase></code>. | |
4295 | </para> | |
4296 | </listitem> | |
4297 | </varlistentry> | |
4298 | <varlistentry> | |
4299 | <term>Effects:</term> | |
4300 | <listitem> | |
4301 | <para> | |
4302 | Deallocates the stack space. | |
4303 | </para> | |
4304 | </listitem> | |
4305 | </varlistentry> | |
4306 | </variablelist> | |
4307 | <para> | |
4308 | <bridgehead renderas="sect4" id="class_segmented_stack_bridgehead"> | |
4309 | <phrase id="class_segmented_stack"/> | |
4310 | <link linkend="class_segmented_stack">Class | |
4311 | <code>segmented_stack</code></link> | |
4312 | </bridgehead> | |
4313 | </para> | |
4314 | <para> | |
4315 | <emphasis role="bold">Boost.Fiber</emphasis> supports usage of a <link linkend="class_segmented_stack"><code>segmented_stack</code></link>, | |
4316 | i.e. the stack grows on demand. The fiber is created with a minimal stack size | |
4317 | which will be increased as required. Class <link linkend="class_segmented_stack"><code>segmented_stack</code></link> models | |
4318 | the <link linkend="stack_allocator_concept"><emphasis>stack-allocator concept</emphasis></link>. | |
4319 | In contrast to <link linkend="class_protected_fixedsize_stack"><code>protected_fixedsize_stack</code></link> and | |
4320 | <link linkend="class_fixedsize_stack"><code>fixedsize_stack</code></link> it creates a stack which grows on demand. | |
4321 | </para> | |
4322 | <note> | |
4323 | <para> | |
4324 | Segmented stacks are currently only supported by <emphasis role="bold">gcc</emphasis> | |
4325 | from version <emphasis role="bold">4.7</emphasis> and <emphasis role="bold">clang</emphasis> | |
4326 | from version <emphasis role="bold">3.4</emphasis> onwards. In order to use | |
4327 | a <link linkend="class_segmented_stack"><code>segmented_stack</code></link> <emphasis role="bold">Boost.Fiber</emphasis> | |
4328 | must be built with property <code><phrase role="identifier">segmented</phrase><phrase | |
4329 | role="special">-</phrase><phrase role="identifier">stacks</phrase></code>, | |
4330 | e.g. <emphasis role="bold">toolset=gcc segmented-stacks=on</emphasis> at | |
4331 | b2/bjam command line. | |
4332 | </para> | |
4333 | </note> | |
4334 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">segmented_stack</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
4335 | ||
4336 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
4337 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
4338 | ||
4339 | <phrase role="keyword">struct</phrase> <phrase role="identifier">segmented_stack</phrase> <phrase role="special">{</phrase> | |
4340 | <phrase role="identifier">segmented_stack</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">stack_size</phrase> <phrase role="special">=</phrase> <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase role="identifier">default_size</phrase><phrase role="special">());</phrase> | |
4341 | ||
4342 | <phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
4343 | ||
4344 | <phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&);</phrase> | |
4345 | <phrase role="special">}</phrase> | |
4346 | ||
4347 | <phrase role="special">}}</phrase> | |
4348 | </programlisting> | |
4349 | <para> | |
4350 | <bridgehead renderas="sect4" id="segmented_allocate_bridgehead"> | |
4351 | <phrase id="segmented_allocate"/> | |
4352 | <link linkend="segmented_allocate">Member function | |
4353 | <code>allocate</code>()</link> | |
4354 | </bridgehead> | |
4355 | </para> | |
4356 | <programlisting><phrase role="identifier">stack_context</phrase> <phrase role="identifier">allocate</phrase><phrase role="special">();</phrase> | |
4357 | </programlisting> | |
4358 | <variablelist> | |
4359 | <title></title> | |
4360 | <varlistentry> | |
4361 | <term>Preconditions:</term> | |
4362 | <listitem> | |
4363 | <para> | |
4364 | <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4365 | role="identifier">minimum_size</phrase><phrase role="special">()</phrase> | |
4366 | <phrase role="special"><=</phrase> <phrase role="identifier">size</phrase></code> | |
4367 | and <code><phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4368 | role="identifier">is_unbounded</phrase><phrase role="special">()</phrase> | |
4369 | <phrase role="special">||</phrase> <phrase role="special">(</phrase> | |
4370 | <phrase role="identifier">traits_type</phrase><phrase role="special">::</phrase><phrase | |
4371 | role="identifier">maximum_size</phrase><phrase role="special">()</phrase> | |
4372 | <phrase role="special">>=</phrase> <phrase role="identifier">size</phrase><phrase | |
4373 | role="special">)</phrase></code>. | |
4374 | </para> | |
4375 | </listitem> | |
4376 | </varlistentry> | |
4377 | <varlistentry> | |
4378 | <term>Effects:</term> | |
4379 | <listitem> | |
4380 | <para> | |
4381 | Allocates memory of at least <code><phrase role="identifier">size</phrase></code> | |
4382 | bytes and stores a pointer to the stack and its actual size in <code><phrase | |
4383 | role="identifier">sctx</phrase></code>. Depending on the architecture | |
4384 | (the stack grows downwards/upwards) the stored address is the highest/lowest | |
4385 | address of the stack. | |
4386 | </para> | |
4387 | </listitem> | |
4388 | </varlistentry> | |
4389 | </variablelist> | |
4390 | <para> | |
4391 | <bridgehead renderas="sect4" id="segmented_deallocate_bridgehead"> | |
4392 | <phrase id="segmented_deallocate"/> | |
4393 | <link linkend="segmented_deallocate">Member | |
4394 | function <code>deallocate</code>()</link> | |
4395 | </bridgehead> | |
4396 | </para> | |
4397 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">deallocate</phrase><phrase role="special">(</phrase> <phrase role="identifier">stack_context</phrase> <phrase role="special">&</phrase> <phrase role="identifier">sctx</phrase><phrase role="special">);</phrase> | |
4398 | </programlisting> | |
4399 | <variablelist> | |
4400 | <title></title> | |
4401 | <varlistentry> | |
4402 | <term>Preconditions:</term> | |
4403 | <listitem> | |
4404 | <para> | |
4405 | <code><phrase role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4406 | role="identifier">sp</phrase></code> is valid, <code><phrase role="identifier">traits_type</phrase><phrase | |
4407 | role="special">::</phrase><phrase role="identifier">minimum_size</phrase><phrase | |
4408 | role="special">()</phrase> <phrase role="special"><=</phrase> <phrase | |
4409 | role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4410 | role="identifier">size</phrase></code> and <code><phrase role="identifier">traits_type</phrase><phrase | |
4411 | role="special">::</phrase><phrase role="identifier">is_unbounded</phrase><phrase | |
4412 | role="special">()</phrase> <phrase role="special">||</phrase> <phrase | |
4413 | role="special">(</phrase> <phrase role="identifier">traits_type</phrase><phrase | |
4414 | role="special">::</phrase><phrase role="identifier">maximum_size</phrase><phrase | |
4415 | role="special">()</phrase> <phrase role="special">>=</phrase> <phrase | |
4416 | role="identifier">sctx</phrase><phrase role="special">.</phrase><phrase | |
4417 | role="identifier">size</phrase><phrase role="special">)</phrase></code>. | |
4418 | </para> | |
4419 | </listitem> | |
4420 | </varlistentry> | |
4421 | <varlistentry> | |
4422 | <term>Effects:</term> | |
4423 | <listitem> | |
4424 | <para> | |
4425 | Deallocates the stack space. | |
4426 | </para> | |
4427 | </listitem> | |
4428 | </varlistentry> | |
4429 | </variablelist> | |
4430 | <note> | |
4431 | <para> | |
4432 | If the library is compiled for segmented stacks, <link linkend="class_segmented_stack"><code>segmented_stack</code></link> is | |
4433 | the only available stack allocator. | |
4434 | </para> | |
4435 | </note> | |
4436 | </section> | |
4437 | <section id="fiber.synchronization"> | |
4438 | <title><anchor id="synchronization"/><link linkend="fiber.synchronization">Synchronization</link></title> | |
4439 | <para> | |
4440 | In general, <emphasis role="bold">Boost.Fiber</emphasis> synchronization objects | |
4441 | can neither be moved nor copied. A synchronization object acts as a mutually-agreed | |
4442 | rendezvous point between different fibers. If such an object were copied somewhere | |
4443 | else, the new copy would have no consumers. If such an object were <emphasis>moved</emphasis> | |
4444 | somewhere else, leaving the original instance in an unspecified state, existing | |
4445 | consumers would behave strangely. | |
4446 | </para> | |
4447 | <para> | |
4448 | The fiber synchronization objects provided by this library will, by default, | |
4449 | safely synchronize fibers running on different threads. However, this level | |
4450 | of synchronization can be removed (for performance) by building the library | |
4451 | with <emphasis role="bold"><code><phrase role="identifier">BOOST_FIBERS_NO_ATOMICS</phrase></code></emphasis> | |
4452 | defined. When the library is built with that macro, you must ensure that all | |
4453 | the fibers referencing a particular synchronization object are running in the | |
4454 | same thread. | |
4455 | </para> | |
4456 | <section id="fiber.synchronization.mutex_types"> | |
4457 | <title><link linkend="fiber.synchronization.mutex_types">Mutex Types</link></title> | |
4458 | <para> | |
4459 | <bridgehead renderas="sect4" id="class_mutex_bridgehead"> | |
4460 | <phrase id="class_mutex"/> | |
4461 | <link linkend="class_mutex">Class <code>mutex</code></link> | |
4462 | </bridgehead> | |
4463 | </para> | |
4464 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
4465 | ||
4466 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
4467 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
4468 | ||
4469 | <phrase role="keyword">class</phrase> <phrase role="identifier">mutex</phrase> <phrase role="special">{</phrase> | |
4470 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
4471 | <phrase role="identifier">mutex</phrase><phrase role="special">();</phrase> | |
4472 | <phrase role="special">~</phrase><phrase role="identifier">mutex</phrase><phrase role="special">();</phrase> | |
4473 | ||
4474 | <phrase role="identifier">mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
4475 | <phrase role="identifier">mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
4476 | ||
4477 | <phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
4478 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase> | |
4479 | <phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
4480 | <phrase role="special">};</phrase> | |
4481 | ||
4482 | <phrase role="special">}}</phrase> | |
4483 | </programlisting> | |
4484 | <para> | |
4485 | <link linkend="class_mutex"><code>mutex</code></link> provides an exclusive-ownership mutex. At most one fiber | |
4486 | can own the lock on a given instance of <link linkend="class_mutex"><code>mutex</code></link> at any time. Multiple | |
4487 | concurrent calls to <code><phrase role="identifier">lock</phrase><phrase | |
4488 | role="special">()</phrase></code>, <code><phrase role="identifier">try_lock</phrase><phrase | |
4489 | role="special">()</phrase></code> and <code><phrase role="identifier">unlock</phrase><phrase | |
4490 | role="special">()</phrase></code> shall be permitted. | |
4491 | </para> | |
4492 | <para> | |
4493 | Any fiber blocked in <code><phrase role="identifier">lock</phrase><phrase | |
4494 | role="special">()</phrase></code> is suspended until the owning fiber releases | |
4495 | the lock by calling <code><phrase role="identifier">unlock</phrase><phrase | |
4496 | role="special">()</phrase></code>. | |
4497 | </para> | |
4498 | <para> | |
4499 | <bridgehead renderas="sect4" id="mutex_lock_bridgehead"> | |
4500 | <phrase id="mutex_lock"/> | |
4501 | <link linkend="mutex_lock">Member function <code>lock</code>()</link> | |
4502 | </bridgehead> | |
4503 | </para> | |
4504 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
4505 | </programlisting> | |
4506 | <variablelist> | |
4507 | <title></title> | |
4508 | <varlistentry> | |
4509 | <term>Precondition:</term> | |
4510 | <listitem> | |
4511 | <para> | |
4512 | The calling fiber doesn't own the mutex. | |
4513 | </para> | |
4514 | </listitem> | |
4515 | </varlistentry> | |
4516 | <varlistentry> | |
4517 | <term>Effects:</term> | |
4518 | <listitem> | |
4519 | <para> | |
4520 | The current fiber blocks until ownership can be obtained. | |
4521 | </para> | |
4522 | </listitem> | |
4523 | </varlistentry> | |
4524 | <varlistentry> | |
4525 | <term>Throws:</term> | |
4526 | <listitem> | |
4527 | <para> | |
4528 | <code><phrase role="identifier">lock_error</phrase></code> | |
4529 | </para> | |
4530 | </listitem> | |
4531 | </varlistentry> | |
4532 | <varlistentry> | |
4533 | <term>Error Conditions:</term> | |
4534 | <listitem> | |
4535 | <para> | |
4536 | <emphasis role="bold">resource_deadlock_would_occur</emphasis>: if | |
4537 | <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4538 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4539 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4540 | already owns the mutex. | |
4541 | </para> | |
4542 | </listitem> | |
4543 | </varlistentry> | |
4544 | </variablelist> | |
4545 | <para> | |
4546 | <bridgehead renderas="sect4" id="mutex_try_lock_bridgehead"> | |
4547 | <phrase id="mutex_try_lock"/> | |
4548 | <link linkend="mutex_try_lock">Member function <code>try_lock</code>()</link> | |
4549 | </bridgehead> | |
4550 | </para> | |
4551 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase> | |
4552 | </programlisting> | |
4553 | <variablelist> | |
4554 | <title></title> | |
4555 | <varlistentry> | |
4556 | <term>Precondition:</term> | |
4557 | <listitem> | |
4558 | <para> | |
4559 | The calling fiber doesn't own the mutex. | |
4560 | </para> | |
4561 | </listitem> | |
4562 | </varlistentry> | |
4563 | <varlistentry> | |
4564 | <term>Effects:</term> | |
4565 | <listitem> | |
4566 | <para> | |
4567 | Attempt to obtain ownership for the current fiber without blocking. | |
4568 | </para> | |
4569 | </listitem> | |
4570 | </varlistentry> | |
4571 | <varlistentry> | |
4572 | <term>Returns:</term> | |
4573 | <listitem> | |
4574 | <para> | |
4575 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
4576 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
4577 | otherwise. | |
4578 | </para> | |
4579 | </listitem> | |
4580 | </varlistentry> | |
4581 | <varlistentry> | |
4582 | <term>Throws:</term> | |
4583 | <listitem> | |
4584 | <para> | |
4585 | <code><phrase role="identifier">lock_error</phrase></code> | |
4586 | </para> | |
4587 | </listitem> | |
4588 | </varlistentry> | |
4589 | <varlistentry> | |
4590 | <term>Error Conditions:</term> | |
4591 | <listitem> | |
4592 | <para> | |
4593 | <emphasis role="bold">resource_deadlock_would_occur</emphasis>: if | |
4594 | <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4595 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4596 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4597 | already owns the mutex. | |
4598 | </para> | |
4599 | </listitem> | |
4600 | </varlistentry> | |
4601 | </variablelist> | |
4602 | <para> | |
4603 | <bridgehead renderas="sect4" id="mutex_unlock_bridgehead"> | |
4604 | <phrase id="mutex_unlock"/> | |
4605 | <link linkend="mutex_unlock">Member function <code>unlock</code>()</link> | |
4606 | </bridgehead> | |
4607 | </para> | |
4608 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
4609 | </programlisting> | |
4610 | <variablelist> | |
4611 | <title></title> | |
4612 | <varlistentry> | |
4613 | <term>Precondition:</term> | |
4614 | <listitem> | |
4615 | <para> | |
4616 | The current fiber owns <code><phrase role="special">*</phrase><phrase | |
4617 | role="keyword">this</phrase></code>. | |
4618 | </para> | |
4619 | </listitem> | |
4620 | </varlistentry> | |
4621 | <varlistentry> | |
4622 | <term>Effects:</term> | |
4623 | <listitem> | |
4624 | <para> | |
4625 | Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
4626 | by the current fiber. | |
4627 | </para> | |
4628 | </listitem> | |
4629 | </varlistentry> | |
4630 | <varlistentry> | |
4631 | <term>Throws:</term> | |
4632 | <listitem> | |
4633 | <para> | |
4634 | <code><phrase role="identifier">lock_error</phrase></code> | |
4635 | </para> | |
4636 | </listitem> | |
4637 | </varlistentry> | |
4638 | <varlistentry> | |
4639 | <term>Error Conditions:</term> | |
4640 | <listitem> | |
4641 | <para> | |
4642 | <emphasis role="bold">operation_not_permitted</emphasis>: if <code><phrase | |
4643 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4644 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4645 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4646 | does not own the mutex. | |
4647 | </para> | |
4648 | </listitem> | |
4649 | </varlistentry> | |
4650 | </variablelist> | |
4651 | <para> | |
4652 | <bridgehead renderas="sect4" id="class_timed_mutex_bridgehead"> | |
4653 | <phrase id="class_timed_mutex"/> | |
4654 | <link linkend="class_timed_mutex">Class <code>timed_mutex</code></link> | |
4655 | </bridgehead> | |
4656 | </para> | |
4657 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">timed_mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
4658 | ||
4659 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
4660 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
4661 | ||
4662 | <phrase role="keyword">class</phrase> <phrase role="identifier">timed_mutex</phrase> <phrase role="special">{</phrase> | |
4663 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
4664 | <phrase role="identifier">timed_mutex</phrase><phrase role="special">();</phrase> | |
4665 | <phrase role="special">~</phrase><phrase role="identifier">timed_mutex</phrase><phrase role="special">();</phrase> | |
4666 | ||
4667 | <phrase role="identifier">timed_mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
4668 | <phrase role="identifier">timed_mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
4669 | ||
4670 | <phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
4671 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase> | |
4672 | <phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
4673 | ||
4674 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
4675 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
4676 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
4677 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
4678 | <phrase role="special">};</phrase> | |
4679 | ||
4680 | <phrase role="special">}}</phrase> | |
4681 | </programlisting> | |
4682 | <para> | |
4683 | <link linkend="class_timed_mutex"><code>timed_mutex</code></link> provides an exclusive-ownership mutex. At most | |
4684 | one fiber can own the lock on a given instance of <link linkend="class_timed_mutex"><code>timed_mutex</code></link> at | |
4685 | any time. Multiple concurrent calls to <code><phrase role="identifier">lock</phrase><phrase | |
4686 | role="special">()</phrase></code>, <code><phrase role="identifier">try_lock</phrase><phrase | |
4687 | role="special">()</phrase></code>, <code><phrase role="identifier">try_lock_until</phrase><phrase | |
4688 | role="special">()</phrase></code>, <code><phrase role="identifier">try_lock_for</phrase><phrase | |
4689 | role="special">()</phrase></code> and <code><phrase role="identifier">unlock</phrase><phrase | |
4690 | role="special">()</phrase></code> shall be permitted. | |
4691 | </para> | |
4692 | <para> | |
4693 | <bridgehead renderas="sect4" id="timed_mutex_lock_bridgehead"> | |
4694 | <phrase id="timed_mutex_lock"/> | |
4695 | <link linkend="timed_mutex_lock">Member function | |
4696 | <code>lock</code>()</link> | |
4697 | </bridgehead> | |
4698 | </para> | |
4699 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
4700 | </programlisting> | |
4701 | <variablelist> | |
4702 | <title></title> | |
4703 | <varlistentry> | |
4704 | <term>Precondition:</term> | |
4705 | <listitem> | |
4706 | <para> | |
4707 | The calling fiber doesn't own the mutex. | |
4708 | </para> | |
4709 | </listitem> | |
4710 | </varlistentry> | |
4711 | <varlistentry> | |
4712 | <term>Effects:</term> | |
4713 | <listitem> | |
4714 | <para> | |
4715 | The current fiber blocks until ownership can be obtained. | |
4716 | </para> | |
4717 | </listitem> | |
4718 | </varlistentry> | |
4719 | <varlistentry> | |
4720 | <term>Throws:</term> | |
4721 | <listitem> | |
4722 | <para> | |
4723 | <code><phrase role="identifier">lock_error</phrase></code> | |
4724 | </para> | |
4725 | </listitem> | |
4726 | </varlistentry> | |
4727 | <varlistentry> | |
4728 | <term>Error Conditions:</term> | |
4729 | <listitem> | |
4730 | <para> | |
4731 | <emphasis role="bold">resource_deadlock_would_occur</emphasis>: if | |
4732 | <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4733 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4734 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4735 | already owns the mutex. | |
4736 | </para> | |
4737 | </listitem> | |
4738 | </varlistentry> | |
4739 | </variablelist> | |
4740 | <para> | |
4741 | <bridgehead renderas="sect4" id="timed_mutex_try_lock_bridgehead"> | |
4742 | <phrase id="timed_mutex_try_lock"/> | |
4743 | <link linkend="timed_mutex_try_lock">Member | |
4744 | function <code>try_lock</code>()</link> | |
4745 | </bridgehead> | |
4746 | </para> | |
4747 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">();</phrase> | |
4748 | </programlisting> | |
4749 | <variablelist> | |
4750 | <title></title> | |
4751 | <varlistentry> | |
4752 | <term>Precondition:</term> | |
4753 | <listitem> | |
4754 | <para> | |
4755 | The calling fiber doesn't own the mutex. | |
4756 | </para> | |
4757 | </listitem> | |
4758 | </varlistentry> | |
4759 | <varlistentry> | |
4760 | <term>Effects:</term> | |
4761 | <listitem> | |
4762 | <para> | |
4763 | Attempt to obtain ownership for the current fiber without blocking. | |
4764 | </para> | |
4765 | </listitem> | |
4766 | </varlistentry> | |
4767 | <varlistentry> | |
4768 | <term>Returns:</term> | |
4769 | <listitem> | |
4770 | <para> | |
4771 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
4772 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
4773 | otherwise. | |
4774 | </para> | |
4775 | </listitem> | |
4776 | </varlistentry> | |
4777 | <varlistentry> | |
4778 | <term>Throws:</term> | |
4779 | <listitem> | |
4780 | <para> | |
4781 | <code><phrase role="identifier">lock_error</phrase></code> | |
4782 | </para> | |
4783 | </listitem> | |
4784 | </varlistentry> | |
4785 | <varlistentry> | |
4786 | <term>Error Conditions:</term> | |
4787 | <listitem> | |
4788 | <para> | |
4789 | <emphasis role="bold">resource_deadlock_would_occur</emphasis>: if | |
4790 | <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4791 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4792 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4793 | already owns the mutex. | |
4794 | </para> | |
4795 | </listitem> | |
4796 | </varlistentry> | |
4797 | </variablelist> | |
4798 | <para> | |
4799 | <bridgehead renderas="sect4" id="timed_mutex_unlock_bridgehead"> | |
4800 | <phrase id="timed_mutex_unlock"/> | |
4801 | <link linkend="timed_mutex_unlock">Member function | |
4802 | <code>unlock</code>()</link> | |
4803 | </bridgehead> | |
4804 | </para> | |
4805 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
4806 | </programlisting> | |
4807 | <variablelist> | |
4808 | <title></title> | |
4809 | <varlistentry> | |
4810 | <term>Precondition:</term> | |
4811 | <listitem> | |
4812 | <para> | |
4813 | The current fiber owns <code><phrase role="special">*</phrase><phrase | |
4814 | role="keyword">this</phrase></code>. | |
4815 | </para> | |
4816 | </listitem> | |
4817 | </varlistentry> | |
4818 | <varlistentry> | |
4819 | <term>Effects:</term> | |
4820 | <listitem> | |
4821 | <para> | |
4822 | Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
4823 | by the current fiber. | |
4824 | </para> | |
4825 | </listitem> | |
4826 | </varlistentry> | |
4827 | <varlistentry> | |
4828 | <term>Throws:</term> | |
4829 | <listitem> | |
4830 | <para> | |
4831 | <code><phrase role="identifier">lock_error</phrase></code> | |
4832 | </para> | |
4833 | </listitem> | |
4834 | </varlistentry> | |
4835 | <varlistentry> | |
4836 | <term>Error Conditions:</term> | |
4837 | <listitem> | |
4838 | <para> | |
4839 | <emphasis role="bold">operation_not_permitted</emphasis>: if <code><phrase | |
4840 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4841 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4842 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4843 | does not own the mutex. | |
4844 | </para> | |
4845 | </listitem> | |
4846 | </varlistentry> | |
4847 | </variablelist> | |
4848 | <para> | |
4849 | <bridgehead renderas="sect4" id="timed_mutex_try_lock_until_bridgehead"> | |
4850 | <phrase id="timed_mutex_try_lock_until"/> | |
4851 | <link linkend="timed_mutex_try_lock_until">Templated | |
4852 | member function <code>try_lock_until</code>()</link> | |
4853 | </bridgehead> | |
4854 | </para> | |
4855 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
4856 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
4857 | </programlisting> | |
4858 | <variablelist> | |
4859 | <title></title> | |
4860 | <varlistentry> | |
4861 | <term>Precondition:</term> | |
4862 | <listitem> | |
4863 | <para> | |
4864 | The calling fiber doesn't own the mutex. | |
4865 | </para> | |
4866 | </listitem> | |
4867 | </varlistentry> | |
4868 | <varlistentry> | |
4869 | <term>Effects:</term> | |
4870 | <listitem> | |
4871 | <para> | |
4872 | Attempt to obtain ownership for the current fiber. Blocks until ownership | |
4873 | can be obtained, or the specified time is reached. If the specified | |
4874 | time has already passed, behaves as <link linkend="timed_mutex_try_lock"><code>timed_mutex::try_lock()</code></link>. | |
4875 | </para> | |
4876 | </listitem> | |
4877 | </varlistentry> | |
4878 | <varlistentry> | |
4879 | <term>Returns:</term> | |
4880 | <listitem> | |
4881 | <para> | |
4882 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
4883 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
4884 | otherwise. | |
4885 | </para> | |
4886 | </listitem> | |
4887 | </varlistentry> | |
4888 | <varlistentry> | |
4889 | <term>Throws:</term> | |
4890 | <listitem> | |
4891 | <para> | |
4892 | <code><phrase role="identifier">lock_error</phrase></code>, timeout-related | |
4893 | exceptions. | |
4894 | </para> | |
4895 | </listitem> | |
4896 | </varlistentry> | |
4897 | <varlistentry> | |
4898 | <term>Error Conditions:</term> | |
4899 | <listitem> | |
4900 | <para> | |
4901 | <emphasis role="bold">resource_deadlock_would_occur</emphasis>: if | |
4902 | <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4903 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4904 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4905 | already owns the mutex. | |
4906 | </para> | |
4907 | </listitem> | |
4908 | </varlistentry> | |
4909 | </variablelist> | |
4910 | <para> | |
4911 | <bridgehead renderas="sect4" id="timed_mutex_try_lock_for_bridgehead"> | |
4912 | <phrase id="timed_mutex_try_lock_for"/> | |
4913 | <link linkend="timed_mutex_try_lock_for">Templated | |
4914 | member function <code>try_lock_for</code>()</link> | |
4915 | </bridgehead> | |
4916 | </para> | |
4917 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
4918 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
4919 | </programlisting> | |
4920 | <variablelist> | |
4921 | <title></title> | |
4922 | <varlistentry> | |
4923 | <term>Precondition:</term> | |
4924 | <listitem> | |
4925 | <para> | |
4926 | The calling fiber doesn't own the mutex. | |
4927 | </para> | |
4928 | </listitem> | |
4929 | </varlistentry> | |
4930 | <varlistentry> | |
4931 | <term>Effects:</term> | |
4932 | <listitem> | |
4933 | <para> | |
4934 | Attempt to obtain ownership for the current fiber. Blocks until ownership | |
4935 | can be obtained, or the specified time is reached. If the specified | |
4936 | time has already passed, behaves as <link linkend="timed_mutex_try_lock"><code>timed_mutex::try_lock()</code></link>. | |
4937 | </para> | |
4938 | </listitem> | |
4939 | </varlistentry> | |
4940 | <varlistentry> | |
4941 | <term>Returns:</term> | |
4942 | <listitem> | |
4943 | <para> | |
4944 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
4945 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
4946 | otherwise. | |
4947 | </para> | |
4948 | </listitem> | |
4949 | </varlistentry> | |
4950 | <varlistentry> | |
4951 | <term>Throws:</term> | |
4952 | <listitem> | |
4953 | <para> | |
4954 | <code><phrase role="identifier">lock_error</phrase></code>, timeout-related | |
4955 | exceptions. | |
4956 | </para> | |
4957 | </listitem> | |
4958 | </varlistentry> | |
4959 | <varlistentry> | |
4960 | <term>Error Conditions:</term> | |
4961 | <listitem> | |
4962 | <para> | |
4963 | <emphasis role="bold">resource_deadlock_would_occur</emphasis>: if | |
4964 | <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
4965 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
4966 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
4967 | already owns the mutex. | |
4968 | </para> | |
4969 | </listitem> | |
4970 | </varlistentry> | |
4971 | </variablelist> | |
4972 | <para> | |
4973 | <bridgehead renderas="sect4" id="class_recursive_mutex_bridgehead"> | |
4974 | <phrase id="class_recursive_mutex"/> | |
4975 | <link linkend="class_recursive_mutex">Class | |
4976 | <code>recursive_mutex</code></link> | |
4977 | </bridgehead> | |
4978 | </para> | |
4979 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">recursive_mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
4980 | ||
4981 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
4982 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
4983 | ||
4984 | <phrase role="keyword">class</phrase> <phrase role="identifier">recursive_mutex</phrase> <phrase role="special">{</phrase> | |
4985 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
4986 | <phrase role="identifier">recursive_mutex</phrase><phrase role="special">();</phrase> | |
4987 | <phrase role="special">~</phrase><phrase role="identifier">recursive_mutex</phrase><phrase role="special">();</phrase> | |
4988 | ||
4989 | <phrase role="identifier">recursive_mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">recursive_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
4990 | <phrase role="identifier">recursive_mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">recursive_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
4991 | ||
4992 | <phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
4993 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
4994 | <phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
4995 | <phrase role="special">};</phrase> | |
4996 | ||
4997 | <phrase role="special">}}</phrase> | |
4998 | </programlisting> | |
4999 | <para> | |
5000 | <link linkend="class_recursive_mutex"><code>recursive_mutex</code></link> provides an exclusive-ownership recursive | |
5001 | mutex. At most one fiber can own the lock on a given instance of <link linkend="class_recursive_mutex"><code>recursive_mutex</code></link> at | |
5002 | any time. Multiple concurrent calls to <code><phrase role="identifier">lock</phrase><phrase | |
5003 | role="special">()</phrase></code>, <code><phrase role="identifier">try_lock</phrase><phrase | |
5004 | role="special">()</phrase></code> and <code><phrase role="identifier">unlock</phrase><phrase | |
5005 | role="special">()</phrase></code> shall be permitted. A fiber that already | |
5006 | has exclusive ownership of a given <link linkend="class_recursive_mutex"><code>recursive_mutex</code></link> instance | |
5007 | can call <code><phrase role="identifier">lock</phrase><phrase role="special">()</phrase></code> | |
5008 | or <code><phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase></code> | |
5009 | to acquire an additional level of ownership of the mutex. <code><phrase role="identifier">unlock</phrase><phrase | |
5010 | role="special">()</phrase></code> must be called once for each level of ownership | |
5011 | acquired by a single fiber before ownership can be acquired by another fiber. | |
5012 | </para> | |
5013 | <para> | |
5014 | <bridgehead renderas="sect4" id="recursive_mutex_lock_bridgehead"> | |
5015 | <phrase id="recursive_mutex_lock"/> | |
5016 | <link linkend="recursive_mutex_lock">Member | |
5017 | function <code>lock</code>()</link> | |
5018 | </bridgehead> | |
5019 | </para> | |
5020 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
5021 | </programlisting> | |
5022 | <variablelist> | |
5023 | <title></title> | |
5024 | <varlistentry> | |
5025 | <term>Effects:</term> | |
5026 | <listitem> | |
5027 | <para> | |
5028 | The current fiber blocks until ownership can be obtained. | |
5029 | </para> | |
5030 | </listitem> | |
5031 | </varlistentry> | |
5032 | <varlistentry> | |
5033 | <term>Throws:</term> | |
5034 | <listitem> | |
5035 | <para> | |
5036 | Nothing | |
5037 | </para> | |
5038 | </listitem> | |
5039 | </varlistentry> | |
5040 | </variablelist> | |
5041 | <para> | |
5042 | <bridgehead renderas="sect4" id="recursive_mutex_try_lock_bridgehead"> | |
5043 | <phrase id="recursive_mutex_try_lock"/> | |
5044 | <link linkend="recursive_mutex_try_lock">Member | |
5045 | function <code>try_lock</code>()</link> | |
5046 | </bridgehead> | |
5047 | </para> | |
5048 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
5049 | </programlisting> | |
5050 | <variablelist> | |
5051 | <title></title> | |
5052 | <varlistentry> | |
5053 | <term>Effects:</term> | |
5054 | <listitem> | |
5055 | <para> | |
5056 | Attempt to obtain ownership for the current fiber without blocking. | |
5057 | </para> | |
5058 | </listitem> | |
5059 | </varlistentry> | |
5060 | <varlistentry> | |
5061 | <term>Returns:</term> | |
5062 | <listitem> | |
5063 | <para> | |
5064 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
5065 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
5066 | otherwise. | |
5067 | </para> | |
5068 | </listitem> | |
5069 | </varlistentry> | |
5070 | <varlistentry> | |
5071 | <term>Throws:</term> | |
5072 | <listitem> | |
5073 | <para> | |
5074 | Nothing. | |
5075 | </para> | |
5076 | </listitem> | |
5077 | </varlistentry> | |
5078 | </variablelist> | |
5079 | <para> | |
5080 | <bridgehead renderas="sect4" id="recursive_mutex_unlock_bridgehead"> | |
5081 | <phrase id="recursive_mutex_unlock"/> | |
5082 | <link linkend="recursive_mutex_unlock">Member | |
5083 | function <code>unlock</code>()</link> | |
5084 | </bridgehead> | |
5085 | </para> | |
5086 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
5087 | </programlisting> | |
5088 | <variablelist> | |
5089 | <title></title> | |
5090 | <varlistentry> | |
5091 | <term>Effects:</term> | |
5092 | <listitem> | |
5093 | <para> | |
5094 | Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
5095 | by the current fiber. | |
5096 | </para> | |
5097 | </listitem> | |
5098 | </varlistentry> | |
5099 | <varlistentry> | |
5100 | <term>Throws:</term> | |
5101 | <listitem> | |
5102 | <para> | |
5103 | <code><phrase role="identifier">lock_error</phrase></code> | |
5104 | </para> | |
5105 | </listitem> | |
5106 | </varlistentry> | |
5107 | <varlistentry> | |
5108 | <term>Error Conditions:</term> | |
5109 | <listitem> | |
5110 | <para> | |
5111 | <emphasis role="bold">operation_not_permitted</emphasis>: if <code><phrase | |
5112 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
5113 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
5114 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
5115 | does not own the mutex. | |
5116 | </para> | |
5117 | </listitem> | |
5118 | </varlistentry> | |
5119 | </variablelist> | |
5120 | <para> | |
5121 | <bridgehead renderas="sect4" id="class_recursive_timed_mutex_bridgehead"> | |
5122 | <phrase id="class_recursive_timed_mutex"/> | |
5123 | <link linkend="class_recursive_timed_mutex">Class | |
5124 | <code>recursive_timed_mutex</code></link> | |
5125 | </bridgehead> | |
5126 | </para> | |
5127 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
5128 | ||
5129 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
5130 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
5131 | ||
5132 | <phrase role="keyword">class</phrase> <phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="special">{</phrase> | |
5133 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
5134 | <phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">();</phrase> | |
5135 | <phrase role="special">~</phrase><phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">();</phrase> | |
5136 | ||
5137 | <phrase role="identifier">recursive_timed_mutex</phrase><phrase role="special">(</phrase> <phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
5138 | <phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">recursive_timed_mutex</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
5139 | ||
5140 | <phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
5141 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
5142 | <phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
5143 | ||
5144 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
5145 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
5146 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
5147 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
5148 | <phrase role="special">};</phrase> | |
5149 | ||
5150 | <phrase role="special">}}</phrase> | |
5151 | </programlisting> | |
5152 | <para> | |
5153 | <link linkend="class_recursive_timed_mutex"><code>recursive_timed_mutex</code></link> provides an exclusive-ownership | |
5154 | recursive mutex. At most one fiber can own the lock on a given instance of | |
5155 | <link linkend="class_recursive_timed_mutex"><code>recursive_timed_mutex</code></link> at any time. Multiple concurrent | |
5156 | calls to <code><phrase role="identifier">lock</phrase><phrase role="special">()</phrase></code>, | |
5157 | <code><phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase></code>, | |
5158 | <code><phrase role="identifier">try_lock_for</phrase><phrase role="special">()</phrase></code>, | |
5159 | <code><phrase role="identifier">try_lock_until</phrase><phrase role="special">()</phrase></code> | |
5160 | and <code><phrase role="identifier">unlock</phrase><phrase role="special">()</phrase></code> | |
5161 | shall be permitted. A fiber that already has exclusive ownership of a given | |
5162 | <link linkend="class_recursive_timed_mutex"><code>recursive_timed_mutex</code></link> instance can call <code><phrase | |
5163 | role="identifier">lock</phrase><phrase role="special">()</phrase></code>, | |
5164 | <code><phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase></code>, | |
5165 | <code><phrase role="identifier">try_lock_for</phrase><phrase role="special">()</phrase></code> | |
5166 | or <code><phrase role="identifier">try_lock_until</phrase><phrase role="special">()</phrase></code> | |
5167 | to acquire an additional level of ownership of the mutex. <code><phrase role="identifier">unlock</phrase><phrase | |
5168 | role="special">()</phrase></code> must be called once for each level of ownership | |
5169 | acquired by a single fiber before ownership can be acquired by another fiber. | |
5170 | </para> | |
5171 | <para> | |
5172 | <bridgehead renderas="sect4" id="recursive_timed_mutex_lock_bridgehead"> | |
5173 | <phrase id="recursive_timed_mutex_lock"/> | |
5174 | <link linkend="recursive_timed_mutex_lock">Member | |
5175 | function <code>lock</code>()</link> | |
5176 | </bridgehead> | |
5177 | </para> | |
5178 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">lock</phrase><phrase role="special">();</phrase> | |
5179 | </programlisting> | |
5180 | <variablelist> | |
5181 | <title></title> | |
5182 | <varlistentry> | |
5183 | <term>Effects:</term> | |
5184 | <listitem> | |
5185 | <para> | |
5186 | The current fiber blocks until ownership can be obtained. | |
5187 | </para> | |
5188 | </listitem> | |
5189 | </varlistentry> | |
5190 | <varlistentry> | |
5191 | <term>Throws:</term> | |
5192 | <listitem> | |
5193 | <para> | |
5194 | Nothing | |
5195 | </para> | |
5196 | </listitem> | |
5197 | </varlistentry> | |
5198 | </variablelist> | |
5199 | <para> | |
5200 | <bridgehead renderas="sect4" id="recursive_timed_mutex_try_lock_bridgehead"> | |
5201 | <phrase id="recursive_timed_mutex_try_lock"/> | |
5202 | <link linkend="recursive_timed_mutex_try_lock">Member | |
5203 | function <code>try_lock</code>()</link> | |
5204 | </bridgehead> | |
5205 | </para> | |
5206 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
5207 | </programlisting> | |
5208 | <variablelist> | |
5209 | <title></title> | |
5210 | <varlistentry> | |
5211 | <term>Effects:</term> | |
5212 | <listitem> | |
5213 | <para> | |
5214 | Attempt to obtain ownership for the current fiber without blocking. | |
5215 | </para> | |
5216 | </listitem> | |
5217 | </varlistentry> | |
5218 | <varlistentry> | |
5219 | <term>Returns:</term> | |
5220 | <listitem> | |
5221 | <para> | |
5222 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
5223 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
5224 | otherwise. | |
5225 | </para> | |
5226 | </listitem> | |
5227 | </varlistentry> | |
5228 | <varlistentry> | |
5229 | <term>Throws:</term> | |
5230 | <listitem> | |
5231 | <para> | |
5232 | Nothing. | |
5233 | </para> | |
5234 | </listitem> | |
5235 | </varlistentry> | |
5236 | </variablelist> | |
5237 | <para> | |
5238 | <bridgehead renderas="sect4" id="recursive_timed_mutex_unlock_bridgehead"> | |
5239 | <phrase id="recursive_timed_mutex_unlock"/> | |
5240 | <link linkend="recursive_timed_mutex_unlock">Member | |
5241 | function <code>unlock</code>()</link> | |
5242 | </bridgehead> | |
5243 | </para> | |
5244 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
5245 | </programlisting> | |
5246 | <variablelist> | |
5247 | <title></title> | |
5248 | <varlistentry> | |
5249 | <term>Effects:</term> | |
5250 | <listitem> | |
5251 | <para> | |
5252 | Releases a lock on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
5253 | by the current fiber. | |
5254 | </para> | |
5255 | </listitem> | |
5256 | </varlistentry> | |
5257 | <varlistentry> | |
5258 | <term>Throws:</term> | |
5259 | <listitem> | |
5260 | <para> | |
5261 | <code><phrase role="identifier">lock_error</phrase></code> | |
5262 | </para> | |
5263 | </listitem> | |
5264 | </varlistentry> | |
5265 | <varlistentry> | |
5266 | <term>Error Conditions:</term> | |
5267 | <listitem> | |
5268 | <para> | |
5269 | <emphasis role="bold">operation_not_permitted</emphasis>: if <code><phrase | |
5270 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
5271 | role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase | |
5272 | role="identifier">get_id</phrase><phrase role="special">()</phrase></code> | |
5273 | does not own the mutex. | |
5274 | </para> | |
5275 | </listitem> | |
5276 | </varlistentry> | |
5277 | </variablelist> | |
5278 | <para> | |
5279 | <bridgehead renderas="sect4" id="recursive_timed_mutex_try_lock_until_bridgehead"> | |
5280 | <phrase id="recursive_timed_mutex_try_lock_until"/> | |
5281 | <link linkend="recursive_timed_mutex_try_lock_until">Templated | |
5282 | member function <code>try_lock_until</code>()</link> | |
5283 | </bridgehead> | |
5284 | </para> | |
5285 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
5286 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
5287 | </programlisting> | |
5288 | <variablelist> | |
5289 | <title></title> | |
5290 | <varlistentry> | |
5291 | <term>Effects:</term> | |
5292 | <listitem> | |
5293 | <para> | |
5294 | Attempt to obtain ownership for the current fiber. Blocks until ownership | |
5295 | can be obtained, or the specified time is reached. If the specified | |
5296 | time has already passed, behaves as <link linkend="recursive_timed_mutex_try_lock"><code>recursive_timed_mutex::try_lock()</code></link>. | |
5297 | </para> | |
5298 | </listitem> | |
5299 | </varlistentry> | |
5300 | <varlistentry> | |
5301 | <term>Returns:</term> | |
5302 | <listitem> | |
5303 | <para> | |
5304 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
5305 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
5306 | otherwise. | |
5307 | </para> | |
5308 | </listitem> | |
5309 | </varlistentry> | |
5310 | <varlistentry> | |
5311 | <term>Throws:</term> | |
5312 | <listitem> | |
5313 | <para> | |
5314 | Timeout-related exceptions. | |
5315 | </para> | |
5316 | </listitem> | |
5317 | </varlistentry> | |
5318 | </variablelist> | |
5319 | <para> | |
5320 | <bridgehead renderas="sect4" id="recursive_timed_mutex_try_lock_for_bridgehead"> | |
5321 | <phrase id="recursive_timed_mutex_try_lock_for"/> | |
5322 | <link linkend="recursive_timed_mutex_try_lock_for">Templated | |
5323 | member function <code>try_lock_for</code>()</link> | |
5324 | </bridgehead> | |
5325 | </para> | |
5326 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
5327 | <phrase role="keyword">bool</phrase> <phrase role="identifier">try_lock_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
5328 | </programlisting> | |
5329 | <variablelist> | |
5330 | <title></title> | |
5331 | <varlistentry> | |
5332 | <term>Effects:</term> | |
5333 | <listitem> | |
5334 | <para> | |
5335 | Attempt to obtain ownership for the current fiber. Blocks until ownership | |
5336 | can be obtained, or the specified time is reached. If the specified | |
5337 | time has already passed, behaves as <link linkend="recursive_timed_mutex_try_lock"><code>recursive_timed_mutex::try_lock()</code></link>. | |
5338 | </para> | |
5339 | </listitem> | |
5340 | </varlistentry> | |
5341 | <varlistentry> | |
5342 | <term>Returns:</term> | |
5343 | <listitem> | |
5344 | <para> | |
5345 | <code><phrase role="keyword">true</phrase></code> if ownership was | |
5346 | obtained for the current fiber, <code><phrase role="keyword">false</phrase></code> | |
5347 | otherwise. | |
5348 | </para> | |
5349 | </listitem> | |
5350 | </varlistentry> | |
5351 | <varlistentry> | |
5352 | <term>Throws:</term> | |
5353 | <listitem> | |
5354 | <para> | |
5355 | Timeout-related exceptions. | |
5356 | </para> | |
5357 | </listitem> | |
5358 | </varlistentry> | |
5359 | </variablelist> | |
5360 | </section> | |
5361 | <section id="fiber.synchronization.conditions"> | |
5362 | <title><link linkend="fiber.synchronization.conditions">Condition Variables</link></title> | |
5363 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h0"> | |
5364 | <phrase id="fiber.synchronization.conditions.synopsis"/><link linkend="fiber.synchronization.conditions.synopsis">Synopsis</link> | |
5365 | </bridgehead> | |
5366 | <programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">;</phrase> <phrase role="special">{</phrase> | |
5367 | <phrase role="identifier">no_timeout</phrase><phrase role="special">,</phrase> | |
5368 | <phrase role="identifier">timeout</phrase> | |
5369 | <phrase role="special">};</phrase> | |
5370 | ||
5371 | <phrase role="keyword">class</phrase> <phrase role="identifier">condition_variable</phrase><phrase role="special">;</phrase> | |
5372 | <phrase role="keyword">class</phrase> <phrase role="identifier">condition_variable_any</phrase><phrase role="special">;</phrase> | |
5373 | </programlisting> | |
5374 | <para> | |
5375 | The class <link linkend="class_condition_variable"><code>condition_variable</code></link> provides a mechanism | |
5376 | for a fiber to wait for notification from another fiber. When the fiber awakens | |
5377 | from the wait, then it checks to see if the appropriate condition is now | |
5378 | true, and continues if so. If the condition is not true, then the fiber calls | |
5379 | <code><phrase role="identifier">wait</phrase></code> again to resume waiting. | |
5380 | In the simplest case, this condition is just a boolean variable: | |
5381 | </para> | |
5382 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">condition_variable</phrase> <phrase role="identifier">cond</phrase><phrase role="special">;</phrase> | |
5383 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="identifier">mtx</phrase><phrase role="special">;</phrase> | |
5384 | <phrase role="keyword">bool</phrase> <phrase role="identifier">data_ready</phrase> <phrase role="special">=</phrase> <phrase role="keyword">false</phrase><phrase role="special">;</phrase> | |
5385 | ||
5386 | <phrase role="keyword">void</phrase> <phrase role="identifier">process_data</phrase><phrase role="special">();</phrase> | |
5387 | ||
5388 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_for_data_to_process</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
5389 | <phrase role="special">{</phrase> | |
5390 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx</phrase><phrase role="special">);</phrase> | |
5391 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">data_ready</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
5392 | <phrase role="identifier">cond</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase> | |
5393 | <phrase role="special">}</phrase> | |
5394 | <phrase role="special">}</phrase> <phrase role="comment">// release lk</phrase> | |
5395 | <phrase role="identifier">process_data</phrase><phrase role="special">();</phrase> | |
5396 | <phrase role="special">}</phrase> | |
5397 | </programlisting> | |
5398 | <para> | |
5399 | Notice that the <code><phrase role="identifier">lk</phrase></code> is passed | |
5400 | to <link linkend="condition_variable_wait"><code>condition_variable::wait()</code></link>: <code><phrase role="identifier">wait</phrase><phrase | |
5401 | role="special">()</phrase></code> will atomically add the fiber to the set | |
5402 | of fibers waiting on the condition variable, and unlock the <link linkend="class_mutex"><code>mutex</code></link>. | |
5403 | When the fiber is awakened, the <code><phrase role="identifier">mutex</phrase></code> | |
5404 | will be locked again before the call to <code><phrase role="identifier">wait</phrase><phrase | |
5405 | role="special">()</phrase></code> returns. This allows other fibers to acquire | |
5406 | the <code><phrase role="identifier">mutex</phrase></code> in order to update | |
5407 | the shared data, and ensures that the data associated with the condition | |
5408 | is correctly synchronized. | |
5409 | </para> | |
5410 | <para> | |
5411 | <code><phrase role="identifier">wait_for_data_to_process</phrase><phrase | |
5412 | role="special">()</phrase></code> could equivalently be written: | |
5413 | </para> | |
5414 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">wait_for_data_to_process</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
5415 | <phrase role="special">{</phrase> | |
5416 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx</phrase><phrase role="special">);</phrase> | |
5417 | <phrase role="comment">// make condition_variable::wait() perform the loop</phrase> | |
5418 | <phrase role="identifier">cond</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">data_ready</phrase><phrase role="special">;</phrase> <phrase role="special">});</phrase> | |
5419 | <phrase role="special">}</phrase> <phrase role="comment">// release lk</phrase> | |
5420 | <phrase role="identifier">process_data</phrase><phrase role="special">();</phrase> | |
5421 | <phrase role="special">}</phrase> | |
5422 | </programlisting> | |
5423 | <para> | |
5424 | In the meantime, another fiber sets <code><phrase role="identifier">data_ready</phrase></code> | |
5425 | to <code><phrase role="keyword">true</phrase></code>, and then calls either | |
5426 | <link linkend="condition_variable_notify_one"><code>condition_variable::notify_one()</code></link> or <link linkend="condition_variable_notify_all"><code>condition_variable::notify_all()</code></link> on | |
5427 | the <link linkend="class_condition_variable"><code>condition_variable</code></link> <code><phrase role="identifier">cond</phrase></code> | |
5428 | to wake one waiting fiber or all the waiting fibers respectively. | |
5429 | </para> | |
5430 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">retrieve_data</phrase><phrase role="special">();</phrase> | |
5431 | <phrase role="keyword">void</phrase> <phrase role="identifier">prepare_data</phrase><phrase role="special">();</phrase> | |
5432 | ||
5433 | <phrase role="keyword">void</phrase> <phrase role="identifier">prepare_data_for_processing</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
5434 | <phrase role="identifier">retrieve_data</phrase><phrase role="special">();</phrase> | |
5435 | <phrase role="identifier">prepare_data</phrase><phrase role="special">();</phrase> | |
5436 | <phrase role="special">{</phrase> | |
5437 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx</phrase><phrase role="special">);</phrase> | |
5438 | <phrase role="identifier">data_ready</phrase> <phrase role="special">=</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
5439 | <phrase role="special">}</phrase> | |
5440 | <phrase role="identifier">cond</phrase><phrase role="special">.</phrase><phrase role="identifier">notify_one</phrase><phrase role="special">();</phrase> | |
5441 | <phrase role="special">}</phrase> | |
5442 | </programlisting> | |
5443 | <para> | |
5444 | Note that the same <link linkend="class_mutex"><code>mutex</code></link> is locked before the shared data is updated, | |
5445 | but that the <code><phrase role="identifier">mutex</phrase></code> does not | |
5446 | have to be locked across the call to <link linkend="condition_variable_notify_one"><code>condition_variable::notify_one()</code></link>. | |
5447 | </para> | |
5448 | <para> | |
5449 | Locking is important because the synchronization objects provided by <emphasis | |
5450 | role="bold">Boost.Fiber</emphasis> can be used to synchronize fibers running | |
5451 | on different threads. | |
5452 | </para> | |
5453 | <para> | |
5454 | <emphasis role="bold">Boost.Fiber</emphasis> provides both <link linkend="class_condition_variable"><code>condition_variable</code></link> and | |
5455 | <link linkend="class_condition_variable_any"><code>condition_variable_any</code></link>. <code><phrase role="identifier">boost</phrase><phrase | |
5456 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
5457 | role="special">::</phrase><phrase role="identifier">condition_variable</phrase></code> | |
5458 | can only wait on <ulink url="http://en.cppreference.com/w/cpp/thread/unique_lock"><code><phrase | |
5459 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase></code></ulink><code><phrase | |
5460 | role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase | |
5461 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
5462 | role="special">::</phrase></code><link linkend="class_mutex"><code>mutex</code></link><code> <phrase role="special">></phrase></code> | |
5463 | while <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
5464 | role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase | |
5465 | role="identifier">condition_variable_any</phrase></code> can wait on user-defined | |
5466 | lock types. | |
5467 | </para> | |
5468 | <anchor id="condition_variable_spurious_wakeups"/> | |
5469 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h1"> | |
5470 | <phrase id="fiber.synchronization.conditions.no_spurious_wakeups"/><link | |
5471 | linkend="fiber.synchronization.conditions.no_spurious_wakeups">No Spurious | |
5472 | Wakeups</link> | |
5473 | </bridgehead> | |
5474 | <para> | |
5475 | Neither <link linkend="class_condition_variable"><code>condition_variable</code></link> nor <link linkend="class_condition_variable_any"><code>condition_variable_any</code></link> are | |
5476 | subject to spurious wakeup: <link linkend="condition_variable_wait"><code>condition_variable::wait()</code></link> can | |
5477 | only wake up when <link linkend="condition_variable_notify_one"><code>condition_variable::notify_one()</code></link> or | |
5478 | <link linkend="condition_variable_notify_all"><code>condition_variable::notify_all()</code></link> is called. Even | |
5479 | so, it is prudent to use one of the <code><phrase role="identifier">wait</phrase><phrase | |
5480 | role="special">(</phrase> <phrase role="identifier">lock</phrase><phrase | |
5481 | role="special">,</phrase> <phrase role="identifier">predicate</phrase> <phrase | |
5482 | role="special">)</phrase></code> overloads. | |
5483 | </para> | |
5484 | <para> | |
5485 | Consider a set of consumer fibers processing items from a <ulink url="http://en.cppreference.com/w/cpp/container/queue"><code><phrase | |
5486 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">queue</phrase></code></ulink>. | |
5487 | The queue is continually populated by a set of producer fibers. | |
5488 | </para> | |
5489 | <para> | |
5490 | The consumer fibers might reasonably wait on a <code><phrase role="identifier">condition_variable</phrase></code> | |
5491 | as long as the queue remains <ulink url="http://en.cppreference.com/w/cpp/container/queue/empty"><code><phrase | |
5492 | role="identifier">empty</phrase><phrase role="special">()</phrase></code></ulink>. | |
5493 | </para> | |
5494 | <para> | |
5495 | Because producer fibers might <ulink url="http://en.cppreference.com/w/cpp/container/queue/push"><code><phrase | |
5496 | role="identifier">push</phrase><phrase role="special">()</phrase></code></ulink> | |
5497 | items to the queue in bursts, they call <link linkend="condition_variable_notify_all"><code>condition_variable::notify_all()</code></link> rather | |
5498 | than <link linkend="condition_variable_notify_one"><code>condition_variable::notify_one()</code></link>. | |
5499 | </para> | |
5500 | <para> | |
5501 | But a given consumer fiber might well wake up from <link linkend="condition_variable_wait"><code>condition_variable::wait()</code></link> and | |
5502 | find the queue <code><phrase role="identifier">empty</phrase><phrase role="special">()</phrase></code>, | |
5503 | because other consumer fibers might already have processed all pending items. | |
5504 | </para> | |
5505 | <para> | |
5506 | (See also <link linkend="spurious_wakeup">spurious wakeup</link>.) | |
5507 | </para> | |
5508 | <anchor id="class_cv_status"/> | |
5509 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h2"> | |
5510 | <phrase id="fiber.synchronization.conditions.enumeration__code__phrase_role__identifier__cv_status__phrase___code_"/><link | |
5511 | linkend="fiber.synchronization.conditions.enumeration__code__phrase_role__identifier__cv_status__phrase___code_">Enumeration | |
5512 | <code><phrase role="identifier">cv_status</phrase></code></link> | |
5513 | </bridgehead> | |
5514 | <para> | |
5515 | A timed wait operation might return because of timeout or not. | |
5516 | </para> | |
5517 | <programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">cv_status</phrase> <phrase role="special">{</phrase> | |
5518 | <phrase role="identifier">no_timeout</phrase><phrase role="special">,</phrase> | |
5519 | <phrase role="identifier">timeout</phrase> | |
5520 | <phrase role="special">};</phrase> | |
5521 | </programlisting> | |
5522 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h3"> | |
5523 | <phrase id="fiber.synchronization.conditions._code__phrase_role__identifier__no_timeout__phrase___code_"/><link | |
5524 | linkend="fiber.synchronization.conditions._code__phrase_role__identifier__no_timeout__phrase___code_"><code><phrase | |
5525 | role="identifier">no_timeout</phrase></code></link> | |
5526 | </bridgehead> | |
5527 | <variablelist> | |
5528 | <title></title> | |
5529 | <varlistentry> | |
5530 | <term>Effects:</term> | |
5531 | <listitem> | |
5532 | <para> | |
5533 | The condition variable was awakened with <code><phrase role="identifier">notify_one</phrase></code> | |
5534 | or <code><phrase role="identifier">notify_all</phrase></code>. | |
5535 | </para> | |
5536 | </listitem> | |
5537 | </varlistentry> | |
5538 | </variablelist> | |
5539 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h4"> | |
5540 | <phrase id="fiber.synchronization.conditions._code__phrase_role__identifier__timeout__phrase___code_"/><link | |
5541 | linkend="fiber.synchronization.conditions._code__phrase_role__identifier__timeout__phrase___code_"><code><phrase | |
5542 | role="identifier">timeout</phrase></code></link> | |
5543 | </bridgehead> | |
5544 | <variablelist> | |
5545 | <title></title> | |
5546 | <varlistentry> | |
5547 | <term>Effects:</term> | |
5548 | <listitem> | |
5549 | <para> | |
5550 | The condition variable was awakened by timeout. | |
5551 | </para> | |
5552 | </listitem> | |
5553 | </varlistentry> | |
5554 | </variablelist> | |
5555 | <para> | |
5556 | <bridgehead renderas="sect4" id="class_condition_variable_any_bridgehead"> | |
5557 | <phrase id="class_condition_variable_any"/> | |
5558 | <link linkend="class_condition_variable_any">Class | |
5559 | <code>condition_variable_any</code></link> | |
5560 | </bridgehead> | |
5561 | </para> | |
5562 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">condition_variable</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
5563 | ||
5564 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
5565 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
5566 | ||
5567 | <phrase role="keyword">class</phrase> condition_variable_any <phrase role="special">{</phrase> | |
5568 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
5569 | condition_variable_any<phrase role="special">();</phrase> | |
5570 | <phrase role="special">~</phrase>condition_variable_any<phrase role="special">();</phrase> | |
5571 | ||
5572 | condition_variable_any<phrase role="special">(</phrase> condition_variable_any <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
5573 | condition_variable_any <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> condition_variable_any <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
5574 | ||
5575 | <phrase role="keyword">void</phrase> <phrase role="identifier">notify_one</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
5576 | <phrase role="keyword">void</phrase> <phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
5577 | ||
5578 | template< typename LockType > | |
5579 | void <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&);</phrase> | |
5580 | ||
5581 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
5582 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&,</phrase> <phrase role="identifier">Pred</phrase><phrase role="special">);</phrase> | |
5583 | ||
5584 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
5585 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&,</phrase> | |
5586 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> | |
5587 | ||
5588 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
5589 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&,</phrase> | |
5590 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&,</phrase> | |
5591 | <phrase role="identifier">Pred</phrase><phrase role="special">);</phrase> | |
5592 | ||
5593 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
5594 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&,</phrase> | |
5595 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> | |
5596 | ||
5597 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
5598 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&,</phrase> | |
5599 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&,</phrase> | |
5600 | <phrase role="identifier">Pred</phrase><phrase role="special">);</phrase> | |
5601 | <phrase role="special">};</phrase> | |
5602 | ||
5603 | <phrase role="special">}}</phrase> | |
5604 | </programlisting> | |
5605 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h5"> | |
5606 | <phrase id="fiber.synchronization.conditions.constructor"/><link linkend="fiber.synchronization.conditions.constructor">Constructor</link> | |
5607 | </bridgehead> | |
5608 | <programlisting>condition_variable_any<phrase role="special">()</phrase> | |
5609 | </programlisting> | |
5610 | <variablelist> | |
5611 | <title></title> | |
5612 | <varlistentry> | |
5613 | <term>Effects:</term> | |
5614 | <listitem> | |
5615 | <para> | |
5616 | Creates the object. | |
5617 | </para> | |
5618 | </listitem> | |
5619 | </varlistentry> | |
5620 | <varlistentry> | |
5621 | <term>Throws:</term> | |
5622 | <listitem> | |
5623 | <para> | |
5624 | Nothing. | |
5625 | </para> | |
5626 | </listitem> | |
5627 | </varlistentry> | |
5628 | </variablelist> | |
5629 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h6"> | |
5630 | <phrase id="fiber.synchronization.conditions.destructor"/><link linkend="fiber.synchronization.conditions.destructor">Destructor</link> | |
5631 | </bridgehead> | |
5632 | <programlisting><phrase role="special">~</phrase>condition_variable_any<phrase role="special">()</phrase> | |
5633 | </programlisting> | |
5634 | <variablelist> | |
5635 | <title></title> | |
5636 | <varlistentry> | |
5637 | <term>Precondition:</term> | |
5638 | <listitem> | |
5639 | <para> | |
5640 | All fibers waiting on <code><phrase role="special">*</phrase><phrase | |
5641 | role="keyword">this</phrase></code> have been notified by a call to | |
5642 | <code><phrase role="identifier">notify_one</phrase></code> or <code><phrase | |
5643 | role="identifier">notify_all</phrase></code> (though the respective | |
5644 | calls to <code><phrase role="identifier">wait</phrase></code>, <code><phrase | |
5645 | role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code> | |
5646 | need not have returned). | |
5647 | </para> | |
5648 | </listitem> | |
5649 | </varlistentry> | |
5650 | <varlistentry> | |
5651 | <term>Effects:</term> | |
5652 | <listitem> | |
5653 | <para> | |
5654 | Destroys the object. | |
5655 | </para> | |
5656 | </listitem> | |
5657 | </varlistentry> | |
5658 | </variablelist> | |
5659 | <para> | |
5660 | <bridgehead renderas="sect4" id="condition_variable_any_notify_one_bridgehead"> | |
5661 | <phrase id="condition_variable_any_notify_one"/> | |
5662 | <link linkend="condition_variable_any_notify_one">Member | |
5663 | function <code>notify_one</code>()</link> | |
5664 | </bridgehead> | |
5665 | </para> | |
5666 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify_one</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
5667 | </programlisting> | |
5668 | <variablelist> | |
5669 | <title></title> | |
5670 | <varlistentry> | |
5671 | <term>Effects:</term> | |
5672 | <listitem> | |
5673 | <para> | |
5674 | If any fibers are currently <link linkend="blocking"><emphasis>blocked</emphasis></link> | |
5675 | waiting on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
5676 | in a call to <code><phrase role="identifier">wait</phrase></code>, | |
5677 | <code><phrase role="identifier">wait_for</phrase></code> or <code><phrase | |
5678 | role="identifier">wait_until</phrase></code>, unblocks one of those | |
5679 | fibers. | |
5680 | </para> | |
5681 | </listitem> | |
5682 | </varlistentry> | |
5683 | <varlistentry> | |
5684 | <term>Throws:</term> | |
5685 | <listitem> | |
5686 | <para> | |
5687 | Nothing. | |
5688 | </para> | |
5689 | </listitem> | |
5690 | </varlistentry> | |
5691 | <varlistentry> | |
5692 | <term>Note:</term> | |
5693 | <listitem> | |
5694 | <para> | |
5695 | It is arbitrary which waiting fiber is resumed. | |
5696 | </para> | |
5697 | </listitem> | |
5698 | </varlistentry> | |
5699 | </variablelist> | |
5700 | <para> | |
5701 | <bridgehead renderas="sect4" id="condition_variable_any_notify_all_bridgehead"> | |
5702 | <phrase id="condition_variable_any_notify_all"/> | |
5703 | <link linkend="condition_variable_any_notify_all">Member | |
5704 | function <code>notify_all</code>()</link> | |
5705 | </bridgehead> | |
5706 | </para> | |
5707 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
5708 | </programlisting> | |
5709 | <variablelist> | |
5710 | <title></title> | |
5711 | <varlistentry> | |
5712 | <term>Effects:</term> | |
5713 | <listitem> | |
5714 | <para> | |
5715 | If any fibers are currently <link linkend="blocking"><emphasis>blocked</emphasis></link> | |
5716 | waiting on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
5717 | in a call to <code><phrase role="identifier">wait</phrase></code>, | |
5718 | <code><phrase role="identifier">wait_for</phrase></code> or <code><phrase | |
5719 | role="identifier">wait_until</phrase></code>, unblocks all of those | |
5720 | fibers. | |
5721 | </para> | |
5722 | </listitem> | |
5723 | </varlistentry> | |
5724 | <varlistentry> | |
5725 | <term>Throws:</term> | |
5726 | <listitem> | |
5727 | <para> | |
5728 | Nothing. | |
5729 | </para> | |
5730 | </listitem> | |
5731 | </varlistentry> | |
5732 | <varlistentry> | |
5733 | <term>Note:</term> | |
5734 | <listitem> | |
5735 | <para> | |
5736 | This is why a waiting fiber must <emphasis>also</emphasis> check for | |
5737 | the desired program state using a mechanism external to the <code>condition_variable_any</code>, | |
5738 | and retry the wait until that state is reached. A fiber waiting on | |
5739 | a <code>condition_variable_any</code> might well wake up a number of times before | |
5740 | the desired state is reached. | |
5741 | </para> | |
5742 | </listitem> | |
5743 | </varlistentry> | |
5744 | </variablelist> | |
5745 | <para> | |
5746 | <bridgehead renderas="sect4" id="condition_variable_any_wait_bridgehead"> | |
5747 | <phrase id="condition_variable_any_wait"/> | |
5748 | <link linkend="condition_variable_any_wait">Templated | |
5749 | member function <code>wait</code>()</link> | |
5750 | </bridgehead> | |
5751 | </para> | |
5752 | <programlisting>template< typename LockType > | |
5753 | void <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase> | |
5754 | ||
5755 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
5756 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase> | |
5757 | </programlisting> | |
5758 | <variablelist> | |
5759 | <title></title> | |
5760 | <varlistentry> | |
5761 | <term>Precondition:</term> | |
5762 | <listitem> | |
5763 | <para> | |
5764 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
5765 | current fiber, and either no other fiber is currently waiting on <code><phrase | |
5766 | role="special">*</phrase><phrase role="keyword">this</phrase></code>, | |
5767 | or the execution of the <ulink url="http://en.cppreference.com/w/cpp/thread/unique_lock/mutex"><code><phrase | |
5768 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code></ulink> | |
5769 | member function on the <code><phrase role="identifier">lk</phrase></code> | |
5770 | objects supplied in the calls to <code><phrase role="identifier">wait</phrase></code> | |
5771 | in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase | |
5772 | role="keyword">this</phrase></code> would return the same value as | |
5773 | <code><phrase role="identifier">lk</phrase><phrase role="special">-></phrase><phrase | |
5774 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code> | |
5775 | for this call to <code><phrase role="identifier">wait</phrase></code>. | |
5776 | </para> | |
5777 | </listitem> | |
5778 | </varlistentry> | |
5779 | <varlistentry> | |
5780 | <term>Effects:</term> | |
5781 | <listitem> | |
5782 | <para> | |
5783 | Atomically call <code><phrase role="identifier">lk</phrase><phrase | |
5784 | role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase | |
5785 | role="special">()</phrase></code> and blocks the current fiber. The | |
5786 | fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase | |
5787 | role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase | |
5788 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
5789 | role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase | |
5790 | role="special">()</phrase></code>. When the fiber is unblocked (for | |
5791 | whatever reason), the lock is reacquired by invoking <code><phrase | |
5792 | role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
5793 | role="identifier">lock</phrase><phrase role="special">()</phrase></code> | |
5794 | before the call to <code><phrase role="identifier">wait</phrase></code> | |
5795 | returns. The lock is also reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase | |
5796 | role="special">.</phrase><phrase role="identifier">lock</phrase><phrase | |
5797 | role="special">()</phrase></code> if the function exits with an exception. | |
5798 | The member function accepting <code><phrase role="identifier">pred</phrase></code> | |
5799 | is shorthand for: | |
5800 | <programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
5801 | <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase> | |
5802 | <phrase role="special">}</phrase> | |
5803 | </programlisting> | |
5804 | </para> | |
5805 | </listitem> | |
5806 | </varlistentry> | |
5807 | <varlistentry> | |
5808 | <term>Postcondition:</term> | |
5809 | <listitem> | |
5810 | <para> | |
5811 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
5812 | current fiber. | |
5813 | </para> | |
5814 | </listitem> | |
5815 | </varlistentry> | |
5816 | <varlistentry> | |
5817 | <term>Throws:</term> | |
5818 | <listitem> | |
5819 | <para> | |
5820 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
5821 | occurs. | |
5822 | </para> | |
5823 | </listitem> | |
5824 | </varlistentry> | |
5825 | <varlistentry> | |
5826 | <term>Note:</term> | |
5827 | <listitem> | |
5828 | <para> | |
5829 | The Precondition is a bit dense. It merely states that all the fibers | |
5830 | concurrently calling <code><phrase role="identifier">wait</phrase></code> | |
5831 | on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
5832 | must wait on <code><phrase role="identifier">lk</phrase></code> objects | |
5833 | governing the <emphasis>same</emphasis> <link linkend="class_mutex"><code>mutex</code></link>. Three distinct | |
5834 | objects are involved in any <code>condition_variable_any::wait()</code> call: the | |
5835 | <code>condition_variable_any</code> itself, the <code><phrase role="identifier">mutex</phrase></code> | |
5836 | coordinating access between fibers and a local lock object (e.g. <ulink | |
5837 | url="http://en.cppreference.com/w/cpp/thread/unique_lock"><code><phrase | |
5838 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
5839 | role="identifier">unique_lock</phrase></code></ulink>). In general, | |
5840 | you can partition the lifespan of a given <code>condition_variable_any</code> instance | |
5841 | into periods with one or more fibers waiting on it, separated by periods | |
5842 | when no fibers are waiting on it. When more than one fiber is waiting | |
5843 | on that <code>condition_variable_any</code>, all must pass lock objects referencing | |
5844 | the <emphasis>same</emphasis> <code><phrase role="identifier">mutex</phrase></code> | |
5845 | instance. | |
5846 | </para> | |
5847 | </listitem> | |
5848 | </varlistentry> | |
5849 | </variablelist> | |
5850 | <para> | |
5851 | <bridgehead renderas="sect4" id="condition_variable_any_wait_until_bridgehead"> | |
5852 | <phrase id="condition_variable_any_wait_until"/> | |
5853 | <link linkend="condition_variable_any_wait_until">Templated | |
5854 | member function <code>wait_until</code>()</link> | |
5855 | </bridgehead> | |
5856 | </para> | |
5857 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
5858 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
5859 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">);</phrase> | |
5860 | ||
5861 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
5862 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
5863 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">,</phrase> | |
5864 | <phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase> | |
5865 | </programlisting> | |
5866 | <variablelist> | |
5867 | <title></title> | |
5868 | <varlistentry> | |
5869 | <term>Precondition:</term> | |
5870 | <listitem> | |
5871 | <para> | |
5872 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
5873 | current fiber, and either no other fiber is currently waiting on <code><phrase | |
5874 | role="special">*</phrase><phrase role="keyword">this</phrase></code>, | |
5875 | or the execution of the <code><phrase role="identifier">mutex</phrase><phrase | |
5876 | role="special">()</phrase></code> member function on the <code><phrase | |
5877 | role="identifier">lk</phrase></code> objects supplied in the calls | |
5878 | to <code><phrase role="identifier">wait</phrase></code>, <code><phrase | |
5879 | role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code> | |
5880 | in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase | |
5881 | role="keyword">this</phrase></code> would return the same value as | |
5882 | <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
5883 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code> | |
5884 | for this call to <code><phrase role="identifier">wait_until</phrase></code>. | |
5885 | </para> | |
5886 | </listitem> | |
5887 | </varlistentry> | |
5888 | <varlistentry> | |
5889 | <term>Effects:</term> | |
5890 | <listitem> | |
5891 | <para> | |
5892 | Atomically call <code><phrase role="identifier">lk</phrase><phrase | |
5893 | role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase | |
5894 | role="special">()</phrase></code> and blocks the current fiber. The | |
5895 | fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase | |
5896 | role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase | |
5897 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
5898 | role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase | |
5899 | role="special">()</phrase></code>, when the system time would be equal | |
5900 | to or later than the specified <code><phrase role="identifier">abs_time</phrase></code>. | |
5901 | When the fiber is unblocked (for whatever reason), the lock is reacquired | |
5902 | by invoking <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
5903 | role="identifier">lock</phrase><phrase role="special">()</phrase></code> | |
5904 | before the call to <code><phrase role="identifier">wait_until</phrase></code> | |
5905 | returns. The lock is also reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase | |
5906 | role="special">.</phrase><phrase role="identifier">lock</phrase><phrase | |
5907 | role="special">()</phrase></code> if the function exits with an exception. | |
5908 | The member function accepting <code><phrase role="identifier">pred</phrase></code> | |
5909 | is shorthand for: | |
5910 | <programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
5911 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase role="identifier">timeout</phrase> <phrase role="special">==</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> | |
5912 | <phrase role="keyword">return</phrase> <phrase role="identifier">pred</phrase><phrase role="special">();</phrase> | |
5913 | <phrase role="special">}</phrase> | |
5914 | <phrase role="keyword">return</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
5915 | </programlisting> | |
5916 | That is, even if <code><phrase role="identifier">wait_until</phrase><phrase | |
5917 | role="special">()</phrase></code> times out, it can still return <code><phrase | |
5918 | role="keyword">true</phrase></code> if <code><phrase role="identifier">pred</phrase><phrase | |
5919 | role="special">()</phrase></code> returns <code><phrase role="keyword">true</phrase></code> | |
5920 | at that time. | |
5921 | </para> | |
5922 | </listitem> | |
5923 | </varlistentry> | |
5924 | <varlistentry> | |
5925 | <term>Postcondition:</term> | |
5926 | <listitem> | |
5927 | <para> | |
5928 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
5929 | current fiber. | |
5930 | </para> | |
5931 | </listitem> | |
5932 | </varlistentry> | |
5933 | <varlistentry> | |
5934 | <term>Throws:</term> | |
5935 | <listitem> | |
5936 | <para> | |
5937 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
5938 | occurs or timeout-related exceptions. | |
5939 | </para> | |
5940 | </listitem> | |
5941 | </varlistentry> | |
5942 | <varlistentry> | |
5943 | <term>Returns:</term> | |
5944 | <listitem> | |
5945 | <para> | |
5946 | The overload without <code><phrase role="identifier">pred</phrase></code> | |
5947 | returns <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
5948 | role="identifier">no_timeout</phrase></code> if awakened by <code><phrase | |
5949 | role="identifier">notify_one</phrase><phrase role="special">()</phrase></code> | |
5950 | or <code><phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase></code>, | |
5951 | or <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
5952 | role="identifier">timeout</phrase></code> if awakened because the system | |
5953 | time is past <code><phrase role="identifier">abs_time</phrase></code>. | |
5954 | </para> | |
5955 | </listitem> | |
5956 | </varlistentry> | |
5957 | <varlistentry> | |
5958 | <term>Returns:</term> | |
5959 | <listitem> | |
5960 | <para> | |
5961 | The overload accepting <code><phrase role="identifier">pred</phrase></code> | |
5962 | returns <code><phrase role="keyword">false</phrase></code> if the call | |
5963 | is returning because the time specified by <code><phrase role="identifier">abs_time</phrase></code> | |
5964 | was reached and the predicate returns <code><phrase role="keyword">false</phrase></code>, | |
5965 | <code><phrase role="keyword">true</phrase></code> otherwise. | |
5966 | </para> | |
5967 | </listitem> | |
5968 | </varlistentry> | |
5969 | <varlistentry> | |
5970 | <term>Note:</term> | |
5971 | <listitem> | |
5972 | <para> | |
5973 | See <emphasis role="bold">Note</emphasis> for <link linkend="condition_variable_any_wait"><code>condition_variable_any::wait()</code></link>. | |
5974 | </para> | |
5975 | </listitem> | |
5976 | </varlistentry> | |
5977 | </variablelist> | |
5978 | <para> | |
5979 | <bridgehead renderas="sect4" id="condition_variable_any_wait_for_bridgehead"> | |
5980 | <phrase id="condition_variable_any_wait_for"/> | |
5981 | <link linkend="condition_variable_any_wait_for">Templated | |
5982 | member function <code>wait_for</code>()</link> | |
5983 | </bridgehead> | |
5984 | </para> | |
5985 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
5986 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
5987 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">);</phrase> | |
5988 | ||
5989 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename LockType, typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
5990 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> LockType <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
5991 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">,</phrase> | |
5992 | <phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase> | |
5993 | </programlisting> | |
5994 | <variablelist> | |
5995 | <title></title> | |
5996 | <varlistentry> | |
5997 | <term>Precondition:</term> | |
5998 | <listitem> | |
5999 | <para> | |
6000 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6001 | current fiber, and either no other fiber is currently waiting on <code><phrase | |
6002 | role="special">*</phrase><phrase role="keyword">this</phrase></code>, | |
6003 | or the execution of the <code><phrase role="identifier">mutex</phrase><phrase | |
6004 | role="special">()</phrase></code> member function on the <code><phrase | |
6005 | role="identifier">lk</phrase></code> objects supplied in the calls | |
6006 | to <code><phrase role="identifier">wait</phrase></code>, <code><phrase | |
6007 | role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code> | |
6008 | in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase | |
6009 | role="keyword">this</phrase></code> would return the same value as | |
6010 | <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
6011 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code> | |
6012 | for this call to <code><phrase role="identifier">wait_for</phrase></code>. | |
6013 | </para> | |
6014 | </listitem> | |
6015 | </varlistentry> | |
6016 | <varlistentry> | |
6017 | <term>Effects:</term> | |
6018 | <listitem> | |
6019 | <para> | |
6020 | Atomically call <code><phrase role="identifier">lk</phrase><phrase | |
6021 | role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase | |
6022 | role="special">()</phrase></code> and blocks the current fiber. The | |
6023 | fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase | |
6024 | role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase | |
6025 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
6026 | role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase | |
6027 | role="special">()</phrase></code>, when a time interval equal to or | |
6028 | greater than the specified <code><phrase role="identifier">rel_time</phrase></code> | |
6029 | has elapsed. When the fiber is unblocked (for whatever reason), the | |
6030 | lock is reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase | |
6031 | role="special">.</phrase><phrase role="identifier">lock</phrase><phrase | |
6032 | role="special">()</phrase></code> before the call to <code><phrase | |
6033 | role="identifier">wait</phrase></code> returns. The lock is also reacquired | |
6034 | by invoking <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
6035 | role="identifier">lock</phrase><phrase role="special">()</phrase></code> | |
6036 | if the function exits with an exception. The <code><phrase role="identifier">wait_for</phrase><phrase | |
6037 | role="special">()</phrase></code> member function accepting <code><phrase | |
6038 | role="identifier">pred</phrase></code> is shorthand for: | |
6039 | <programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6040 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase role="identifier">timeout</phrase> <phrase role="special">==</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6041 | <phrase role="keyword">return</phrase> <phrase role="identifier">pred</phrase><phrase role="special">();</phrase> | |
6042 | <phrase role="special">}</phrase> | |
6043 | <phrase role="special">}</phrase> | |
6044 | <phrase role="keyword">return</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
6045 | </programlisting> | |
6046 | (except of course that <code><phrase role="identifier">rel_time</phrase></code> | |
6047 | is adjusted for each iteration). The point is that, even if <code><phrase | |
6048 | role="identifier">wait_for</phrase><phrase role="special">()</phrase></code> | |
6049 | times out, it can still return <code><phrase role="keyword">true</phrase></code> | |
6050 | if <code><phrase role="identifier">pred</phrase><phrase role="special">()</phrase></code> | |
6051 | returns <code><phrase role="keyword">true</phrase></code> at that time. | |
6052 | </para> | |
6053 | </listitem> | |
6054 | </varlistentry> | |
6055 | <varlistentry> | |
6056 | <term>Postcondition:</term> | |
6057 | <listitem> | |
6058 | <para> | |
6059 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6060 | current fiber. | |
6061 | </para> | |
6062 | </listitem> | |
6063 | </varlistentry> | |
6064 | <varlistentry> | |
6065 | <term>Throws:</term> | |
6066 | <listitem> | |
6067 | <para> | |
6068 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
6069 | occurs or timeout-related exceptions. | |
6070 | </para> | |
6071 | </listitem> | |
6072 | </varlistentry> | |
6073 | <varlistentry> | |
6074 | <term>Returns:</term> | |
6075 | <listitem> | |
6076 | <para> | |
6077 | The overload without <code><phrase role="identifier">pred</phrase></code> | |
6078 | returns <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
6079 | role="identifier">no_timeout</phrase></code> if awakened by <code><phrase | |
6080 | role="identifier">notify_one</phrase><phrase role="special">()</phrase></code> | |
6081 | or <code><phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase></code>, | |
6082 | or <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
6083 | role="identifier">timeout</phrase></code> if awakened because at least | |
6084 | <code><phrase role="identifier">rel_time</phrase></code> has elapsed. | |
6085 | </para> | |
6086 | </listitem> | |
6087 | </varlistentry> | |
6088 | <varlistentry> | |
6089 | <term>Returns:</term> | |
6090 | <listitem> | |
6091 | <para> | |
6092 | The overload accepting <code><phrase role="identifier">pred</phrase></code> | |
6093 | returns <code><phrase role="keyword">false</phrase></code> if the call | |
6094 | is returning because at least <code><phrase role="identifier">rel_time</phrase></code> | |
6095 | has elapsed and the predicate returns <code><phrase role="keyword">false</phrase></code>, | |
6096 | <code><phrase role="keyword">true</phrase></code> otherwise. | |
6097 | </para> | |
6098 | </listitem> | |
6099 | </varlistentry> | |
6100 | <varlistentry> | |
6101 | <term>Note:</term> | |
6102 | <listitem> | |
6103 | <para> | |
6104 | See <emphasis role="bold">Note</emphasis> for <link linkend="condition_variable_any_wait"><code>condition_variable_any::wait()</code></link>. | |
6105 | </para> | |
6106 | </listitem> | |
6107 | </varlistentry> | |
6108 | </variablelist> | |
6109 | <para> | |
6110 | <bridgehead renderas="sect4" id="class_condition_variable_bridgehead"> | |
6111 | <phrase id="class_condition_variable"/> | |
6112 | <link linkend="class_condition_variable">Class | |
6113 | <code>condition_variable</code></link> | |
6114 | </bridgehead> | |
6115 | </para> | |
6116 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">condition_variable</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
6117 | ||
6118 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
6119 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
6120 | ||
6121 | <phrase role="keyword">class</phrase> condition_variable <phrase role="special">{</phrase> | |
6122 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
6123 | condition_variable<phrase role="special">();</phrase> | |
6124 | <phrase role="special">~</phrase>condition_variable<phrase role="special">();</phrase> | |
6125 | ||
6126 | condition_variable<phrase role="special">(</phrase> condition_variable <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
6127 | condition_variable <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> condition_variable <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
6128 | ||
6129 | <phrase role="keyword">void</phrase> <phrase role="identifier">notify_one</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
6130 | <phrase role="keyword">void</phrase> <phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
6131 | ||
6132 | void <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&);</phrase> | |
6133 | ||
6134 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
6135 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&,</phrase> <phrase role="identifier">Pred</phrase><phrase role="special">);</phrase> | |
6136 | ||
6137 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
6138 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&,</phrase> | |
6139 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> | |
6140 | ||
6141 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
6142 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&,</phrase> | |
6143 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&,</phrase> | |
6144 | <phrase role="identifier">Pred</phrase><phrase role="special">);</phrase> | |
6145 | ||
6146 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
6147 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&,</phrase> | |
6148 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> | |
6149 | ||
6150 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
6151 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&,</phrase> | |
6152 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&,</phrase> | |
6153 | <phrase role="identifier">Pred</phrase><phrase role="special">);</phrase> | |
6154 | <phrase role="special">};</phrase> | |
6155 | ||
6156 | <phrase role="special">}}</phrase> | |
6157 | </programlisting> | |
6158 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h7"> | |
6159 | <phrase id="fiber.synchronization.conditions.constructor0"/><link linkend="fiber.synchronization.conditions.constructor0">Constructor</link> | |
6160 | </bridgehead> | |
6161 | <programlisting>condition_variable<phrase role="special">()</phrase> | |
6162 | </programlisting> | |
6163 | <variablelist> | |
6164 | <title></title> | |
6165 | <varlistentry> | |
6166 | <term>Effects:</term> | |
6167 | <listitem> | |
6168 | <para> | |
6169 | Creates the object. | |
6170 | </para> | |
6171 | </listitem> | |
6172 | </varlistentry> | |
6173 | <varlistentry> | |
6174 | <term>Throws:</term> | |
6175 | <listitem> | |
6176 | <para> | |
6177 | Nothing. | |
6178 | </para> | |
6179 | </listitem> | |
6180 | </varlistentry> | |
6181 | </variablelist> | |
6182 | <bridgehead renderas="sect4" id="fiber.synchronization.conditions.h8"> | |
6183 | <phrase id="fiber.synchronization.conditions.destructor0"/><link linkend="fiber.synchronization.conditions.destructor0">Destructor</link> | |
6184 | </bridgehead> | |
6185 | <programlisting><phrase role="special">~</phrase>condition_variable<phrase role="special">()</phrase> | |
6186 | </programlisting> | |
6187 | <variablelist> | |
6188 | <title></title> | |
6189 | <varlistentry> | |
6190 | <term>Precondition:</term> | |
6191 | <listitem> | |
6192 | <para> | |
6193 | All fibers waiting on <code><phrase role="special">*</phrase><phrase | |
6194 | role="keyword">this</phrase></code> have been notified by a call to | |
6195 | <code><phrase role="identifier">notify_one</phrase></code> or <code><phrase | |
6196 | role="identifier">notify_all</phrase></code> (though the respective | |
6197 | calls to <code><phrase role="identifier">wait</phrase></code>, <code><phrase | |
6198 | role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code> | |
6199 | need not have returned). | |
6200 | </para> | |
6201 | </listitem> | |
6202 | </varlistentry> | |
6203 | <varlistentry> | |
6204 | <term>Effects:</term> | |
6205 | <listitem> | |
6206 | <para> | |
6207 | Destroys the object. | |
6208 | </para> | |
6209 | </listitem> | |
6210 | </varlistentry> | |
6211 | </variablelist> | |
6212 | <para> | |
6213 | <bridgehead renderas="sect4" id="condition_variable_notify_one_bridgehead"> | |
6214 | <phrase id="condition_variable_notify_one"/> | |
6215 | <link linkend="condition_variable_notify_one">Member | |
6216 | function <code>notify_one</code>()</link> | |
6217 | </bridgehead> | |
6218 | </para> | |
6219 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify_one</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
6220 | </programlisting> | |
6221 | <variablelist> | |
6222 | <title></title> | |
6223 | <varlistentry> | |
6224 | <term>Effects:</term> | |
6225 | <listitem> | |
6226 | <para> | |
6227 | If any fibers are currently <link linkend="blocking"><emphasis>blocked</emphasis></link> | |
6228 | waiting on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
6229 | in a call to <code><phrase role="identifier">wait</phrase></code>, | |
6230 | <code><phrase role="identifier">wait_for</phrase></code> or <code><phrase | |
6231 | role="identifier">wait_until</phrase></code>, unblocks one of those | |
6232 | fibers. | |
6233 | </para> | |
6234 | </listitem> | |
6235 | </varlistentry> | |
6236 | <varlistentry> | |
6237 | <term>Throws:</term> | |
6238 | <listitem> | |
6239 | <para> | |
6240 | Nothing. | |
6241 | </para> | |
6242 | </listitem> | |
6243 | </varlistentry> | |
6244 | <varlistentry> | |
6245 | <term>Note:</term> | |
6246 | <listitem> | |
6247 | <para> | |
6248 | It is arbitrary which waiting fiber is resumed. | |
6249 | </para> | |
6250 | </listitem> | |
6251 | </varlistentry> | |
6252 | </variablelist> | |
6253 | <para> | |
6254 | <bridgehead renderas="sect4" id="condition_variable_notify_all_bridgehead"> | |
6255 | <phrase id="condition_variable_notify_all"/> | |
6256 | <link linkend="condition_variable_notify_all">Member | |
6257 | function <code>notify_all</code>()</link> | |
6258 | </bridgehead> | |
6259 | </para> | |
6260 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
6261 | </programlisting> | |
6262 | <variablelist> | |
6263 | <title></title> | |
6264 | <varlistentry> | |
6265 | <term>Effects:</term> | |
6266 | <listitem> | |
6267 | <para> | |
6268 | If any fibers are currently <link linkend="blocking"><emphasis>blocked</emphasis></link> | |
6269 | waiting on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
6270 | in a call to <code><phrase role="identifier">wait</phrase></code>, | |
6271 | <code><phrase role="identifier">wait_for</phrase></code> or <code><phrase | |
6272 | role="identifier">wait_until</phrase></code>, unblocks all of those | |
6273 | fibers. | |
6274 | </para> | |
6275 | </listitem> | |
6276 | </varlistentry> | |
6277 | <varlistentry> | |
6278 | <term>Throws:</term> | |
6279 | <listitem> | |
6280 | <para> | |
6281 | Nothing. | |
6282 | </para> | |
6283 | </listitem> | |
6284 | </varlistentry> | |
6285 | <varlistentry> | |
6286 | <term>Note:</term> | |
6287 | <listitem> | |
6288 | <para> | |
6289 | This is why a waiting fiber must <emphasis>also</emphasis> check for | |
6290 | the desired program state using a mechanism external to the <code>condition_variable</code>, | |
6291 | and retry the wait until that state is reached. A fiber waiting on | |
6292 | a <code>condition_variable</code> might well wake up a number of times before the | |
6293 | desired state is reached. | |
6294 | </para> | |
6295 | </listitem> | |
6296 | </varlistentry> | |
6297 | </variablelist> | |
6298 | <para> | |
6299 | <bridgehead renderas="sect4" id="condition_variable_wait_bridgehead"> | |
6300 | <phrase id="condition_variable_wait"/> | |
6301 | <link linkend="condition_variable_wait">Templated | |
6302 | member function <code>wait</code>()</link> | |
6303 | </bridgehead> | |
6304 | </para> | |
6305 | <programlisting>void <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase> | |
6306 | ||
6307 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
6308 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase> | |
6309 | </programlisting> | |
6310 | <variablelist> | |
6311 | <title></title> | |
6312 | <varlistentry> | |
6313 | <term>Precondition:</term> | |
6314 | <listitem> | |
6315 | <para> | |
6316 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6317 | current fiber, and either no other fiber is currently waiting on <code><phrase | |
6318 | role="special">*</phrase><phrase role="keyword">this</phrase></code>, | |
6319 | or the execution of the <ulink url="http://en.cppreference.com/w/cpp/thread/unique_lock/mutex"><code><phrase | |
6320 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code></ulink> | |
6321 | member function on the <code><phrase role="identifier">lk</phrase></code> | |
6322 | objects supplied in the calls to <code><phrase role="identifier">wait</phrase></code> | |
6323 | in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase | |
6324 | role="keyword">this</phrase></code> would return the same value as | |
6325 | <code><phrase role="identifier">lk</phrase><phrase role="special">-></phrase><phrase | |
6326 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code> | |
6327 | for this call to <code><phrase role="identifier">wait</phrase></code>. | |
6328 | </para> | |
6329 | </listitem> | |
6330 | </varlistentry> | |
6331 | <varlistentry> | |
6332 | <term>Effects:</term> | |
6333 | <listitem> | |
6334 | <para> | |
6335 | Atomically call <code><phrase role="identifier">lk</phrase><phrase | |
6336 | role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase | |
6337 | role="special">()</phrase></code> and blocks the current fiber. The | |
6338 | fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase | |
6339 | role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase | |
6340 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
6341 | role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase | |
6342 | role="special">()</phrase></code>. When the fiber is unblocked (for | |
6343 | whatever reason), the lock is reacquired by invoking <code><phrase | |
6344 | role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
6345 | role="identifier">lock</phrase><phrase role="special">()</phrase></code> | |
6346 | before the call to <code><phrase role="identifier">wait</phrase></code> | |
6347 | returns. The lock is also reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase | |
6348 | role="special">.</phrase><phrase role="identifier">lock</phrase><phrase | |
6349 | role="special">()</phrase></code> if the function exits with an exception. | |
6350 | The member function accepting <code><phrase role="identifier">pred</phrase></code> | |
6351 | is shorthand for: | |
6352 | <programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6353 | <phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase> | |
6354 | <phrase role="special">}</phrase> | |
6355 | </programlisting> | |
6356 | </para> | |
6357 | </listitem> | |
6358 | </varlistentry> | |
6359 | <varlistentry> | |
6360 | <term>Postcondition:</term> | |
6361 | <listitem> | |
6362 | <para> | |
6363 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6364 | current fiber. | |
6365 | </para> | |
6366 | </listitem> | |
6367 | </varlistentry> | |
6368 | <varlistentry> | |
6369 | <term>Throws:</term> | |
6370 | <listitem> | |
6371 | <para> | |
6372 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
6373 | occurs. | |
6374 | </para> | |
6375 | </listitem> | |
6376 | </varlistentry> | |
6377 | <varlistentry> | |
6378 | <term>Note:</term> | |
6379 | <listitem> | |
6380 | <para> | |
6381 | The Precondition is a bit dense. It merely states that all the fibers | |
6382 | concurrently calling <code><phrase role="identifier">wait</phrase></code> | |
6383 | on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
6384 | must wait on <code><phrase role="identifier">lk</phrase></code> objects | |
6385 | governing the <emphasis>same</emphasis> <link linkend="class_mutex"><code>mutex</code></link>. Three distinct | |
6386 | objects are involved in any <code>condition_variable::wait()</code> call: the <code>condition_variable</code> itself, | |
6387 | the <code><phrase role="identifier">mutex</phrase></code> coordinating | |
6388 | access between fibers and a local lock object (e.g. <ulink url="http://en.cppreference.com/w/cpp/thread/unique_lock"><code><phrase | |
6389 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
6390 | role="identifier">unique_lock</phrase></code></ulink>). In general, | |
6391 | you can partition the lifespan of a given <code>condition_variable</code> instance | |
6392 | into periods with one or more fibers waiting on it, separated by periods | |
6393 | when no fibers are waiting on it. When more than one fiber is waiting | |
6394 | on that <code>condition_variable</code>, all must pass lock objects referencing | |
6395 | the <emphasis>same</emphasis> <code><phrase role="identifier">mutex</phrase></code> | |
6396 | instance. | |
6397 | </para> | |
6398 | </listitem> | |
6399 | </varlistentry> | |
6400 | </variablelist> | |
6401 | <para> | |
6402 | <bridgehead renderas="sect4" id="condition_variable_wait_until_bridgehead"> | |
6403 | <phrase id="condition_variable_wait_until"/> | |
6404 | <link linkend="condition_variable_wait_until">Templated | |
6405 | member function <code>wait_until</code>()</link> | |
6406 | </bridgehead> | |
6407 | </para> | |
6408 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
6409 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
6410 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">);</phrase> | |
6411 | ||
6412 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
6413 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
6414 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">,</phrase> | |
6415 | <phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase> | |
6416 | </programlisting> | |
6417 | <variablelist> | |
6418 | <title></title> | |
6419 | <varlistentry> | |
6420 | <term>Precondition:</term> | |
6421 | <listitem> | |
6422 | <para> | |
6423 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6424 | current fiber, and either no other fiber is currently waiting on <code><phrase | |
6425 | role="special">*</phrase><phrase role="keyword">this</phrase></code>, | |
6426 | or the execution of the <code><phrase role="identifier">mutex</phrase><phrase | |
6427 | role="special">()</phrase></code> member function on the <code><phrase | |
6428 | role="identifier">lk</phrase></code> objects supplied in the calls | |
6429 | to <code><phrase role="identifier">wait</phrase></code>, <code><phrase | |
6430 | role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code> | |
6431 | in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase | |
6432 | role="keyword">this</phrase></code> would return the same value as | |
6433 | <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
6434 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code> | |
6435 | for this call to <code><phrase role="identifier">wait_until</phrase></code>. | |
6436 | </para> | |
6437 | </listitem> | |
6438 | </varlistentry> | |
6439 | <varlistentry> | |
6440 | <term>Effects:</term> | |
6441 | <listitem> | |
6442 | <para> | |
6443 | Atomically call <code><phrase role="identifier">lk</phrase><phrase | |
6444 | role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase | |
6445 | role="special">()</phrase></code> and blocks the current fiber. The | |
6446 | fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase | |
6447 | role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase | |
6448 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
6449 | role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase | |
6450 | role="special">()</phrase></code>, when the system time would be equal | |
6451 | to or later than the specified <code><phrase role="identifier">abs_time</phrase></code>. | |
6452 | When the fiber is unblocked (for whatever reason), the lock is reacquired | |
6453 | by invoking <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
6454 | role="identifier">lock</phrase><phrase role="special">()</phrase></code> | |
6455 | before the call to <code><phrase role="identifier">wait_until</phrase></code> | |
6456 | returns. The lock is also reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase | |
6457 | role="special">.</phrase><phrase role="identifier">lock</phrase><phrase | |
6458 | role="special">()</phrase></code> if the function exits with an exception. | |
6459 | The member function accepting <code><phrase role="identifier">pred</phrase></code> | |
6460 | is shorthand for: | |
6461 | <programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6462 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase role="identifier">timeout</phrase> <phrase role="special">==</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> | |
6463 | <phrase role="keyword">return</phrase> <phrase role="identifier">pred</phrase><phrase role="special">();</phrase> | |
6464 | <phrase role="special">}</phrase> | |
6465 | <phrase role="keyword">return</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
6466 | </programlisting> | |
6467 | That is, even if <code><phrase role="identifier">wait_until</phrase><phrase | |
6468 | role="special">()</phrase></code> times out, it can still return <code><phrase | |
6469 | role="keyword">true</phrase></code> if <code><phrase role="identifier">pred</phrase><phrase | |
6470 | role="special">()</phrase></code> returns <code><phrase role="keyword">true</phrase></code> | |
6471 | at that time. | |
6472 | </para> | |
6473 | </listitem> | |
6474 | </varlistentry> | |
6475 | <varlistentry> | |
6476 | <term>Postcondition:</term> | |
6477 | <listitem> | |
6478 | <para> | |
6479 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6480 | current fiber. | |
6481 | </para> | |
6482 | </listitem> | |
6483 | </varlistentry> | |
6484 | <varlistentry> | |
6485 | <term>Throws:</term> | |
6486 | <listitem> | |
6487 | <para> | |
6488 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
6489 | occurs or timeout-related exceptions. | |
6490 | </para> | |
6491 | </listitem> | |
6492 | </varlistentry> | |
6493 | <varlistentry> | |
6494 | <term>Returns:</term> | |
6495 | <listitem> | |
6496 | <para> | |
6497 | The overload without <code><phrase role="identifier">pred</phrase></code> | |
6498 | returns <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
6499 | role="identifier">no_timeout</phrase></code> if awakened by <code><phrase | |
6500 | role="identifier">notify_one</phrase><phrase role="special">()</phrase></code> | |
6501 | or <code><phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase></code>, | |
6502 | or <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
6503 | role="identifier">timeout</phrase></code> if awakened because the system | |
6504 | time is past <code><phrase role="identifier">abs_time</phrase></code>. | |
6505 | </para> | |
6506 | </listitem> | |
6507 | </varlistentry> | |
6508 | <varlistentry> | |
6509 | <term>Returns:</term> | |
6510 | <listitem> | |
6511 | <para> | |
6512 | The overload accepting <code><phrase role="identifier">pred</phrase></code> | |
6513 | returns <code><phrase role="keyword">false</phrase></code> if the call | |
6514 | is returning because the time specified by <code><phrase role="identifier">abs_time</phrase></code> | |
6515 | was reached and the predicate returns <code><phrase role="keyword">false</phrase></code>, | |
6516 | <code><phrase role="keyword">true</phrase></code> otherwise. | |
6517 | </para> | |
6518 | </listitem> | |
6519 | </varlistentry> | |
6520 | <varlistentry> | |
6521 | <term>Note:</term> | |
6522 | <listitem> | |
6523 | <para> | |
6524 | See <emphasis role="bold">Note</emphasis> for <link linkend="condition_variable_wait"><code>condition_variable::wait()</code></link>. | |
6525 | </para> | |
6526 | </listitem> | |
6527 | </varlistentry> | |
6528 | </variablelist> | |
6529 | <para> | |
6530 | <bridgehead renderas="sect4" id="condition_variable_wait_for_bridgehead"> | |
6531 | <phrase id="condition_variable_wait_for"/> | |
6532 | <link linkend="condition_variable_wait_for">Templated | |
6533 | member function <code>wait_for</code>()</link> | |
6534 | </bridgehead> | |
6535 | </para> | |
6536 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
6537 | <phrase role="identifier">cv_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
6538 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">);</phrase> | |
6539 | ||
6540 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> typename <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Pred</phrase> <phrase role="special">></phrase> | |
6541 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> std::unique_lock< mutex > <phrase role="special">&</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> | |
6542 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">,</phrase> | |
6543 | <phrase role="identifier">Pred</phrase> <phrase role="identifier">pred</phrase><phrase role="special">);</phrase> | |
6544 | </programlisting> | |
6545 | <variablelist> | |
6546 | <title></title> | |
6547 | <varlistentry> | |
6548 | <term>Precondition:</term> | |
6549 | <listitem> | |
6550 | <para> | |
6551 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6552 | current fiber, and either no other fiber is currently waiting on <code><phrase | |
6553 | role="special">*</phrase><phrase role="keyword">this</phrase></code>, | |
6554 | or the execution of the <code><phrase role="identifier">mutex</phrase><phrase | |
6555 | role="special">()</phrase></code> member function on the <code><phrase | |
6556 | role="identifier">lk</phrase></code> objects supplied in the calls | |
6557 | to <code><phrase role="identifier">wait</phrase></code>, <code><phrase | |
6558 | role="identifier">wait_for</phrase></code> or <code><phrase role="identifier">wait_until</phrase></code> | |
6559 | in all the fibers currently waiting on <code><phrase role="special">*</phrase><phrase | |
6560 | role="keyword">this</phrase></code> would return the same value as | |
6561 | <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
6562 | role="identifier">mutex</phrase><phrase role="special">()</phrase></code> | |
6563 | for this call to <code><phrase role="identifier">wait_for</phrase></code>. | |
6564 | </para> | |
6565 | </listitem> | |
6566 | </varlistentry> | |
6567 | <varlistentry> | |
6568 | <term>Effects:</term> | |
6569 | <listitem> | |
6570 | <para> | |
6571 | Atomically call <code><phrase role="identifier">lk</phrase><phrase | |
6572 | role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase | |
6573 | role="special">()</phrase></code> and blocks the current fiber. The | |
6574 | fiber will unblock when notified by a call to <code><phrase role="keyword">this</phrase><phrase | |
6575 | role="special">-></phrase><phrase role="identifier">notify_one</phrase><phrase | |
6576 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
6577 | role="special">-></phrase><phrase role="identifier">notify_all</phrase><phrase | |
6578 | role="special">()</phrase></code>, when a time interval equal to or | |
6579 | greater than the specified <code><phrase role="identifier">rel_time</phrase></code> | |
6580 | has elapsed. When the fiber is unblocked (for whatever reason), the | |
6581 | lock is reacquired by invoking <code><phrase role="identifier">lk</phrase><phrase | |
6582 | role="special">.</phrase><phrase role="identifier">lock</phrase><phrase | |
6583 | role="special">()</phrase></code> before the call to <code><phrase | |
6584 | role="identifier">wait</phrase></code> returns. The lock is also reacquired | |
6585 | by invoking <code><phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase | |
6586 | role="identifier">lock</phrase><phrase role="special">()</phrase></code> | |
6587 | if the function exits with an exception. The <code><phrase role="identifier">wait_for</phrase><phrase | |
6588 | role="special">()</phrase></code> member function accepting <code><phrase | |
6589 | role="identifier">pred</phrase></code> is shorthand for: | |
6590 | <programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">pred</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6591 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase role="identifier">timeout</phrase> <phrase role="special">==</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">rel_time</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6592 | <phrase role="keyword">return</phrase> <phrase role="identifier">pred</phrase><phrase role="special">();</phrase> | |
6593 | <phrase role="special">}</phrase> | |
6594 | <phrase role="special">}</phrase> | |
6595 | <phrase role="keyword">return</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
6596 | </programlisting> | |
6597 | (except of course that <code><phrase role="identifier">rel_time</phrase></code> | |
6598 | is adjusted for each iteration). The point is that, even if <code><phrase | |
6599 | role="identifier">wait_for</phrase><phrase role="special">()</phrase></code> | |
6600 | times out, it can still return <code><phrase role="keyword">true</phrase></code> | |
6601 | if <code><phrase role="identifier">pred</phrase><phrase role="special">()</phrase></code> | |
6602 | returns <code><phrase role="keyword">true</phrase></code> at that time. | |
6603 | </para> | |
6604 | </listitem> | |
6605 | </varlistentry> | |
6606 | <varlistentry> | |
6607 | <term>Postcondition:</term> | |
6608 | <listitem> | |
6609 | <para> | |
6610 | <code><phrase role="identifier">lk</phrase></code> is locked by the | |
6611 | current fiber. | |
6612 | </para> | |
6613 | </listitem> | |
6614 | </varlistentry> | |
6615 | <varlistentry> | |
6616 | <term>Throws:</term> | |
6617 | <listitem> | |
6618 | <para> | |
6619 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
6620 | occurs or timeout-related exceptions. | |
6621 | </para> | |
6622 | </listitem> | |
6623 | </varlistentry> | |
6624 | <varlistentry> | |
6625 | <term>Returns:</term> | |
6626 | <listitem> | |
6627 | <para> | |
6628 | The overload without <code><phrase role="identifier">pred</phrase></code> | |
6629 | returns <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
6630 | role="identifier">no_timeout</phrase></code> if awakened by <code><phrase | |
6631 | role="identifier">notify_one</phrase><phrase role="special">()</phrase></code> | |
6632 | or <code><phrase role="identifier">notify_all</phrase><phrase role="special">()</phrase></code>, | |
6633 | or <code><phrase role="identifier">cv_status</phrase><phrase role="special">::</phrase><phrase | |
6634 | role="identifier">timeout</phrase></code> if awakened because at least | |
6635 | <code><phrase role="identifier">rel_time</phrase></code> has elapsed. | |
6636 | </para> | |
6637 | </listitem> | |
6638 | </varlistentry> | |
6639 | <varlistentry> | |
6640 | <term>Returns:</term> | |
6641 | <listitem> | |
6642 | <para> | |
6643 | The overload accepting <code><phrase role="identifier">pred</phrase></code> | |
6644 | returns <code><phrase role="keyword">false</phrase></code> if the call | |
6645 | is returning because at least <code><phrase role="identifier">rel_time</phrase></code> | |
6646 | has elapsed and the predicate returns <code><phrase role="keyword">false</phrase></code>, | |
6647 | <code><phrase role="keyword">true</phrase></code> otherwise. | |
6648 | </para> | |
6649 | </listitem> | |
6650 | </varlistentry> | |
6651 | <varlistentry> | |
6652 | <term>Note:</term> | |
6653 | <listitem> | |
6654 | <para> | |
6655 | See <emphasis role="bold">Note</emphasis> for <link linkend="condition_variable_wait"><code>condition_variable::wait()</code></link>. | |
6656 | </para> | |
6657 | </listitem> | |
6658 | </varlistentry> | |
6659 | </variablelist> | |
6660 | </section> | |
6661 | <section id="fiber.synchronization.barriers"> | |
6662 | <title><link linkend="fiber.synchronization.barriers">Barriers</link></title> | |
6663 | <para> | |
6664 | A barrier is a concept also known as a <emphasis>rendezvous</emphasis>, it | |
6665 | is a synchronization point between multiple contexts of execution (fibers). | |
6666 | The barrier is configured for a particular number of fibers (<code><phrase | |
6667 | role="identifier">n</phrase></code>), and as fibers reach the barrier they | |
6668 | must wait until all <code><phrase role="identifier">n</phrase></code> fibers | |
6669 | have arrived. Once the <code><phrase role="identifier">n</phrase></code>-th | |
6670 | fiber has reached the barrier, all the waiting fibers can proceed, and the | |
6671 | barrier is reset. | |
6672 | </para> | |
6673 | <para> | |
6674 | The fact that the barrier automatically resets is significant. Consider a | |
6675 | case in which you launch some number of fibers and want to wait only until | |
6676 | the first of them has completed. You might be tempted to use a <code><phrase | |
6677 | role="identifier">barrier</phrase><phrase role="special">(</phrase><phrase | |
6678 | role="number">2</phrase><phrase role="special">)</phrase></code> as the synchronization | |
6679 | mechanism, making each new fiber call its <link linkend="barrier_wait"><code>barrier::wait()</code></link> method, | |
6680 | then calling <code><phrase role="identifier">wait</phrase><phrase role="special">()</phrase></code> | |
6681 | in the launching fiber to wait until the first other fiber completes. | |
6682 | </para> | |
6683 | <para> | |
6684 | That will in fact unblock the launching fiber. The unfortunate part is that | |
6685 | it will continue blocking the <emphasis>remaining</emphasis> fibers. | |
6686 | </para> | |
6687 | <para> | |
6688 | Consider the following scenario: | |
6689 | </para> | |
6690 | <orderedlist> | |
6691 | <listitem> | |
6692 | <simpara> | |
6693 | Fiber <quote>main</quote> launches fibers A, B, C and D, then calls | |
6694 | <code><phrase role="identifier">barrier</phrase><phrase role="special">::</phrase><phrase | |
6695 | role="identifier">wait</phrase><phrase role="special">()</phrase></code>. | |
6696 | </simpara> | |
6697 | </listitem> | |
6698 | <listitem> | |
6699 | <simpara> | |
6700 | Fiber C finishes first and likewise calls <code><phrase role="identifier">barrier</phrase><phrase | |
6701 | role="special">::</phrase><phrase role="identifier">wait</phrase><phrase | |
6702 | role="special">()</phrase></code>. | |
6703 | </simpara> | |
6704 | </listitem> | |
6705 | <listitem> | |
6706 | <simpara> | |
6707 | Fiber <quote>main</quote> is unblocked, as desired. | |
6708 | </simpara> | |
6709 | </listitem> | |
6710 | <listitem> | |
6711 | <simpara> | |
6712 | Fiber B calls <code><phrase role="identifier">barrier</phrase><phrase | |
6713 | role="special">::</phrase><phrase role="identifier">wait</phrase><phrase | |
6714 | role="special">()</phrase></code>. Fiber B is <emphasis>blocked!</emphasis> | |
6715 | </simpara> | |
6716 | </listitem> | |
6717 | <listitem> | |
6718 | <simpara> | |
6719 | Fiber A calls <code><phrase role="identifier">barrier</phrase><phrase | |
6720 | role="special">::</phrase><phrase role="identifier">wait</phrase><phrase | |
6721 | role="special">()</phrase></code>. Fibers A and B are unblocked. | |
6722 | </simpara> | |
6723 | </listitem> | |
6724 | <listitem> | |
6725 | <simpara> | |
6726 | Fiber D calls <code><phrase role="identifier">barrier</phrase><phrase | |
6727 | role="special">::</phrase><phrase role="identifier">wait</phrase><phrase | |
6728 | role="special">()</phrase></code>. Fiber D is blocked indefinitely. | |
6729 | </simpara> | |
6730 | </listitem> | |
6731 | </orderedlist> | |
6732 | <para> | |
6733 | (See also <link linkend="wait_first_simple_section">when_any, simple completion</link>.) | |
6734 | </para> | |
6735 | <note> | |
6736 | <para> | |
6737 | It is unwise to tie the lifespan of a barrier to any one of its participating | |
6738 | fibers. Although conceptually all waiting fibers awaken <quote>simultaneously,</quote> | |
6739 | because of the nature of fibers, in practice they will awaken one by one | |
6740 | in indeterminate order.<footnote id="fiber.synchronization.barriers.f0"> | |
6741 | <para> | |
6742 | The current implementation wakes fibers in FIFO order: the first to call | |
6743 | <code><phrase role="identifier">wait</phrase><phrase role="special">()</phrase></code> | |
6744 | wakes first, and so forth. But it is perilous to rely on the order in | |
6745 | which the various fibers will reach the <code><phrase role="identifier">wait</phrase><phrase | |
6746 | role="special">()</phrase></code> call. | |
6747 | </para> | |
6748 | </footnote> The rest of the waiting fibers will still be blocked in <code><phrase | |
6749 | role="identifier">wait</phrase><phrase role="special">()</phrase></code>, | |
6750 | which must, before returning, access data members in the barrier object. | |
6751 | </para> | |
6752 | </note> | |
6753 | <para> | |
6754 | <bridgehead renderas="sect4" id="class_barrier_bridgehead"> | |
6755 | <phrase id="class_barrier"/> | |
6756 | <link linkend="class_barrier">Class <code>barrier</code></link> | |
6757 | </bridgehead> | |
6758 | </para> | |
6759 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">barrier</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
6760 | ||
6761 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
6762 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
6763 | ||
6764 | <phrase role="keyword">class</phrase> <phrase role="identifier">barrier</phrase> <phrase role="special">{</phrase> | |
6765 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
6766 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">barrier</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase><phrase role="special">);</phrase> | |
6767 | ||
6768 | <phrase role="identifier">barrier</phrase><phrase role="special">(</phrase> <phrase role="identifier">barrier</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
6769 | <phrase role="identifier">barrier</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">barrier</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
6770 | ||
6771 | <phrase role="keyword">bool</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
6772 | <phrase role="special">};</phrase> | |
6773 | ||
6774 | <phrase role="special">}}</phrase> | |
6775 | </programlisting> | |
6776 | <para> | |
6777 | Instances of <link linkend="class_barrier"><code>barrier</code></link> are not copyable or movable. | |
6778 | </para> | |
6779 | <bridgehead renderas="sect4" id="fiber.synchronization.barriers.h0"> | |
6780 | <phrase id="fiber.synchronization.barriers.constructor"/><link linkend="fiber.synchronization.barriers.constructor">Constructor</link> | |
6781 | </bridgehead> | |
6782 | <programlisting><phrase role="keyword">explicit</phrase> <phrase role="identifier">barrier</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">initial</phrase><phrase role="special">);</phrase> | |
6783 | </programlisting> | |
6784 | <variablelist> | |
6785 | <title></title> | |
6786 | <varlistentry> | |
6787 | <term>Effects:</term> | |
6788 | <listitem> | |
6789 | <para> | |
6790 | Construct a barrier for <code><phrase role="identifier">initial</phrase></code> | |
6791 | fibers. | |
6792 | </para> | |
6793 | </listitem> | |
6794 | </varlistentry> | |
6795 | <varlistentry> | |
6796 | <term>Throws:</term> | |
6797 | <listitem> | |
6798 | <para> | |
6799 | <code><phrase role="identifier">fiber_error</phrase></code> | |
6800 | </para> | |
6801 | </listitem> | |
6802 | </varlistentry> | |
6803 | <varlistentry> | |
6804 | <term>Error Conditions:</term> | |
6805 | <listitem> | |
6806 | <para> | |
6807 | <emphasis role="bold">invalid_argument</emphasis>: if <code><phrase | |
6808 | role="identifier">initial</phrase></code> is zero. | |
6809 | </para> | |
6810 | </listitem> | |
6811 | </varlistentry> | |
6812 | </variablelist> | |
6813 | <para> | |
6814 | <bridgehead renderas="sect4" id="barrier_wait_bridgehead"> | |
6815 | <phrase id="barrier_wait"/> | |
6816 | <link linkend="barrier_wait">Member function <code>wait</code>()</link> | |
6817 | </bridgehead> | |
6818 | </para> | |
6819 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
6820 | </programlisting> | |
6821 | <variablelist> | |
6822 | <title></title> | |
6823 | <varlistentry> | |
6824 | <term>Effects:</term> | |
6825 | <listitem> | |
6826 | <para> | |
6827 | Block until <code><phrase role="identifier">initial</phrase></code> | |
6828 | fibers have called <code><phrase role="identifier">wait</phrase></code> | |
6829 | on <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
6830 | When the <code><phrase role="identifier">initial</phrase></code>-th | |
6831 | fiber calls <code><phrase role="identifier">wait</phrase></code>, all | |
6832 | waiting fibers are unblocked, and the barrier is reset. | |
6833 | </para> | |
6834 | </listitem> | |
6835 | </varlistentry> | |
6836 | <varlistentry> | |
6837 | <term>Returns:</term> | |
6838 | <listitem> | |
6839 | <para> | |
6840 | <code><phrase role="keyword">true</phrase></code> for exactly one fiber | |
6841 | from each batch of waiting fibers, <code><phrase role="keyword">false</phrase></code> | |
6842 | otherwise. | |
6843 | </para> | |
6844 | </listitem> | |
6845 | </varlistentry> | |
6846 | <varlistentry> | |
6847 | <term>Throws:</term> | |
6848 | <listitem> | |
6849 | <para> | |
6850 | <code><phrase role="identifier">fiber_error</phrase></code> | |
6851 | </para> | |
6852 | </listitem> | |
6853 | </varlistentry> | |
6854 | </variablelist> | |
6855 | </section> | |
6856 | <section id="fiber.synchronization.channels"> | |
6857 | <title><link linkend="fiber.synchronization.channels">Channels</link></title> | |
6858 | <para> | |
6859 | <emphasis role="bold">Boost.Fiber</emphasis> provides a bounded and a unbounded | |
6860 | channel suitable to synchonize fibers via message passing. | |
6861 | </para> | |
6862 | <programlisting><phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="keyword">int</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase> | |
6863 | ||
6864 | <phrase role="keyword">void</phrase> <phrase role="identifier">send</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">&</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6865 | <phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">i</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> <phrase role="identifier">i</phrase> <phrase role="special"><</phrase> <phrase role="number">5</phrase><phrase role="special">;</phrase> <phrase role="special">++</phrase><phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6866 | <phrase role="identifier">channel</phrase><phrase role="special">.</phrase><phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">i</phrase><phrase role="special">);</phrase> | |
6867 | <phrase role="special">}</phrase> | |
6868 | <phrase role="identifier">channel</phrase><phrase role="special">.</phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase> | |
6869 | <phrase role="special">}</phrase> | |
6870 | ||
6871 | <phrase role="keyword">void</phrase> <phrase role="identifier">recv</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">&</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6872 | <phrase role="keyword">int</phrase> <phrase role="identifier">i</phrase><phrase role="special">;</phrase> | |
6873 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">==</phrase> <phrase role="identifier">channel</phrase><phrase role="special">.</phrase><phrase role="identifier">pop</phrase><phrase role="special">(</phrase><phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
6874 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"received "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">i</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
6875 | <phrase role="special">}</phrase> | |
6876 | <phrase role="special">}</phrase> | |
6877 | ||
6878 | <phrase role="identifier">channel_t</phrase> <phrase role="identifier">channel</phrase><phrase role="special">;</phrase> | |
6879 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f1</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">(</phrase> <phrase role="identifier">send</phrase><phrase role="special">,</phrase> <phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
6880 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">f2</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">(</phrase> <phrase role="identifier">recv</phrase><phrase role="special">,</phrase> <phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">channel</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
6881 | ||
6882 | <phrase role="identifier">f1</phrase><phrase role="special">.</phrase><phrase role="identifier">join</phrase><phrase role="special">();</phrase> | |
6883 | <phrase role="identifier">f2</phrase><phrase role="special">.</phrase><phrase role="identifier">join</phrase><phrase role="special">();</phrase> | |
6884 | </programlisting> | |
6885 | <anchor id="class_channel_op_status"/> | |
6886 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h0"> | |
6887 | <phrase id="fiber.synchronization.channels.enumeration__code__phrase_role__identifier__channel_op_status__phrase___code_"/><link | |
6888 | linkend="fiber.synchronization.channels.enumeration__code__phrase_role__identifier__channel_op_status__phrase___code_">Enumeration | |
6889 | <code><phrase role="identifier">channel_op_status</phrase></code></link> | |
6890 | </bridgehead> | |
6891 | <para> | |
6892 | channel operations return the state of the channel. | |
6893 | </para> | |
6894 | <programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">channel_op_status</phrase> <phrase role="special">{</phrase> | |
6895 | <phrase role="identifier">success</phrase><phrase role="special">,</phrase> | |
6896 | <phrase role="identifier">empty</phrase><phrase role="special">,</phrase> | |
6897 | <phrase role="identifier">full</phrase><phrase role="special">,</phrase> | |
6898 | <phrase role="identifier">closed</phrase><phrase role="special">,</phrase> | |
6899 | <phrase role="identifier">timeout</phrase> | |
6900 | <phrase role="special">};</phrase> | |
6901 | </programlisting> | |
6902 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h1"> | |
6903 | <phrase id="fiber.synchronization.channels._code__phrase_role__identifier__success__phrase___code_"/><link | |
6904 | linkend="fiber.synchronization.channels._code__phrase_role__identifier__success__phrase___code_"><code><phrase | |
6905 | role="identifier">success</phrase></code></link> | |
6906 | </bridgehead> | |
6907 | <variablelist> | |
6908 | <title></title> | |
6909 | <varlistentry> | |
6910 | <term>Effects:</term> | |
6911 | <listitem> | |
6912 | <para> | |
6913 | Operation was successful. | |
6914 | </para> | |
6915 | </listitem> | |
6916 | </varlistentry> | |
6917 | </variablelist> | |
6918 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h2"> | |
6919 | <phrase id="fiber.synchronization.channels._code__phrase_role__identifier__empty__phrase___code_"/><link | |
6920 | linkend="fiber.synchronization.channels._code__phrase_role__identifier__empty__phrase___code_"><code><phrase | |
6921 | role="identifier">empty</phrase></code></link> | |
6922 | </bridgehead> | |
6923 | <variablelist> | |
6924 | <title></title> | |
6925 | <varlistentry> | |
6926 | <term>Effects:</term> | |
6927 | <listitem> | |
6928 | <para> | |
6929 | channel is empty, operation failed. | |
6930 | </para> | |
6931 | </listitem> | |
6932 | </varlistentry> | |
6933 | </variablelist> | |
6934 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h3"> | |
6935 | <phrase id="fiber.synchronization.channels._code__phrase_role__identifier__full__phrase___code_"/><link | |
6936 | linkend="fiber.synchronization.channels._code__phrase_role__identifier__full__phrase___code_"><code><phrase | |
6937 | role="identifier">full</phrase></code></link> | |
6938 | </bridgehead> | |
6939 | <variablelist> | |
6940 | <title></title> | |
6941 | <varlistentry> | |
6942 | <term>Effects:</term> | |
6943 | <listitem> | |
6944 | <para> | |
6945 | channel is full, operation failed. | |
6946 | </para> | |
6947 | </listitem> | |
6948 | </varlistentry> | |
6949 | </variablelist> | |
6950 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h4"> | |
6951 | <phrase id="fiber.synchronization.channels._code__phrase_role__identifier__closed__phrase___code_"/><link | |
6952 | linkend="fiber.synchronization.channels._code__phrase_role__identifier__closed__phrase___code_"><code><phrase | |
6953 | role="identifier">closed</phrase></code></link> | |
6954 | </bridgehead> | |
6955 | <variablelist> | |
6956 | <title></title> | |
6957 | <varlistentry> | |
6958 | <term>Effects:</term> | |
6959 | <listitem> | |
6960 | <para> | |
6961 | channel is closed, operation failed. | |
6962 | </para> | |
6963 | </listitem> | |
6964 | </varlistentry> | |
6965 | </variablelist> | |
6966 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h5"> | |
6967 | <phrase id="fiber.synchronization.channels._code__phrase_role__identifier__timeout__phrase___code_"/><link | |
6968 | linkend="fiber.synchronization.channels._code__phrase_role__identifier__timeout__phrase___code_"><code><phrase | |
6969 | role="identifier">timeout</phrase></code></link> | |
6970 | </bridgehead> | |
6971 | <variablelist> | |
6972 | <title></title> | |
6973 | <varlistentry> | |
6974 | <term>Effects:</term> | |
6975 | <listitem> | |
6976 | <para> | |
6977 | The operation did not become ready before specified timeout elapsed. | |
6978 | </para> | |
6979 | </listitem> | |
6980 | </varlistentry> | |
6981 | </variablelist> | |
6982 | <para> | |
6983 | <bridgehead renderas="sect4" id="class_unbounded_channel_bridgehead"> | |
6984 | <phrase id="class_unbounded_channel"/> | |
6985 | <link linkend="class_unbounded_channel">Template | |
6986 | <code>unbounded_channel<></code></link> | |
6987 | </bridgehead> | |
6988 | </para> | |
6989 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
6990 | ||
6991 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
6992 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
6993 | ||
6994 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="special">=</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase></code></ulink> <phrase role="special">></phrase> | |
6995 | <phrase role="keyword">class</phrase> <phrase role="identifier">unbounded_channel</phrase> <phrase role="special">{</phrase> | |
6996 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
6997 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">value_type</phrase><phrase role="special">;</phrase> | |
6998 | ||
6999 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">unbounded_channel</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase> <phrase role="special">=</phrase> <phrase role="identifier">Allocator</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7000 | ||
7001 | <phrase role="identifier">unbounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">unbounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
7002 | <phrase role="identifier">unbounded_channel</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">unbounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
7003 | ||
7004 | <phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7005 | ||
7006 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7007 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7008 | ||
7009 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7010 | <phrase role="identifier">value_type</phrase> <phrase role="identifier">value_pop</phrase><phrase role="special">();</phrase> | |
7011 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7012 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
7013 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_for</phrase><phrase role="special">(</phrase> | |
7014 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7015 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
7016 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7017 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_until</phrase><phrase role="special">(</phrase> | |
7018 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7019 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
7020 | <phrase role="special">};</phrase> | |
7021 | ||
7022 | <phrase role="special">}}</phrase> | |
7023 | </programlisting> | |
7024 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h6"> | |
7025 | <phrase id="fiber.synchronization.channels.constructor"/><link linkend="fiber.synchronization.channels.constructor">Constructor</link> | |
7026 | </bridgehead> | |
7027 | <programlisting><phrase role="keyword">explicit</phrase> <phrase role="identifier">unbounded_channel</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase> <phrase role="special">=</phrase> <phrase role="identifier">Allocator</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7028 | </programlisting> | |
7029 | <variablelist> | |
7030 | <title></title> | |
7031 | <varlistentry> | |
7032 | <term>Effects:</term> | |
7033 | <listitem> | |
7034 | <para> | |
7035 | Constructs an object of class <code><phrase role="identifier">unbounded_channel</phrase></code>. | |
7036 | Internal nodes are allocated using <code><phrase role="identifier">alloc</phrase></code> | |
7037 | - C++11-allocators are supported. | |
7038 | </para> | |
7039 | </listitem> | |
7040 | </varlistentry> | |
7041 | <varlistentry> | |
7042 | <term>Throws:</term> | |
7043 | <listitem> | |
7044 | <para> | |
7045 | Nothing. | |
7046 | </para> | |
7047 | </listitem> | |
7048 | </varlistentry> | |
7049 | <varlistentry> | |
7050 | <term>See also:</term> | |
7051 | <listitem> | |
7052 | <para> | |
7053 | <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase | |
7054 | role="identifier">Allocator</phrase></code></ulink> concept, <ulink | |
7055 | url="http://en.cppreference.com/w/cpp/memory/allocator"><code><phrase | |
7056 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7057 | role="identifier">allocator</phrase><phrase role="special"><</phrase> | |
7058 | <phrase role="identifier">T</phrase> <phrase role="special">></phrase></code></ulink> | |
7059 | </para> | |
7060 | </listitem> | |
7061 | </varlistentry> | |
7062 | </variablelist> | |
7063 | <para> | |
7064 | <bridgehead renderas="sect4" id="unbounded_channel_close_bridgehead"> | |
7065 | <phrase id="unbounded_channel_close"/> | |
7066 | <link linkend="unbounded_channel_close">Member | |
7067 | function <code>close</code>()</link> | |
7068 | </bridgehead> | |
7069 | </para> | |
7070 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7071 | </programlisting> | |
7072 | <variablelist> | |
7073 | <title></title> | |
7074 | <varlistentry> | |
7075 | <term>Effects:</term> | |
7076 | <listitem> | |
7077 | <para> | |
7078 | Deactivates the channel. No values can be put after calling <code><phrase | |
7079 | role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7080 | role="identifier">close</phrase><phrase role="special">()</phrase></code>. | |
7081 | Fibers blocked in <code><phrase role="keyword">this</phrase><phrase | |
7082 | role="special">-></phrase><phrase role="identifier">pop</phrase><phrase | |
7083 | role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase | |
7084 | role="special">-></phrase><phrase role="identifier">pop_wait_for</phrase><phrase | |
7085 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
7086 | role="special">-></phrase><phrase role="identifier">pop_wait_until</phrase><phrase | |
7087 | role="special">()</phrase></code> will return <code><phrase role="identifier">closed</phrase></code>. | |
7088 | Fibers blocked in <code><phrase role="keyword">this</phrase><phrase | |
7089 | role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase | |
7090 | role="special">()</phrase></code> will receive an exception. | |
7091 | </para> | |
7092 | </listitem> | |
7093 | </varlistentry> | |
7094 | <varlistentry> | |
7095 | <term>Throws:</term> | |
7096 | <listitem> | |
7097 | <para> | |
7098 | Nothing. | |
7099 | </para> | |
7100 | </listitem> | |
7101 | </varlistentry> | |
7102 | <varlistentry> | |
7103 | <term>Note:</term> | |
7104 | <listitem> | |
7105 | <para> | |
7106 | <code><phrase role="identifier">close</phrase><phrase role="special">()</phrase></code> | |
7107 | is like closing a pipe. It informs waiting consumers that no more values | |
7108 | will arrive. | |
7109 | </para> | |
7110 | </listitem> | |
7111 | </varlistentry> | |
7112 | </variablelist> | |
7113 | <para> | |
7114 | <bridgehead renderas="sect4" id="unbounded_channel_push_bridgehead"> | |
7115 | <phrase id="unbounded_channel_push"/> | |
7116 | <link linkend="unbounded_channel_push">Member | |
7117 | function <code>push</code>()</link> | |
7118 | </bridgehead> | |
7119 | </para> | |
7120 | <programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7121 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7122 | </programlisting> | |
7123 | <variablelist> | |
7124 | <title></title> | |
7125 | <varlistentry> | |
7126 | <term>Effects:</term> | |
7127 | <listitem> | |
7128 | <para> | |
7129 | If channel is closed, returns <code><phrase role="identifier">closed</phrase></code>. | |
7130 | Otherwise enqueues the value in the channel, wakes up a fiber blocked | |
7131 | on <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7132 | role="identifier">pop</phrase><phrase role="special">()</phrase></code>, | |
7133 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7134 | role="identifier">value_pop</phrase><phrase role="special">()</phrase></code>, | |
7135 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7136 | role="identifier">pop_wait_for</phrase><phrase role="special">()</phrase></code> | |
7137 | or <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7138 | role="identifier">pop_wait_until</phrase><phrase role="special">()</phrase></code> | |
7139 | and returns <code><phrase role="identifier">success</phrase></code>. | |
7140 | </para> | |
7141 | </listitem> | |
7142 | </varlistentry> | |
7143 | <varlistentry> | |
7144 | <term>Throws:</term> | |
7145 | <listitem> | |
7146 | <para> | |
7147 | Exceptions thrown by memory allocation and copying or moving <code><phrase | |
7148 | role="identifier">va</phrase></code>. | |
7149 | </para> | |
7150 | </listitem> | |
7151 | </varlistentry> | |
7152 | </variablelist> | |
7153 | <para> | |
7154 | <bridgehead renderas="sect4" id="unbounded_channel_pop_bridgehead"> | |
7155 | <phrase id="unbounded_channel_pop"/> | |
7156 | <link linkend="unbounded_channel_pop">Member | |
7157 | function <code>pop</code>()</link> | |
7158 | </bridgehead> | |
7159 | </para> | |
7160 | <programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7161 | </programlisting> | |
7162 | <variablelist> | |
7163 | <title></title> | |
7164 | <varlistentry> | |
7165 | <term>Effects:</term> | |
7166 | <listitem> | |
7167 | <para> | |
7168 | Dequeues a value from the channel. If the channel is empty, the fiber | |
7169 | gets suspended until at least one new item is <code><phrase role="identifier">push</phrase><phrase | |
7170 | role="special">()</phrase></code>ed (return value <code><phrase role="identifier">success</phrase></code> | |
7171 | and <code><phrase role="identifier">va</phrase></code> contains dequeued | |
7172 | value) or the channel gets <code><phrase role="identifier">close</phrase><phrase | |
7173 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>). | |
7174 | </para> | |
7175 | </listitem> | |
7176 | </varlistentry> | |
7177 | <varlistentry> | |
7178 | <term>Throws:</term> | |
7179 | <listitem> | |
7180 | <para> | |
7181 | Nothing | |
7182 | </para> | |
7183 | </listitem> | |
7184 | </varlistentry> | |
7185 | </variablelist> | |
7186 | <para> | |
7187 | <bridgehead renderas="sect4" id="unbounded_channel_value_pop_bridgehead"> | |
7188 | <phrase id="unbounded_channel_value_pop"/> | |
7189 | <link linkend="unbounded_channel_value_pop">Member | |
7190 | function <code>value_pop</code>()</link> | |
7191 | </bridgehead> | |
7192 | </para> | |
7193 | <programlisting><phrase role="identifier">value_type</phrase> <phrase role="identifier">value_pop</phrase><phrase role="special">();</phrase> | |
7194 | </programlisting> | |
7195 | <variablelist> | |
7196 | <title></title> | |
7197 | <varlistentry> | |
7198 | <term>Effects:</term> | |
7199 | <listitem> | |
7200 | <para> | |
7201 | Dequeues a value from the channel. If the channel is empty, the fiber | |
7202 | gets suspended until at least one new item is <code><phrase role="identifier">push</phrase><phrase | |
7203 | role="special">()</phrase></code>ed or the channel gets <code><phrase | |
7204 | role="identifier">close</phrase><phrase role="special">()</phrase></code>d | |
7205 | (which throws an exception). | |
7206 | </para> | |
7207 | </listitem> | |
7208 | </varlistentry> | |
7209 | <varlistentry> | |
7210 | <term>Throws:</term> | |
7211 | <listitem> | |
7212 | <para> | |
7213 | <code><phrase role="identifier">fiber_error</phrase></code> if <code><phrase | |
7214 | role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
7215 | is closed | |
7216 | </para> | |
7217 | </listitem> | |
7218 | </varlistentry> | |
7219 | <varlistentry> | |
7220 | <term>Error conditions:</term> | |
7221 | <listitem> | |
7222 | <para> | |
7223 | <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7224 | role="identifier">errc</phrase><phrase role="special">::</phrase><phrase | |
7225 | role="identifier">operation_not_permitted</phrase></code> | |
7226 | </para> | |
7227 | </listitem> | |
7228 | </varlistentry> | |
7229 | </variablelist> | |
7230 | <para> | |
7231 | <bridgehead renderas="sect4" id="unbounded_channel_try_pop_bridgehead"> | |
7232 | <phrase id="unbounded_channel_try_pop"/> | |
7233 | <link linkend="unbounded_channel_try_pop">Member | |
7234 | function <code>try_pop</code>()</link> | |
7235 | </bridgehead> | |
7236 | </para> | |
7237 | <programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7238 | </programlisting> | |
7239 | <variablelist> | |
7240 | <title></title> | |
7241 | <varlistentry> | |
7242 | <term>Effects:</term> | |
7243 | <listitem> | |
7244 | <para> | |
7245 | If channel is empty, returns <code><phrase role="identifier">empty</phrase></code>. | |
7246 | If channel is closed, returns <code><phrase role="identifier">closed</phrase></code>. | |
7247 | Otherwise it returns <code><phrase role="identifier">success</phrase></code> | |
7248 | and <code><phrase role="identifier">va</phrase></code> contains the | |
7249 | dequeued value. | |
7250 | </para> | |
7251 | </listitem> | |
7252 | </varlistentry> | |
7253 | <varlistentry> | |
7254 | <term>Throws:</term> | |
7255 | <listitem> | |
7256 | <para> | |
7257 | Exceptions thrown by copy- or move-operations. | |
7258 | </para> | |
7259 | </listitem> | |
7260 | </varlistentry> | |
7261 | </variablelist> | |
7262 | <para> | |
7263 | <bridgehead renderas="sect4" id="unbounded_channel_pop_wait_for_bridgehead"> | |
7264 | <phrase id="unbounded_channel_pop_wait_for"/> | |
7265 | <link linkend="unbounded_channel_pop_wait_for">Member | |
7266 | function <code>pop_wait_for</code>()</link> | |
7267 | </bridgehead> | |
7268 | </para> | |
7269 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
7270 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_for</phrase><phrase role="special">(</phrase> | |
7271 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7272 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> | |
7273 | </programlisting> | |
7274 | <variablelist> | |
7275 | <title></title> | |
7276 | <varlistentry> | |
7277 | <term>Effects:</term> | |
7278 | <listitem> | |
7279 | <para> | |
7280 | Accepts <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7281 | role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase | |
7282 | role="identifier">duration</phrase></code> and internally computes | |
7283 | a timeout time as (system time + <code><phrase role="identifier">timeout_duration</phrase></code>). | |
7284 | If channel is not empty, immediately dequeues a value from the channel. | |
7285 | Otherwise the fiber gets suspended until at least one new item is | |
7286 | <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>ed | |
7287 | (return value <code><phrase role="identifier">success</phrase></code> | |
7288 | and <code><phrase role="identifier">va</phrase></code> contains dequeued | |
7289 | value), or the channel gets <code><phrase role="identifier">close</phrase><phrase | |
7290 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>), | |
7291 | or the system time reaches the computed timeout time (return value | |
7292 | <code><phrase role="identifier">timeout</phrase></code>). | |
7293 | </para> | |
7294 | </listitem> | |
7295 | </varlistentry> | |
7296 | <varlistentry> | |
7297 | <term>Throws:</term> | |
7298 | <listitem> | |
7299 | <para> | |
7300 | timeout-related exceptions. | |
7301 | </para> | |
7302 | </listitem> | |
7303 | </varlistentry> | |
7304 | </variablelist> | |
7305 | <para> | |
7306 | <bridgehead renderas="sect4" id="unbounded_channel_pop_wait_until_bridgehead"> | |
7307 | <phrase id="unbounded_channel_pop_wait_until"/> | |
7308 | <link linkend="unbounded_channel_pop_wait_until">Member | |
7309 | function <code>pop_wait_until</code>()</link> | |
7310 | </bridgehead> | |
7311 | </para> | |
7312 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7313 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_until</phrase><phrase role="special">(</phrase> | |
7314 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7315 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> | |
7316 | </programlisting> | |
7317 | <variablelist> | |
7318 | <title></title> | |
7319 | <varlistentry> | |
7320 | <term>Effects:</term> | |
7321 | <listitem> | |
7322 | <para> | |
7323 | Accepts a <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7324 | role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase | |
7325 | role="identifier">time_point</phrase><phrase role="special"><</phrase> | |
7326 | <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> | |
7327 | <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase></code>. | |
7328 | If channel is not empty, immediately dequeues a value from the channel. | |
7329 | Otherwise the fiber gets suspended until at least one new item is | |
7330 | <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>ed | |
7331 | (return value <code><phrase role="identifier">success</phrase></code> | |
7332 | and <code><phrase role="identifier">va</phrase></code> contains dequeued | |
7333 | value), or the channel gets <code><phrase role="identifier">close</phrase><phrase | |
7334 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>), | |
7335 | or the system time reaches the passed <code><phrase role="identifier">time_point</phrase></code> | |
7336 | (return value <code><phrase role="identifier">timeout</phrase></code>). | |
7337 | </para> | |
7338 | </listitem> | |
7339 | </varlistentry> | |
7340 | <varlistentry> | |
7341 | <term>Throws:</term> | |
7342 | <listitem> | |
7343 | <para> | |
7344 | timeout-related exceptions. | |
7345 | </para> | |
7346 | </listitem> | |
7347 | </varlistentry> | |
7348 | </variablelist> | |
7349 | <para> | |
7350 | <bridgehead renderas="sect4" id="class_bounded_channel_bridgehead"> | |
7351 | <phrase id="class_bounded_channel"/> | |
7352 | <link linkend="class_bounded_channel">Template | |
7353 | <code>bounded_channel<></code></link> | |
7354 | </bridgehead> | |
7355 | </para> | |
7356 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">bounded_channel</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
7357 | ||
7358 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
7359 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
7360 | ||
7361 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="special">=</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase></code></ulink> <phrase role="special">></phrase> | |
7362 | <phrase role="keyword">class</phrase> <phrase role="identifier">bounded_channel</phrase> <phrase role="special">{</phrase> | |
7363 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
7364 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">value_type</phrase><phrase role="special">;</phrase> | |
7365 | ||
7366 | <phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">wm</phrase><phrase role="special">,</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase> <phrase role="special">=</phrase> <phrase role="identifier">Allocator</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
7367 | <phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">hwm</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lwm</phrase><phrase role="special">,</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase> <phrase role="special">=</phrase> <phrase role="identifier">Allocator</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
7368 | ||
7369 | <phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">bounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
7370 | <phrase role="identifier">bounded_channel</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">bounded_channel</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
7371 | ||
7372 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">upper_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7373 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lower_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7374 | ||
7375 | <phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7376 | ||
7377 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7378 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7379 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
7380 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_for</phrase><phrase role="special">(</phrase> | |
7381 | <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7382 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
7383 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7384 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
7385 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7386 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_until</phrase><phrase role="special">(</phrase> | |
7387 | <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7388 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
7389 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7390 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_until</phrase><phrase role="special">(</phrase> | |
7391 | <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7392 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
7393 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7394 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7395 | ||
7396 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7397 | <phrase role="identifier">value_type</phrase> <phrase role="identifier">value_pop</phrase><phrase role="special">();</phrase> | |
7398 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
7399 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_for</phrase><phrase role="special">(</phrase> | |
7400 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7401 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
7402 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7403 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_until</phrase><phrase role="special">(</phrase> | |
7404 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7405 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
7406 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7407 | <phrase role="special">};</phrase> | |
7408 | ||
7409 | <phrase role="special">}}</phrase> | |
7410 | </programlisting> | |
7411 | <bridgehead renderas="sect4" id="fiber.synchronization.channels.h7"> | |
7412 | <phrase id="fiber.synchronization.channels.constructor0"/><link linkend="fiber.synchronization.channels.constructor0">Constructor</link> | |
7413 | </bridgehead> | |
7414 | <programlisting><phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">wm</phrase><phrase role="special">,</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase> <phrase role="special">=</phrase> <phrase role="identifier">Allocator</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
7415 | <phrase role="identifier">bounded_channel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">hwm</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lwm</phrase><phrase role="special">,</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase> <phrase role="special">=</phrase> <phrase role="identifier">Allocator</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
7416 | </programlisting> | |
7417 | <variablelist> | |
7418 | <title></title> | |
7419 | <varlistentry> | |
7420 | <term>Preconditions:</term> | |
7421 | <listitem> | |
7422 | <para> | |
7423 | <code><phrase role="identifier">hwm</phrase> <phrase role="special">></phrase> | |
7424 | <phrase role="identifier">lwm</phrase></code> | |
7425 | </para> | |
7426 | </listitem> | |
7427 | </varlistentry> | |
7428 | <varlistentry> | |
7429 | <term>Effects:</term> | |
7430 | <listitem> | |
7431 | <para> | |
7432 | Constructs an object of class <code><phrase role="identifier">bounded_channel</phrase></code>. | |
7433 | The constructor with two arguments constructs an object of class <code><phrase | |
7434 | role="identifier">bounded_channel</phrase></code> with a high-watermark | |
7435 | of <code><phrase role="identifier">hwm</phrase></code> and a low-watermark | |
7436 | of <code><phrase role="identifier">lwm</phrase></code> items. The constructor | |
7437 | with one <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7438 | role="identifier">size_t</phrase></code> argument is effectively the | |
7439 | same as <code><phrase role="identifier">bounded_channel</phrase><phrase | |
7440 | role="special">(</phrase><phrase role="identifier">wm</phrase><phrase | |
7441 | role="special">,</phrase> <phrase role="special">(</phrase><phrase | |
7442 | role="identifier">wm</phrase><phrase role="special">-</phrase><phrase | |
7443 | role="number">1</phrase><phrase role="special">),</phrase> <phrase | |
7444 | role="identifier">alloc</phrase><phrase role="special">)</phrase></code>. | |
7445 | Internal nodes are allocated using <code><phrase role="identifier">alloc</phrase></code> | |
7446 | - C++11-allocators are supported. | |
7447 | </para> | |
7448 | </listitem> | |
7449 | </varlistentry> | |
7450 | <varlistentry> | |
7451 | <term>Throws:</term> | |
7452 | <listitem> | |
7453 | <para> | |
7454 | <code><phrase role="identifier">fiber_error</phrase></code> | |
7455 | </para> | |
7456 | </listitem> | |
7457 | </varlistentry> | |
7458 | <varlistentry> | |
7459 | <term>Error Conditions:</term> | |
7460 | <listitem> | |
7461 | <para> | |
7462 | <emphasis role="bold">invalid_argument</emphasis>: if <code><phrase | |
7463 | role="identifier">lwm</phrase> <phrase role="special">>=</phrase> | |
7464 | <phrase role="identifier">hwm</phrase></code>. | |
7465 | </para> | |
7466 | </listitem> | |
7467 | </varlistentry> | |
7468 | <varlistentry> | |
7469 | <term>Notes:</term> | |
7470 | <listitem> | |
7471 | <para> | |
7472 | Once the number of values in the channel reaches <code><phrase role="identifier">hwm</phrase></code>, | |
7473 | any call to <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>, | |
7474 | <code><phrase role="identifier">push_wait_for</phrase><phrase role="special">()</phrase></code> | |
7475 | or <code><phrase role="identifier">push_wait_until</phrase><phrase | |
7476 | role="special">()</phrase></code> will block until the number of values | |
7477 | in the channel is at most <code><phrase role="identifier">lwm</phrase></code>. | |
7478 | That is, if <code><phrase role="identifier">lwm</phrase> <phrase role="special"><</phrase> | |
7479 | <phrase role="special">(</phrase><phrase role="identifier">hwm</phrase><phrase | |
7480 | role="special">-</phrase><phrase role="number">1</phrase><phrase role="special">)</phrase></code>, | |
7481 | the channel can be in a state in which <code><phrase role="identifier">push</phrase><phrase | |
7482 | role="special">()</phrase></code>, <code><phrase role="identifier">push_wait_for</phrase><phrase | |
7483 | role="special">()</phrase></code> or <code><phrase role="identifier">push_wait_until</phrase><phrase | |
7484 | role="special">()</phrase></code> calls will block (channel is full) | |
7485 | even though the number of values in the channel is less than <code><phrase | |
7486 | role="identifier">hwm</phrase></code>. | |
7487 | </para> | |
7488 | </listitem> | |
7489 | </varlistentry> | |
7490 | <varlistentry> | |
7491 | <term>See also:</term> | |
7492 | <listitem> | |
7493 | <para> | |
7494 | <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase | |
7495 | role="identifier">Allocator</phrase></code></ulink> concept, <ulink | |
7496 | url="http://en.cppreference.com/w/cpp/memory/allocator"><code><phrase | |
7497 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7498 | role="identifier">allocator</phrase><phrase role="special"><</phrase> | |
7499 | <phrase role="identifier">T</phrase> <phrase role="special">></phrase></code></ulink> | |
7500 | </para> | |
7501 | </listitem> | |
7502 | </varlistentry> | |
7503 | </variablelist> | |
7504 | <para> | |
7505 | <bridgehead renderas="sect4" id="bounded_channel_upper_bound_bridgehead"> | |
7506 | <phrase id="bounded_channel_upper_bound"/> | |
7507 | <link linkend="bounded_channel_upper_bound">Member | |
7508 | function <code>upper_bound</code>()</link> | |
7509 | </bridgehead> | |
7510 | </para> | |
7511 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">upper_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7512 | </programlisting> | |
7513 | <variablelist> | |
7514 | <title></title> | |
7515 | <varlistentry> | |
7516 | <term>Returns:</term> | |
7517 | <listitem> | |
7518 | <para> | |
7519 | the high-watermark with which <code><phrase role="special">*</phrase><phrase | |
7520 | role="keyword">this</phrase></code> was constructed. | |
7521 | </para> | |
7522 | </listitem> | |
7523 | </varlistentry> | |
7524 | <varlistentry> | |
7525 | <term>Throws:</term> | |
7526 | <listitem> | |
7527 | <para> | |
7528 | Nothing. | |
7529 | </para> | |
7530 | </listitem> | |
7531 | </varlistentry> | |
7532 | </variablelist> | |
7533 | <para> | |
7534 | <bridgehead renderas="sect4" id="bounded_channel_lower_bound_bridgehead"> | |
7535 | <phrase id="bounded_channel_lower_bound"/> | |
7536 | <link linkend="bounded_channel_lower_bound">Member | |
7537 | function <code>lower_bound</code>()</link> | |
7538 | </bridgehead> | |
7539 | </para> | |
7540 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lower_bound</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7541 | </programlisting> | |
7542 | <variablelist> | |
7543 | <title></title> | |
7544 | <varlistentry> | |
7545 | <term>Returns:</term> | |
7546 | <listitem> | |
7547 | <para> | |
7548 | the low-watermark with which <code><phrase role="special">*</phrase><phrase | |
7549 | role="keyword">this</phrase></code> was constructed. | |
7550 | </para> | |
7551 | </listitem> | |
7552 | </varlistentry> | |
7553 | <varlistentry> | |
7554 | <term>Throws:</term> | |
7555 | <listitem> | |
7556 | <para> | |
7557 | Nothing. | |
7558 | </para> | |
7559 | </listitem> | |
7560 | </varlistentry> | |
7561 | </variablelist> | |
7562 | <para> | |
7563 | <bridgehead renderas="sect4" id="bounded_channel_close_bridgehead"> | |
7564 | <phrase id="bounded_channel_close"/> | |
7565 | <link linkend="bounded_channel_close">Member | |
7566 | function <code>close</code>()</link> | |
7567 | </bridgehead> | |
7568 | </para> | |
7569 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">close</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
7570 | </programlisting> | |
7571 | <variablelist> | |
7572 | <title></title> | |
7573 | <varlistentry> | |
7574 | <term>Effects:</term> | |
7575 | <listitem> | |
7576 | <para> | |
7577 | Deactivates the channel. No values can be put after calling <code><phrase | |
7578 | role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7579 | role="identifier">close</phrase><phrase role="special">()</phrase></code>. | |
7580 | Fibers blocked in <code><phrase role="keyword">this</phrase><phrase | |
7581 | role="special">-></phrase><phrase role="identifier">pop</phrase><phrase | |
7582 | role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase | |
7583 | role="special">-></phrase><phrase role="identifier">pop_wait_for</phrase><phrase | |
7584 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
7585 | role="special">-></phrase><phrase role="identifier">pop_wait_until</phrase><phrase | |
7586 | role="special">()</phrase></code> will return <code><phrase role="identifier">closed</phrase></code>. | |
7587 | Fibers blocked in <code><phrase role="keyword">this</phrase><phrase | |
7588 | role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase | |
7589 | role="special">()</phrase></code> will receive an exception. | |
7590 | </para> | |
7591 | </listitem> | |
7592 | </varlistentry> | |
7593 | <varlistentry> | |
7594 | <term>Throws:</term> | |
7595 | <listitem> | |
7596 | <para> | |
7597 | Nothing. | |
7598 | </para> | |
7599 | </listitem> | |
7600 | </varlistentry> | |
7601 | <varlistentry> | |
7602 | <term>Note:</term> | |
7603 | <listitem> | |
7604 | <para> | |
7605 | <code><phrase role="identifier">close</phrase><phrase role="special">()</phrase></code> | |
7606 | is like closing a pipe. It informs waiting consumers that no more values | |
7607 | will arrive. | |
7608 | </para> | |
7609 | </listitem> | |
7610 | </varlistentry> | |
7611 | </variablelist> | |
7612 | <para> | |
7613 | <bridgehead renderas="sect4" id="bounded_channel_push_bridgehead"> | |
7614 | <phrase id="bounded_channel_push"/> | |
7615 | <link linkend="bounded_channel_push">Member | |
7616 | function <code>push</code>()</link> | |
7617 | </bridgehead> | |
7618 | </para> | |
7619 | <programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7620 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7621 | </programlisting> | |
7622 | <variablelist> | |
7623 | <title></title> | |
7624 | <varlistentry> | |
7625 | <term>Effects:</term> | |
7626 | <listitem> | |
7627 | <para> | |
7628 | If channel is closed, returns <code><phrase role="identifier">closed</phrase></code>. | |
7629 | If channel is not full, enqueues the value in the channel, wakes up | |
7630 | a fiber blocked on <code><phrase role="keyword">this</phrase><phrase | |
7631 | role="special">-></phrase><phrase role="identifier">pop</phrase><phrase | |
7632 | role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase | |
7633 | role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase | |
7634 | role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase | |
7635 | role="special">-></phrase><phrase role="identifier">pop_wait_for</phrase><phrase | |
7636 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
7637 | role="special">-></phrase><phrase role="identifier">pop_wait_until</phrase><phrase | |
7638 | role="special">()</phrase></code> and returns <code><phrase role="identifier">success</phrase></code>. | |
7639 | Otherwise the calling fiber is suspended until the number of values | |
7640 | in the channel drops to <code><phrase role="identifier">lwm</phrase></code> | |
7641 | (return value <code><phrase role="identifier">success</phrase></code>)or | |
7642 | the channel is <code><phrase role="identifier">close</phrase><phrase | |
7643 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>). | |
7644 | </para> | |
7645 | </listitem> | |
7646 | </varlistentry> | |
7647 | <varlistentry> | |
7648 | <term>Throws:</term> | |
7649 | <listitem> | |
7650 | <para> | |
7651 | exceptions thrown by memory allocation and copying or moving <code><phrase | |
7652 | role="identifier">va</phrase></code>. | |
7653 | </para> | |
7654 | </listitem> | |
7655 | </varlistentry> | |
7656 | </variablelist> | |
7657 | <para> | |
7658 | <bridgehead renderas="sect4" id="bounded_channel_push_wait_for_bridgehead"> | |
7659 | <phrase id="bounded_channel_push_wait_for"/> | |
7660 | <link linkend="bounded_channel_push_wait_for">Member | |
7661 | function <code>push_wait_for</code>()</link> | |
7662 | </bridgehead> | |
7663 | </para> | |
7664 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
7665 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_for</phrase><phrase role="special">(</phrase> | |
7666 | <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7667 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
7668 | ||
7669 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
7670 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_for</phrase><phrase role="special">(</phrase> | |
7671 | <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7672 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">);</phrase> | |
7673 | </programlisting> | |
7674 | <variablelist> | |
7675 | <title></title> | |
7676 | <varlistentry> | |
7677 | <term>Effects:</term> | |
7678 | <listitem> | |
7679 | <para> | |
7680 | Accepts <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7681 | role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase | |
7682 | role="identifier">duration</phrase></code> and internally computes | |
7683 | a time_point as (system time + <code><phrase role="identifier">timeout_duration</phrase></code>). | |
7684 | If channel is closed, returns <code><phrase role="identifier">closed</phrase></code>. | |
7685 | If channel is not full, enqueues the value in the channel, wakes up | |
7686 | a fiber blocked on <code><phrase role="keyword">this</phrase><phrase | |
7687 | role="special">-></phrase><phrase role="identifier">pop</phrase><phrase | |
7688 | role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase | |
7689 | role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase | |
7690 | role="special">()</phrase></code>, <code><phrase role="keyword">this</phrase><phrase | |
7691 | role="special">-></phrase><phrase role="identifier">pop_wait_for</phrase><phrase | |
7692 | role="special">()</phrase></code> or <code><phrase role="keyword">this</phrase><phrase | |
7693 | role="special">-></phrase><phrase role="identifier">pop_wait_until</phrase><phrase | |
7694 | role="special">()</phrase></code> and returns <code><phrase role="identifier">success</phrase></code>. | |
7695 | Otherwise the calling fiber is suspended until the number of values | |
7696 | in the channel drops to <code><phrase role="identifier">lwm</phrase></code> | |
7697 | (return value <code><phrase role="identifier">success</phrase></code>), | |
7698 | the channel is <code><phrase role="identifier">close</phrase><phrase | |
7699 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>), | |
7700 | or the system time reaches the computed time_point (return value <code><phrase | |
7701 | role="identifier">timeout</phrase></code>). | |
7702 | </para> | |
7703 | </listitem> | |
7704 | </varlistentry> | |
7705 | <varlistentry> | |
7706 | <term>Throws:</term> | |
7707 | <listitem> | |
7708 | <para> | |
7709 | exceptions thrown by memory allocation and copying or moving <code><phrase | |
7710 | role="identifier">va</phrase></code> or timeout-related exceptions. | |
7711 | </para> | |
7712 | </listitem> | |
7713 | </varlistentry> | |
7714 | </variablelist> | |
7715 | <para> | |
7716 | <bridgehead renderas="sect4" id="bounded_channel_push_wait_until_bridgehead"> | |
7717 | <phrase id="bounded_channel_push_wait_until"/> | |
7718 | <link linkend="bounded_channel_push_wait_until">Member | |
7719 | function <code>push_wait_until</code>()</link> | |
7720 | </bridgehead> | |
7721 | </para> | |
7722 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7723 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_until</phrase><phrase role="special">(</phrase> | |
7724 | <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7725 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
7726 | ||
7727 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7728 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push_wait_until</phrase><phrase role="special">(</phrase> | |
7729 | <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7730 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">);</phrase> | |
7731 | </programlisting> | |
7732 | <variablelist> | |
7733 | <title></title> | |
7734 | <varlistentry> | |
7735 | <term>Effects:</term> | |
7736 | <listitem> | |
7737 | <para> | |
7738 | Accepts an absolute <code><phrase role="identifier">timeout_time</phrase></code> | |
7739 | in any supported time_point type. If channel is closed, returns <code><phrase | |
7740 | role="identifier">closed</phrase></code>. If channel is not full, enqueues | |
7741 | the value in the channel, wakes up a fiber blocked on <code><phrase | |
7742 | role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7743 | role="identifier">pop</phrase><phrase role="special">()</phrase></code>, | |
7744 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7745 | role="identifier">value_pop</phrase><phrase role="special">()</phrase></code>, | |
7746 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7747 | role="identifier">pop_wait_for</phrase><phrase role="special">()</phrase></code> | |
7748 | or <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7749 | role="identifier">pop_wait_until</phrase><phrase role="special">()</phrase></code> | |
7750 | and returns <code><phrase role="identifier">success</phrase></code>. | |
7751 | Otherwise the calling fiber is suspended until the number of values | |
7752 | in the channel drops to <code><phrase role="identifier">lwm</phrase></code> | |
7753 | (return value <code><phrase role="identifier">success</phrase></code>), | |
7754 | the channel is <code><phrase role="identifier">close</phrase><phrase | |
7755 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>), | |
7756 | or the system time reaches the passed time_point (return value <code><phrase | |
7757 | role="identifier">timeout</phrase></code>). | |
7758 | </para> | |
7759 | </listitem> | |
7760 | </varlistentry> | |
7761 | <varlistentry> | |
7762 | <term>Throws:</term> | |
7763 | <listitem> | |
7764 | <para> | |
7765 | exceptions thrown by memory allocation and copying or moving <code><phrase | |
7766 | role="identifier">va</phrase></code> or timeout-related exceptions. | |
7767 | </para> | |
7768 | </listitem> | |
7769 | </varlistentry> | |
7770 | </variablelist> | |
7771 | <para> | |
7772 | <bridgehead renderas="sect4" id="bounded_channel_try_push_bridgehead"> | |
7773 | <phrase id="bounded_channel_try_push"/> | |
7774 | <link linkend="bounded_channel_try_push">Member | |
7775 | function <code>try_push</code>()</link> | |
7776 | </bridgehead> | |
7777 | </para> | |
7778 | <programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7779 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_push</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7780 | </programlisting> | |
7781 | <variablelist> | |
7782 | <title></title> | |
7783 | <varlistentry> | |
7784 | <term>Effects:</term> | |
7785 | <listitem> | |
7786 | <para> | |
7787 | If channel is full, returns <code><phrase role="identifier">full</phrase></code>. | |
7788 | If channel is closed, returns <code><phrase role="identifier">closed</phrase></code>. | |
7789 | Otherwise enqueues the value in the channel, wakes up a fiber blocked | |
7790 | on <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7791 | role="identifier">pop</phrase><phrase role="special">()</phrase></code>, | |
7792 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7793 | role="identifier">value_pop</phrase><phrase role="special">()</phrase></code>, | |
7794 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7795 | role="identifier">pop_wait_for</phrase><phrase role="special">()</phrase></code> | |
7796 | or <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
7797 | role="identifier">pop_wait_until</phrase><phrase role="special">()</phrase></code> | |
7798 | and returns <code><phrase role="identifier">success</phrase></code>. | |
7799 | </para> | |
7800 | </listitem> | |
7801 | </varlistentry> | |
7802 | <varlistentry> | |
7803 | <term>Throws:</term> | |
7804 | <listitem> | |
7805 | <para> | |
7806 | Exceptions thrown by memory allocation and copying or moving <code><phrase | |
7807 | role="identifier">va</phrase></code>. | |
7808 | </para> | |
7809 | </listitem> | |
7810 | </varlistentry> | |
7811 | </variablelist> | |
7812 | <para> | |
7813 | <bridgehead renderas="sect4" id="bounded_channel_pop_bridgehead"> | |
7814 | <phrase id="bounded_channel_pop"/> | |
7815 | <link linkend="bounded_channel_pop">Member | |
7816 | function <code>pop</code>()</link> | |
7817 | </bridgehead> | |
7818 | </para> | |
7819 | <programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7820 | </programlisting> | |
7821 | <variablelist> | |
7822 | <title></title> | |
7823 | <varlistentry> | |
7824 | <term>Effects:</term> | |
7825 | <listitem> | |
7826 | <para> | |
7827 | Dequeues a value from the channel. If the channel is empty, the fiber | |
7828 | gets suspended until at least one new item is <code><phrase role="identifier">push</phrase><phrase | |
7829 | role="special">()</phrase></code>ed (return value <code><phrase role="identifier">success</phrase></code> | |
7830 | and <code><phrase role="identifier">va</phrase></code> contains dequeued | |
7831 | value) or the channel gets <code><phrase role="identifier">close</phrase><phrase | |
7832 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>). | |
7833 | Once the number of items remaining in the channel drops to <code><phrase | |
7834 | role="identifier">lwm</phrase></code>, any fibers blocked on <code><phrase | |
7835 | role="identifier">push</phrase><phrase role="special">()</phrase></code>, | |
7836 | <code><phrase role="identifier">push_wait_for</phrase><phrase role="special">()</phrase></code> | |
7837 | or <code><phrase role="identifier">push_wait_until</phrase><phrase | |
7838 | role="special">()</phrase></code> may resume. | |
7839 | </para> | |
7840 | </listitem> | |
7841 | </varlistentry> | |
7842 | <varlistentry> | |
7843 | <term>Throws:</term> | |
7844 | <listitem> | |
7845 | <para> | |
7846 | Nothing | |
7847 | </para> | |
7848 | </listitem> | |
7849 | </varlistentry> | |
7850 | </variablelist> | |
7851 | <para> | |
7852 | <bridgehead renderas="sect4" id="bounded_channel_value_pop_bridgehead"> | |
7853 | <phrase id="bounded_channel_value_pop"/> | |
7854 | <link linkend="bounded_channel_value_pop">Member | |
7855 | function <code>value_pop</code>()</link> | |
7856 | </bridgehead> | |
7857 | </para> | |
7858 | <programlisting><phrase role="identifier">value_type</phrase> <phrase role="identifier">value_pop</phrase><phrase role="special">();</phrase> | |
7859 | </programlisting> | |
7860 | <variablelist> | |
7861 | <title></title> | |
7862 | <varlistentry> | |
7863 | <term>Effects:</term> | |
7864 | <listitem> | |
7865 | <para> | |
7866 | Dequeues a value from the channel. If the channel is empty, the fiber | |
7867 | gets suspended until at least one new item is <code><phrase role="identifier">push</phrase><phrase | |
7868 | role="special">()</phrase></code>ed or the channel gets <code><phrase | |
7869 | role="identifier">close</phrase><phrase role="special">()</phrase></code>d | |
7870 | (which throws an exception). Once the number of items remaining in | |
7871 | the channel drops to <code><phrase role="identifier">lwm</phrase></code>, | |
7872 | any fibers blocked on <code><phrase role="identifier">push</phrase><phrase | |
7873 | role="special">()</phrase></code>, <code><phrase role="identifier">push_wait_for</phrase><phrase | |
7874 | role="special">()</phrase></code> or <code><phrase role="identifier">push_wait_until</phrase><phrase | |
7875 | role="special">()</phrase></code> may resume. | |
7876 | </para> | |
7877 | </listitem> | |
7878 | </varlistentry> | |
7879 | <varlistentry> | |
7880 | <term>Throws:</term> | |
7881 | <listitem> | |
7882 | <para> | |
7883 | <code><phrase role="identifier">fiber_error</phrase></code> if <code><phrase | |
7884 | role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
7885 | is closed | |
7886 | </para> | |
7887 | </listitem> | |
7888 | </varlistentry> | |
7889 | <varlistentry> | |
7890 | <term>Error conditions:</term> | |
7891 | <listitem> | |
7892 | <para> | |
7893 | <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7894 | role="identifier">errc</phrase><phrase role="special">::</phrase><phrase | |
7895 | role="identifier">operation_not_permitted</phrase></code> | |
7896 | </para> | |
7897 | </listitem> | |
7898 | </varlistentry> | |
7899 | </variablelist> | |
7900 | <para> | |
7901 | <bridgehead renderas="sect4" id="bounded_channel_try_pop_bridgehead"> | |
7902 | <phrase id="bounded_channel_try_pop"/> | |
7903 | <link linkend="bounded_channel_try_pop">Member | |
7904 | function <code>try_pop</code>()</link> | |
7905 | </bridgehead> | |
7906 | </para> | |
7907 | <programlisting><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">try_pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">);</phrase> | |
7908 | </programlisting> | |
7909 | <variablelist> | |
7910 | <title></title> | |
7911 | <varlistentry> | |
7912 | <term>Effects:</term> | |
7913 | <listitem> | |
7914 | <para> | |
7915 | If channel is empty, returns <code><phrase role="identifier">empty</phrase></code>. | |
7916 | If channel is closed, returns <code><phrase role="identifier">closed</phrase></code>. | |
7917 | Otherwise it returns <code><phrase role="identifier">success</phrase></code> | |
7918 | and <code><phrase role="identifier">va</phrase></code> contains the | |
7919 | dequeued value. Once the number of items remaining in the channel drops | |
7920 | to <code><phrase role="identifier">lwm</phrase></code>, any fibers | |
7921 | blocked on <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>, | |
7922 | <code><phrase role="identifier">push_wait_for</phrase><phrase role="special">()</phrase></code> | |
7923 | or <code><phrase role="identifier">push_wait_until</phrase><phrase | |
7924 | role="special">()</phrase></code> may resume. | |
7925 | </para> | |
7926 | </listitem> | |
7927 | </varlistentry> | |
7928 | <varlistentry> | |
7929 | <term>Throws:</term> | |
7930 | <listitem> | |
7931 | <para> | |
7932 | Exceptions thrown by copy- or move-operations. | |
7933 | </para> | |
7934 | </listitem> | |
7935 | </varlistentry> | |
7936 | </variablelist> | |
7937 | <para> | |
7938 | <bridgehead renderas="sect4" id="bounded_channel_pop_wait_for_bridgehead"> | |
7939 | <phrase id="bounded_channel_pop_wait_for"/> | |
7940 | <link linkend="bounded_channel_pop_wait_for">Member | |
7941 | function <code>pop_wait_for</code>()</link> | |
7942 | </bridgehead> | |
7943 | </para> | |
7944 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
7945 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_for</phrase><phrase role="special">(</phrase> | |
7946 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7947 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> | |
7948 | </programlisting> | |
7949 | <variablelist> | |
7950 | <title></title> | |
7951 | <varlistentry> | |
7952 | <term>Effects:</term> | |
7953 | <listitem> | |
7954 | <para> | |
7955 | Accepts <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
7956 | role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase | |
7957 | role="identifier">duration</phrase></code> and internally computes | |
7958 | a timeout time as (system time + <code><phrase role="identifier">timeout_duration</phrase></code>). | |
7959 | If channel is not empty, immediately dequeues a value from the channel. | |
7960 | Otherwise the fiber gets suspended until at least one new item is | |
7961 | <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>ed | |
7962 | (return value <code><phrase role="identifier">success</phrase></code> | |
7963 | and <code><phrase role="identifier">va</phrase></code> contains dequeued | |
7964 | value), or the channel gets <code><phrase role="identifier">close</phrase><phrase | |
7965 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>), | |
7966 | or the system time reaches the computed timeout time (return value | |
7967 | <code><phrase role="identifier">timeout</phrase></code>). Once the | |
7968 | number of items remaining in the channel drops to <code><phrase role="identifier">lwm</phrase></code>, | |
7969 | any fibers blocked on <code><phrase role="identifier">push</phrase><phrase | |
7970 | role="special">()</phrase></code>, <code><phrase role="identifier">push_wait_for</phrase><phrase | |
7971 | role="special">()</phrase></code> or <code><phrase role="identifier">push_wait_until</phrase><phrase | |
7972 | role="special">()</phrase></code> may resume. | |
7973 | </para> | |
7974 | </listitem> | |
7975 | </varlistentry> | |
7976 | <varlistentry> | |
7977 | <term>Throws:</term> | |
7978 | <listitem> | |
7979 | <para> | |
7980 | timeout-related exceptions. | |
7981 | </para> | |
7982 | </listitem> | |
7983 | </varlistentry> | |
7984 | </variablelist> | |
7985 | <para> | |
7986 | <bridgehead renderas="sect4" id="bounded_channel_pop_wait_until_bridgehead"> | |
7987 | <phrase id="bounded_channel_pop_wait_until"/> | |
7988 | <link linkend="bounded_channel_pop_wait_until">Member | |
7989 | function <code>pop_wait_until</code>()</link> | |
7990 | </bridgehead> | |
7991 | </para> | |
7992 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
7993 | <phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">pop_wait_until</phrase><phrase role="special">(</phrase> | |
7994 | <phrase role="identifier">value_type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">va</phrase><phrase role="special">,</phrase> | |
7995 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> | |
7996 | </programlisting> | |
7997 | <variablelist> | |
7998 | <title></title> | |
7999 | <varlistentry> | |
8000 | <term>Effects:</term> | |
8001 | <listitem> | |
8002 | <para> | |
8003 | Accepts a <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
8004 | role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase | |
8005 | role="identifier">time_point</phrase><phrase role="special"><</phrase> | |
8006 | <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> | |
8007 | <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase></code>. | |
8008 | If channel is not empty, immediately dequeues a value from the channel. | |
8009 | Otherwise the fiber gets suspended until at least one new item is | |
8010 | <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code>ed | |
8011 | (return value <code><phrase role="identifier">success</phrase></code> | |
8012 | and <code><phrase role="identifier">va</phrase></code> contains dequeued | |
8013 | value), or the channel gets <code><phrase role="identifier">close</phrase><phrase | |
8014 | role="special">()</phrase></code>d (return value <code><phrase role="identifier">closed</phrase></code>), | |
8015 | or the system time reaches the passed <code><phrase role="identifier">time_point</phrase></code> | |
8016 | (return value <code><phrase role="identifier">timeout</phrase></code>). | |
8017 | Once the number of items remaining in the channel drops to <code><phrase | |
8018 | role="identifier">lwm</phrase></code>, any fibers blocked on <code><phrase | |
8019 | role="identifier">push</phrase><phrase role="special">()</phrase></code>, | |
8020 | <code><phrase role="identifier">push_wait_for</phrase><phrase role="special">()</phrase></code> | |
8021 | or <code><phrase role="identifier">push_wait_until</phrase><phrase | |
8022 | role="special">()</phrase></code> may resume. | |
8023 | </para> | |
8024 | </listitem> | |
8025 | </varlistentry> | |
8026 | <varlistentry> | |
8027 | <term>Throws:</term> | |
8028 | <listitem> | |
8029 | <para> | |
8030 | timeout-related exceptions. | |
8031 | </para> | |
8032 | </listitem> | |
8033 | </varlistentry> | |
8034 | </variablelist> | |
8035 | </section> | |
8036 | <section id="fiber.synchronization.futures"> | |
8037 | <title><link linkend="fiber.synchronization.futures">Futures</link></title> | |
8038 | <bridgehead renderas="sect4" id="fiber.synchronization.futures.h0"> | |
8039 | <phrase id="fiber.synchronization.futures.overview"/><link linkend="fiber.synchronization.futures.overview">Overview</link> | |
8040 | </bridgehead> | |
8041 | <para> | |
8042 | The futures library provides a means of handling asynchronous future values, | |
8043 | whether those values are generated by another fiber, or on a single fiber | |
8044 | in response to external stimuli, or on-demand. | |
8045 | </para> | |
8046 | <para> | |
8047 | This is done through the provision of four class templates: <link linkend="class_future"><code>future<></code></link> and | |
8048 | <link linkend="class_shared_future"><code>shared_future<></code></link> which are used to retrieve the asynchronous | |
8049 | results, and <link linkend="class_promise"><code>promise<></code></link> and <link linkend="class_packaged_task"><code>packaged_task<></code></link> which | |
8050 | are used to generate the asynchronous results. | |
8051 | </para> | |
8052 | <para> | |
8053 | An instance of <link linkend="class_future"><code>future<></code></link> holds the one and only reference | |
8054 | to a result. Ownership can be transferred between instances using the move | |
8055 | constructor or move-assignment operator, but at most one instance holds a | |
8056 | reference to a given asynchronous result. When the result is ready, it is | |
8057 | returned from <link linkend="future_get"><code>future::get()</code></link> by rvalue-reference to allow the result | |
8058 | to be moved or copied as appropriate for the type. | |
8059 | </para> | |
8060 | <para> | |
8061 | On the other hand, many instances of <link linkend="class_shared_future"><code>shared_future<></code></link> may | |
8062 | reference the same result. Instances can be freely copied and assigned, and | |
8063 | <link linkend="shared_future_get"><code>shared_future::get()</code></link> | |
8064 | returns a <code><phrase role="keyword">const</phrase></code> | |
8065 | reference so that multiple calls to <link linkend="shared_future_get"><code>shared_future::get()</code></link> | |
8066 | are | |
8067 | safe. You can move an instance of <link linkend="class_future"><code>future<></code></link> into an instance | |
8068 | of <link linkend="class_shared_future"><code>shared_future<></code></link>, thus transferring ownership | |
8069 | of the associated asynchronous result, but not vice-versa. | |
8070 | </para> | |
8071 | <para> | |
8072 | <link linkend="fibers_async"><code>fibers::async()</code></link> is a simple way of running asynchronous tasks. | |
8073 | A call to <code><phrase role="identifier">async</phrase><phrase role="special">()</phrase></code> | |
8074 | spawns a fiber and returns a <link linkend="class_future"><code>future<></code></link> that will deliver | |
8075 | the result of the fiber function. | |
8076 | </para> | |
8077 | <bridgehead renderas="sect4" id="fiber.synchronization.futures.h1"> | |
8078 | <phrase id="fiber.synchronization.futures.creating_asynchronous_values"/><link | |
8079 | linkend="fiber.synchronization.futures.creating_asynchronous_values">Creating | |
8080 | asynchronous values</link> | |
8081 | </bridgehead> | |
8082 | <para> | |
8083 | You can set the value in a future with either a <link linkend="class_promise"><code>promise<></code></link> or | |
8084 | a <link linkend="class_packaged_task"><code>packaged_task<></code></link>. A <link linkend="class_packaged_task"><code>packaged_task<></code></link> is | |
8085 | a callable object with <code><phrase role="keyword">void</phrase></code> | |
8086 | return that wraps a function or callable object returning the specified type. | |
8087 | When the <link linkend="class_packaged_task"><code>packaged_task<></code></link> is invoked, it invokes the | |
8088 | contained function in turn, and populates a future with the contained function's | |
8089 | return value. This is an answer to the perennial question: <quote>How do | |
8090 | I return a value from a fiber?</quote> Package the function you wish to run | |
8091 | as a <link linkend="class_packaged_task"><code>packaged_task<></code></link> and pass the packaged task to | |
8092 | the fiber constructor. The future retrieved from the packaged task can then | |
8093 | be used to obtain the return value. If the function throws an exception, | |
8094 | that is stored in the future in place of the return value. | |
8095 | </para> | |
8096 | <programlisting><phrase role="keyword">int</phrase> <phrase role="identifier">calculate_the_answer_to_life_the_universe_and_everything</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
8097 | <phrase role="keyword">return</phrase> <phrase role="number">42</phrase><phrase role="special">;</phrase> | |
8098 | <phrase role="special">}</phrase> | |
8099 | ||
8100 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">()></phrase> <phrase role="identifier">pt</phrase><phrase role="special">(</phrase><phrase role="identifier">calculate_the_answer_to_life_the_universe_and_everything</phrase><phrase role="special">);</phrase> | |
8101 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">></phrase> <phrase role="identifier">fi</phrase><phrase role="special">=</phrase><phrase role="identifier">pt</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">();</phrase> | |
8102 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase><phrase role="identifier">pt</phrase><phrase role="special">)).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> <phrase role="comment">// launch task on a fiber</phrase> | |
8103 | ||
8104 | <phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> <phrase role="comment">// wait for it to finish</phrase> | |
8105 | ||
8106 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">is_ready</phrase><phrase role="special">());</phrase> | |
8107 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_value</phrase><phrase role="special">());</phrase> | |
8108 | <phrase role="identifier">assert</phrase><phrase role="special">(!</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_exception</phrase><phrase role="special">());</phrase> | |
8109 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()==</phrase><phrase role="number">42</phrase><phrase role="special">);</phrase> | |
8110 | </programlisting> | |
8111 | <para> | |
8112 | A <link linkend="class_promise"><code>promise<></code></link> is a bit more low level: it just provides explicit | |
8113 | functions to store a value or an exception in the associated future. A promise | |
8114 | can therefore be used where the value might come from more than one possible | |
8115 | source. | |
8116 | </para> | |
8117 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">></phrase> <phrase role="identifier">pi</phrase><phrase role="special">;</phrase> | |
8118 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase><phrase role="keyword">int</phrase><phrase role="special">></phrase> <phrase role="identifier">fi</phrase><phrase role="special">;</phrase> | |
8119 | <phrase role="identifier">fi</phrase><phrase role="special">=</phrase><phrase role="identifier">pi</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">();</phrase> | |
8120 | ||
8121 | <phrase role="identifier">pi</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase><phrase role="number">42</phrase><phrase role="special">);</phrase> | |
8122 | ||
8123 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">is_ready</phrase><phrase role="special">());</phrase> | |
8124 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_value</phrase><phrase role="special">());</phrase> | |
8125 | <phrase role="identifier">assert</phrase><phrase role="special">(!</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">has_exception</phrase><phrase role="special">());</phrase> | |
8126 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">fi</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()==</phrase><phrase role="number">42</phrase><phrase role="special">);</phrase> | |
8127 | </programlisting> | |
8128 | <section id="fiber.synchronization.futures.future"> | |
8129 | <title><link linkend="fiber.synchronization.futures.future">Future</link></title> | |
8130 | <para> | |
8131 | A future provides a mechanism to access the result of an asynchronous operation. | |
8132 | </para> | |
8133 | <anchor id="shared_state"/> | |
8134 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h0"> | |
8135 | <phrase id="fiber.synchronization.futures.future.shared_state"/><link linkend="fiber.synchronization.futures.future.shared_state">shared | |
8136 | state</link> | |
8137 | </bridgehead> | |
8138 | <para> | |
8139 | Behind a <link linkend="class_promise"><code>promise<></code></link> and its <link linkend="class_future"><code>future<></code></link> lies | |
8140 | an unspecified object called their <emphasis>shared state</emphasis>. The | |
8141 | shared state is what will actually hold the async result (or the exception). | |
8142 | </para> | |
8143 | <para> | |
8144 | The shared state is instantiated along with the <link linkend="class_promise"><code>promise<></code></link>. | |
8145 | </para> | |
8146 | <para> | |
8147 | Aside from its originating <code><phrase role="identifier">promise</phrase><phrase | |
8148 | role="special"><></phrase></code>, a <link linkend="class_future"><code>future<></code></link> holds | |
8149 | a unique reference to a particular shared state. However, multiple <link linkend="class_shared_future"><code>shared_future<></code></link> instances | |
8150 | can reference the same underlying shared state. | |
8151 | </para> | |
8152 | <para> | |
8153 | As <link linkend="class_packaged_task"><code>packaged_task<></code></link> and <link linkend="fibers_async"><code>fibers::async()</code></link> are | |
8154 | implemented using <link linkend="class_promise"><code>promise<></code></link>, discussions of shared state | |
8155 | apply to them as well. | |
8156 | </para> | |
8157 | <anchor id="class_future_status"/> | |
8158 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h1"> | |
8159 | <phrase id="fiber.synchronization.futures.future.enumeration__code__phrase_role__identifier__future_status__phrase___code_"/><link | |
8160 | linkend="fiber.synchronization.futures.future.enumeration__code__phrase_role__identifier__future_status__phrase___code_">Enumeration | |
8161 | <code><phrase role="identifier">future_status</phrase></code></link> | |
8162 | </bridgehead> | |
8163 | <para> | |
8164 | Timed wait-operations (<link linkend="future_wait_for"><code>future::wait_for()</code></link> and <link linkend="future_wait_until"><code>future::wait_until()</code></link>) | |
8165 | return the state of the future. | |
8166 | </para> | |
8167 | <programlisting><phrase role="keyword">enum</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">future_status</phrase> <phrase role="special">{</phrase> | |
8168 | <phrase role="identifier">ready</phrase><phrase role="special">,</phrase> | |
8169 | <phrase role="identifier">timeout</phrase><phrase role="special">,</phrase> | |
8170 | <phrase role="identifier">deferred</phrase> <phrase role="comment">// not supported yet</phrase> | |
8171 | <phrase role="special">};</phrase> | |
8172 | </programlisting> | |
8173 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h2"> | |
8174 | <phrase id="fiber.synchronization.futures.future._code__phrase_role__identifier__ready__phrase___code_"/><link | |
8175 | linkend="fiber.synchronization.futures.future._code__phrase_role__identifier__ready__phrase___code_"><code><phrase | |
8176 | role="identifier">ready</phrase></code></link> | |
8177 | </bridgehead> | |
8178 | <variablelist> | |
8179 | <title></title> | |
8180 | <varlistentry> | |
8181 | <term>Effects:</term> | |
8182 | <listitem> | |
8183 | <para> | |
8184 | The <link linkend="shared_state">shared state</link> is ready. | |
8185 | </para> | |
8186 | </listitem> | |
8187 | </varlistentry> | |
8188 | </variablelist> | |
8189 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h3"> | |
8190 | <phrase id="fiber.synchronization.futures.future._code__phrase_role__identifier__timeout__phrase___code_"/><link | |
8191 | linkend="fiber.synchronization.futures.future._code__phrase_role__identifier__timeout__phrase___code_"><code><phrase | |
8192 | role="identifier">timeout</phrase></code></link> | |
8193 | </bridgehead> | |
8194 | <variablelist> | |
8195 | <title></title> | |
8196 | <varlistentry> | |
8197 | <term>Effects:</term> | |
8198 | <listitem> | |
8199 | <para> | |
8200 | The <link linkend="shared_state">shared state</link> did not become | |
8201 | ready before timeout has passed. | |
8202 | </para> | |
8203 | </listitem> | |
8204 | </varlistentry> | |
8205 | </variablelist> | |
8206 | <note> | |
8207 | <para> | |
8208 | Deferred futures are not supported. | |
8209 | </para> | |
8210 | </note> | |
8211 | <para> | |
8212 | <bridgehead renderas="sect4" id="class_future_bridgehead"> | |
8213 | <phrase id="class_future"/> | |
8214 | <link linkend="class_future">Template <code>future<></code></link> | |
8215 | </bridgehead> | |
8216 | </para> | |
8217 | <para> | |
8218 | A <link linkend="class_future"><code>future<></code></link> contains a <link linkend="shared_state">shared | |
8219 | state</link> which is not shared with any other future. | |
8220 | </para> | |
8221 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
8222 | ||
8223 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
8224 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
8225 | ||
8226 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> | |
8227 | <phrase role="keyword">class</phrase> <phrase role="identifier">future</phrase> <phrase role="special">{</phrase> | |
8228 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
8229 | <phrase role="identifier">future</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8230 | ||
8231 | <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
8232 | ||
8233 | <phrase role="identifier">future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
8234 | ||
8235 | <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8236 | ||
8237 | <phrase role="identifier">future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8238 | ||
8239 | <phrase role="special">~</phrase><phrase role="identifier">future</phrase><phrase role="special">();</phrase> | |
8240 | ||
8241 | <phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8242 | ||
8243 | <phrase role="identifier">shared_future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">share</phrase><phrase role="special">();</phrase> | |
8244 | ||
8245 | <phrase role="identifier">R</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic future template</phrase> | |
8246 | <phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< R & > template specialization</phrase> | |
8247 | <phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< void > template specialization</phrase> | |
8248 | ||
8249 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase> | |
8250 | ||
8251 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8252 | ||
8253 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
8254 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> | |
8255 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8256 | ||
8257 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
8258 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> | |
8259 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8260 | <phrase role="special">};</phrase> | |
8261 | ||
8262 | <phrase role="special">}}</phrase> | |
8263 | </programlisting> | |
8264 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h4"> | |
8265 | <phrase id="fiber.synchronization.futures.future.default_constructor"/><link | |
8266 | linkend="fiber.synchronization.futures.future.default_constructor">Default | |
8267 | constructor</link> | |
8268 | </bridgehead> | |
8269 | <programlisting><phrase role="identifier">future</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8270 | </programlisting> | |
8271 | <variablelist> | |
8272 | <title></title> | |
8273 | <varlistentry> | |
8274 | <term>Effects:</term> | |
8275 | <listitem> | |
8276 | <para> | |
8277 | Creates a future with no <link linkend="shared_state">shared state</link>. | |
8278 | After construction <code><phrase role="keyword">false</phrase> <phrase | |
8279 | role="special">==</phrase> <phrase role="identifier">valid</phrase><phrase | |
8280 | role="special">()</phrase></code>. | |
8281 | </para> | |
8282 | </listitem> | |
8283 | </varlistentry> | |
8284 | <varlistentry> | |
8285 | <term>Throws:</term> | |
8286 | <listitem> | |
8287 | <para> | |
8288 | Nothing. | |
8289 | </para> | |
8290 | </listitem> | |
8291 | </varlistentry> | |
8292 | </variablelist> | |
8293 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h5"> | |
8294 | <phrase id="fiber.synchronization.futures.future.move_constructor"/><link | |
8295 | linkend="fiber.synchronization.futures.future.move_constructor">Move constructor</link> | |
8296 | </bridgehead> | |
8297 | <programlisting><phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8298 | </programlisting> | |
8299 | <variablelist> | |
8300 | <title></title> | |
8301 | <varlistentry> | |
8302 | <term>Effects:</term> | |
8303 | <listitem> | |
8304 | <para> | |
8305 | Constructs a future with the <link linkend="shared_state">shared | |
8306 | state</link> of other. After construction <code><phrase role="keyword">false</phrase> | |
8307 | <phrase role="special">==</phrase> <phrase role="identifier">other</phrase><phrase | |
8308 | role="special">.</phrase><phrase role="identifier">valid</phrase><phrase | |
8309 | role="special">()</phrase></code>. | |
8310 | </para> | |
8311 | </listitem> | |
8312 | </varlistentry> | |
8313 | <varlistentry> | |
8314 | <term>Throws:</term> | |
8315 | <listitem> | |
8316 | <para> | |
8317 | Nothing. | |
8318 | </para> | |
8319 | </listitem> | |
8320 | </varlistentry> | |
8321 | </variablelist> | |
8322 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h6"> | |
8323 | <phrase id="fiber.synchronization.futures.future.destructor"/><link linkend="fiber.synchronization.futures.future.destructor">Destructor</link> | |
8324 | </bridgehead> | |
8325 | <programlisting><phrase role="special">~</phrase><phrase role="identifier">future</phrase><phrase role="special">();</phrase> | |
8326 | </programlisting> | |
8327 | <variablelist> | |
8328 | <title></title> | |
8329 | <varlistentry> | |
8330 | <term>Effects:</term> | |
8331 | <listitem> | |
8332 | <para> | |
8333 | Destroys the future; ownership is abandoned. | |
8334 | </para> | |
8335 | </listitem> | |
8336 | </varlistentry> | |
8337 | <varlistentry> | |
8338 | <term>Note:</term> | |
8339 | <listitem> | |
8340 | <para> | |
8341 | <code>~future()</code> does <emphasis>not</emphasis> block the calling fiber. | |
8342 | </para> | |
8343 | </listitem> | |
8344 | </varlistentry> | |
8345 | </variablelist> | |
8346 | <para> | |
8347 | Consider a sequence such as: | |
8348 | </para> | |
8349 | <orderedlist> | |
8350 | <listitem> | |
8351 | <simpara> | |
8352 | instantiate <link linkend="class_promise"><code>promise<></code></link> | |
8353 | </simpara> | |
8354 | </listitem> | |
8355 | <listitem> | |
8356 | <simpara> | |
8357 | obtain its <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
8358 | via <link linkend="promise_get_future"><code>promise::get_future()</code></link> | |
8359 | </simpara> | |
8360 | </listitem> | |
8361 | <listitem> | |
8362 | <simpara> | |
8363 | launch <link linkend="class_fiber"><code>fiber</code></link>, capturing <code><phrase role="identifier">promise</phrase><phrase | |
8364 | role="special"><></phrase></code> | |
8365 | </simpara> | |
8366 | </listitem> | |
8367 | <listitem> | |
8368 | <simpara> | |
8369 | destroy <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
8370 | </simpara> | |
8371 | </listitem> | |
8372 | <listitem> | |
8373 | <simpara> | |
8374 | call <link linkend="promise_set_value"><code>promise::set_value()</code></link> | |
8375 | </simpara> | |
8376 | </listitem> | |
8377 | </orderedlist> | |
8378 | <para> | |
8379 | The final <code><phrase role="identifier">set_value</phrase><phrase role="special">()</phrase></code> | |
8380 | call succeeds, but the value is silently discarded: no additional <code><phrase | |
8381 | role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
8382 | can be obtained from that <code><phrase role="identifier">promise</phrase><phrase | |
8383 | role="special"><></phrase></code>. | |
8384 | </para> | |
8385 | <para> | |
8386 | <bridgehead renderas="sect4" id="future_operator_assign_bridgehead"> | |
8387 | <phrase id="future_operator_assign"/> | |
8388 | <link linkend="future_operator_assign">Member | |
8389 | function <code>operator=</code>()</link> | |
8390 | </bridgehead> | |
8391 | </para> | |
8392 | <programlisting><phrase role="identifier">future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8393 | </programlisting> | |
8394 | <variablelist> | |
8395 | <title></title> | |
8396 | <varlistentry> | |
8397 | <term>Effects:</term> | |
8398 | <listitem> | |
8399 | <para> | |
8400 | Moves the <link linkend="shared_state">shared state</link> of other | |
8401 | to <code><phrase role="keyword">this</phrase></code>. After the assignment, | |
8402 | <code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase> | |
8403 | <phrase role="identifier">other</phrase><phrase role="special">.</phrase><phrase | |
8404 | role="identifier">valid</phrase><phrase role="special">()</phrase></code>. | |
8405 | </para> | |
8406 | </listitem> | |
8407 | </varlistentry> | |
8408 | <varlistentry> | |
8409 | <term>Throws:</term> | |
8410 | <listitem> | |
8411 | <para> | |
8412 | Nothing. | |
8413 | </para> | |
8414 | </listitem> | |
8415 | </varlistentry> | |
8416 | </variablelist> | |
8417 | <para> | |
8418 | <bridgehead renderas="sect4" id="future_valid_bridgehead"> | |
8419 | <phrase id="future_valid"/> | |
8420 | <link linkend="future_valid">Member function <code>valid</code>()</link> | |
8421 | </bridgehead> | |
8422 | </para> | |
8423 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8424 | </programlisting> | |
8425 | <variablelist> | |
8426 | <title></title> | |
8427 | <varlistentry> | |
8428 | <term>Effects:</term> | |
8429 | <listitem> | |
8430 | <para> | |
8431 | Returns <code><phrase role="keyword">true</phrase></code> if future | |
8432 | contains a <link linkend="shared_state">shared state</link>. | |
8433 | </para> | |
8434 | </listitem> | |
8435 | </varlistentry> | |
8436 | <varlistentry> | |
8437 | <term>Throws:</term> | |
8438 | <listitem> | |
8439 | <para> | |
8440 | Nothing. | |
8441 | </para> | |
8442 | </listitem> | |
8443 | </varlistentry> | |
8444 | </variablelist> | |
8445 | <para> | |
8446 | <bridgehead renderas="sect4" id="future_share_bridgehead"> | |
8447 | <phrase id="future_share"/> | |
8448 | <link linkend="future_share">Member function <code>share</code>()</link> | |
8449 | </bridgehead> | |
8450 | </para> | |
8451 | <programlisting><phrase role="identifier">shared_future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">share</phrase><phrase role="special">();</phrase> | |
8452 | </programlisting> | |
8453 | <variablelist> | |
8454 | <title></title> | |
8455 | <varlistentry> | |
8456 | <term>Effects:</term> | |
8457 | <listitem> | |
8458 | <para> | |
8459 | Move the state to a <link linkend="class_shared_future"><code>shared_future<></code></link>. | |
8460 | </para> | |
8461 | </listitem> | |
8462 | </varlistentry> | |
8463 | <varlistentry> | |
8464 | <term>Returns:</term> | |
8465 | <listitem> | |
8466 | <para> | |
8467 | a <link linkend="class_shared_future"><code>shared_future<></code></link> containing the <link linkend="shared_state">shared | |
8468 | state</link> formerly belonging to <code><phrase role="special">*</phrase><phrase | |
8469 | role="keyword">this</phrase></code>. | |
8470 | </para> | |
8471 | </listitem> | |
8472 | </varlistentry> | |
8473 | <varlistentry> | |
8474 | <term>Postcondition:</term> | |
8475 | <listitem> | |
8476 | <para> | |
8477 | <code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase> | |
8478 | <phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code> | |
8479 | </para> | |
8480 | </listitem> | |
8481 | </varlistentry> | |
8482 | <varlistentry> | |
8483 | <term>Throws:</term> | |
8484 | <listitem> | |
8485 | <para> | |
8486 | <code><phrase role="identifier">future_error</phrase></code> with | |
8487 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
8488 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code>. | |
8489 | </para> | |
8490 | </listitem> | |
8491 | </varlistentry> | |
8492 | </variablelist> | |
8493 | <para> | |
8494 | <bridgehead renderas="sect4" id="future_get_bridgehead"> | |
8495 | <phrase id="future_get"/> | |
8496 | <link linkend="future_get">Member function <code>get</code>()</link> | |
8497 | </bridgehead> | |
8498 | </para> | |
8499 | <programlisting><phrase role="identifier">R</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic future template</phrase> | |
8500 | <phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< R & > template specialization</phrase> | |
8501 | <phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of future< void > template specialization</phrase> | |
8502 | </programlisting> | |
8503 | <variablelist> | |
8504 | <title></title> | |
8505 | <varlistentry> | |
8506 | <term>Precondition:</term> | |
8507 | <listitem> | |
8508 | <para> | |
8509 | <code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase> | |
8510 | <phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code> | |
8511 | </para> | |
8512 | </listitem> | |
8513 | </varlistentry> | |
8514 | <varlistentry> | |
8515 | <term>Returns:</term> | |
8516 | <listitem> | |
8517 | <para> | |
8518 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
8519 | called. If <link linkend="promise_set_value"><code>promise::set_value()</code></link> is called, returns | |
8520 | the value. If <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is called, | |
8521 | throws the indicated exception. | |
8522 | </para> | |
8523 | </listitem> | |
8524 | </varlistentry> | |
8525 | <varlistentry> | |
8526 | <term>Postcondition:</term> | |
8527 | <listitem> | |
8528 | <para> | |
8529 | <code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase> | |
8530 | <phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code> | |
8531 | </para> | |
8532 | </listitem> | |
8533 | </varlistentry> | |
8534 | <varlistentry> | |
8535 | <term>Throws:</term> | |
8536 | <listitem> | |
8537 | <para> | |
8538 | <code><phrase role="identifier">future_error</phrase></code> with | |
8539 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
8540 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code>, | |
8541 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
8542 | role="identifier">broken_promise</phrase></code>. Any exception passed | |
8543 | to <code><phrase role="identifier">promise</phrase><phrase role="special">::</phrase><phrase | |
8544 | role="identifier">set_exception</phrase><phrase role="special">()</phrase></code>. | |
8545 | </para> | |
8546 | </listitem> | |
8547 | </varlistentry> | |
8548 | </variablelist> | |
8549 | <para> | |
8550 | <bridgehead renderas="sect4" id="future_get_exception_ptr_bridgehead"> | |
8551 | <phrase id="future_get_exception_ptr"/> | |
8552 | <link linkend="future_get_exception_ptr">Member | |
8553 | function <code>get_exception_ptr</code>()</link> | |
8554 | </bridgehead> | |
8555 | </para> | |
8556 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase> | |
8557 | </programlisting> | |
8558 | <variablelist> | |
8559 | <title></title> | |
8560 | <varlistentry> | |
8561 | <term>Precondition:</term> | |
8562 | <listitem> | |
8563 | <para> | |
8564 | <code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase> | |
8565 | <phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code> | |
8566 | </para> | |
8567 | </listitem> | |
8568 | </varlistentry> | |
8569 | <varlistentry> | |
8570 | <term>Returns:</term> | |
8571 | <listitem> | |
8572 | <para> | |
8573 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
8574 | called. If <code><phrase role="identifier">set_value</phrase><phrase | |
8575 | role="special">()</phrase></code> is called, returns a default-constructed | |
8576 | <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
8577 | role="identifier">exception_ptr</phrase></code>. If <code><phrase | |
8578 | role="identifier">set_exception</phrase><phrase role="special">()</phrase></code> | |
8579 | is called, returns the passed <code><phrase role="identifier">std</phrase><phrase | |
8580 | role="special">::</phrase><phrase role="identifier">exception_ptr</phrase></code>. | |
8581 | </para> | |
8582 | </listitem> | |
8583 | </varlistentry> | |
8584 | <varlistentry> | |
8585 | <term>Throws:</term> | |
8586 | <listitem> | |
8587 | <para> | |
8588 | <code><phrase role="identifier">future_error</phrase></code> with | |
8589 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
8590 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code>. | |
8591 | </para> | |
8592 | </listitem> | |
8593 | </varlistentry> | |
8594 | <varlistentry> | |
8595 | <term>Note:</term> | |
8596 | <listitem> | |
8597 | <para> | |
8598 | <code><phrase role="identifier">get_exception_ptr</phrase><phrase | |
8599 | role="special">()</phrase></code> does <emphasis>not</emphasis> invalidate | |
8600 | the <code>future</code>. After calling <code><phrase role="identifier">get_exception_ptr</phrase><phrase | |
8601 | role="special">()</phrase></code>, you may still call <link linkend="future_get"><code>future::get()</code></link>. | |
8602 | </para> | |
8603 | </listitem> | |
8604 | </varlistentry> | |
8605 | </variablelist> | |
8606 | <para> | |
8607 | <bridgehead renderas="sect4" id="future_wait_bridgehead"> | |
8608 | <phrase id="future_wait"/> | |
8609 | <link linkend="future_wait">Member function <code>wait</code>()</link> | |
8610 | </bridgehead> | |
8611 | </para> | |
8612 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
8613 | </programlisting> | |
8614 | <variablelist> | |
8615 | <title></title> | |
8616 | <varlistentry> | |
8617 | <term>Effects:</term> | |
8618 | <listitem> | |
8619 | <para> | |
8620 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
8621 | called. | |
8622 | </para> | |
8623 | </listitem> | |
8624 | </varlistentry> | |
8625 | <varlistentry> | |
8626 | <term>Throws:</term> | |
8627 | <listitem> | |
8628 | <para> | |
8629 | <code><phrase role="identifier">future_error</phrase></code> with | |
8630 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
8631 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code>. | |
8632 | </para> | |
8633 | </listitem> | |
8634 | </varlistentry> | |
8635 | </variablelist> | |
8636 | <para> | |
8637 | <bridgehead renderas="sect4" id="future_wait_for_bridgehead"> | |
8638 | <phrase id="future_wait_for"/> | |
8639 | <link linkend="future_wait_for">Templated member | |
8640 | function <code>wait_for</code>()</link> | |
8641 | </bridgehead> | |
8642 | </para> | |
8643 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
8644 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8645 | </programlisting> | |
8646 | <variablelist> | |
8647 | <title></title> | |
8648 | <varlistentry> | |
8649 | <term>Effects:</term> | |
8650 | <listitem> | |
8651 | <para> | |
8652 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
8653 | called, or <code><phrase role="identifier">timeout_duration</phrase></code> | |
8654 | has passed. | |
8655 | </para> | |
8656 | </listitem> | |
8657 | </varlistentry> | |
8658 | <varlistentry> | |
8659 | <term>Result:</term> | |
8660 | <listitem> | |
8661 | <para> | |
8662 | A <code><phrase role="identifier">future_status</phrase></code> is | |
8663 | returned indicating the reason for returning. | |
8664 | </para> | |
8665 | </listitem> | |
8666 | </varlistentry> | |
8667 | <varlistentry> | |
8668 | <term>Throws:</term> | |
8669 | <listitem> | |
8670 | <para> | |
8671 | <code><phrase role="identifier">future_error</phrase></code> with | |
8672 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
8673 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code> | |
8674 | or timeout-related exceptions. | |
8675 | </para> | |
8676 | </listitem> | |
8677 | </varlistentry> | |
8678 | </variablelist> | |
8679 | <para> | |
8680 | <bridgehead renderas="sect4" id="future_wait_until_bridgehead"> | |
8681 | <phrase id="future_wait_until"/> | |
8682 | <link linkend="future_wait_until">Templated | |
8683 | member function <code>wait_until</code>()</link> | |
8684 | </bridgehead> | |
8685 | </para> | |
8686 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
8687 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8688 | </programlisting> | |
8689 | <variablelist> | |
8690 | <title></title> | |
8691 | <varlistentry> | |
8692 | <term>Effects:</term> | |
8693 | <listitem> | |
8694 | <para> | |
8695 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
8696 | called, or <code><phrase role="identifier">timeout_time</phrase></code> | |
8697 | has passed. | |
8698 | </para> | |
8699 | </listitem> | |
8700 | </varlistentry> | |
8701 | <varlistentry> | |
8702 | <term>Result:</term> | |
8703 | <listitem> | |
8704 | <para> | |
8705 | A <code><phrase role="identifier">future_status</phrase></code> is | |
8706 | returned indicating the reason for returning. | |
8707 | </para> | |
8708 | </listitem> | |
8709 | </varlistentry> | |
8710 | <varlistentry> | |
8711 | <term>Throws:</term> | |
8712 | <listitem> | |
8713 | <para> | |
8714 | <code><phrase role="identifier">future_error</phrase></code> with | |
8715 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
8716 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code> | |
8717 | or timeout-related exceptions. | |
8718 | </para> | |
8719 | </listitem> | |
8720 | </varlistentry> | |
8721 | </variablelist> | |
8722 | <para> | |
8723 | <bridgehead renderas="sect4" id="class_shared_future_bridgehead"> | |
8724 | <phrase id="class_shared_future"/> | |
8725 | <link linkend="class_shared_future">Template | |
8726 | <code>shared_future<></code></link> | |
8727 | </bridgehead> | |
8728 | </para> | |
8729 | <para> | |
8730 | A <link linkend="class_shared_future"><code>shared_future<></code></link> contains a <link linkend="shared_state">shared | |
8731 | state</link> which might be shared with other <link linkend="class_shared_future"><code>shared_future<></code></link> instances. | |
8732 | </para> | |
8733 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
8734 | ||
8735 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
8736 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
8737 | ||
8738 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> | |
8739 | <phrase role="keyword">class</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">{</phrase> | |
8740 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
8741 | <phrase role="identifier">shared_future</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8742 | ||
8743 | <phrase role="special">~</phrase><phrase role="identifier">shared_future</phrase><phrase role="special">();</phrase> | |
8744 | ||
8745 | <phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">);</phrase> | |
8746 | ||
8747 | <phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8748 | ||
8749 | <phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8750 | ||
8751 | <phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8752 | ||
8753 | <phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8754 | ||
8755 | <phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8756 | ||
8757 | <phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8758 | ||
8759 | <phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic shared_future template</phrase> | |
8760 | <phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< R & > template specialization</phrase> | |
8761 | <phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< void > template specialization</phrase> | |
8762 | ||
8763 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase> | |
8764 | ||
8765 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8766 | ||
8767 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
8768 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> | |
8769 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8770 | ||
8771 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
8772 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> | |
8773 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
8774 | <phrase role="special">};</phrase> | |
8775 | ||
8776 | <phrase role="special">}}</phrase> | |
8777 | </programlisting> | |
8778 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h7"> | |
8779 | <phrase id="fiber.synchronization.futures.future.default_constructor0"/><link | |
8780 | linkend="fiber.synchronization.futures.future.default_constructor0">Default | |
8781 | constructor</link> | |
8782 | </bridgehead> | |
8783 | <programlisting><phrase role="identifier">shared_future</phrase><phrase role="special">();</phrase> | |
8784 | </programlisting> | |
8785 | <variablelist> | |
8786 | <title></title> | |
8787 | <varlistentry> | |
8788 | <term>Effects:</term> | |
8789 | <listitem> | |
8790 | <para> | |
8791 | Creates a shared_future with no <link linkend="shared_state">shared | |
8792 | state</link>. After construction <code><phrase role="keyword">false</phrase> | |
8793 | <phrase role="special">==</phrase> <phrase role="identifier">valid</phrase><phrase | |
8794 | role="special">()</phrase></code>. | |
8795 | </para> | |
8796 | </listitem> | |
8797 | </varlistentry> | |
8798 | <varlistentry> | |
8799 | <term>Throws:</term> | |
8800 | <listitem> | |
8801 | <para> | |
8802 | Nothing. | |
8803 | </para> | |
8804 | </listitem> | |
8805 | </varlistentry> | |
8806 | </variablelist> | |
8807 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h8"> | |
8808 | <phrase id="fiber.synchronization.futures.future.move_constructor0"/><link | |
8809 | linkend="fiber.synchronization.futures.future.move_constructor0">Move constructor</link> | |
8810 | </bridgehead> | |
8811 | <programlisting><phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8812 | <phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8813 | </programlisting> | |
8814 | <variablelist> | |
8815 | <title></title> | |
8816 | <varlistentry> | |
8817 | <term>Effects:</term> | |
8818 | <listitem> | |
8819 | <para> | |
8820 | Constructs a shared_future with the <link linkend="shared_state">shared | |
8821 | state</link> of other. After construction <code><phrase role="keyword">false</phrase> | |
8822 | <phrase role="special">==</phrase> <phrase role="identifier">other</phrase><phrase | |
8823 | role="special">.</phrase><phrase role="identifier">valid</phrase><phrase | |
8824 | role="special">()</phrase></code>. | |
8825 | </para> | |
8826 | </listitem> | |
8827 | </varlistentry> | |
8828 | <varlistentry> | |
8829 | <term>Throws:</term> | |
8830 | <listitem> | |
8831 | <para> | |
8832 | Nothing. | |
8833 | </para> | |
8834 | </listitem> | |
8835 | </varlistentry> | |
8836 | </variablelist> | |
8837 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h9"> | |
8838 | <phrase id="fiber.synchronization.futures.future.copy_constructor"/><link | |
8839 | linkend="fiber.synchronization.futures.future.copy_constructor">Copy constructor</link> | |
8840 | </bridgehead> | |
8841 | <programlisting><phrase role="identifier">shared_future</phrase><phrase role="special">(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8842 | </programlisting> | |
8843 | <variablelist> | |
8844 | <title></title> | |
8845 | <varlistentry> | |
8846 | <term>Effects:</term> | |
8847 | <listitem> | |
8848 | <para> | |
8849 | Constructs a shared_future with the <link linkend="shared_state">shared | |
8850 | state</link> of other. After construction <code><phrase role="identifier">other</phrase><phrase | |
8851 | role="special">.</phrase><phrase role="identifier">valid</phrase><phrase | |
8852 | role="special">()</phrase></code> is unchanged. | |
8853 | </para> | |
8854 | </listitem> | |
8855 | </varlistentry> | |
8856 | <varlistentry> | |
8857 | <term>Throws:</term> | |
8858 | <listitem> | |
8859 | <para> | |
8860 | Nothing. | |
8861 | </para> | |
8862 | </listitem> | |
8863 | </varlistentry> | |
8864 | </variablelist> | |
8865 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.future.h10"> | |
8866 | <phrase id="fiber.synchronization.futures.future.destructor0"/><link linkend="fiber.synchronization.futures.future.destructor0">Destructor</link> | |
8867 | </bridgehead> | |
8868 | <programlisting><phrase role="special">~</phrase><phrase role="identifier">shared_future</phrase><phrase role="special">();</phrase> | |
8869 | </programlisting> | |
8870 | <variablelist> | |
8871 | <title></title> | |
8872 | <varlistentry> | |
8873 | <term>Effects:</term> | |
8874 | <listitem> | |
8875 | <para> | |
8876 | Destroys the shared_future; ownership is abandoned if not shared. | |
8877 | </para> | |
8878 | </listitem> | |
8879 | </varlistentry> | |
8880 | <varlistentry> | |
8881 | <term>Note:</term> | |
8882 | <listitem> | |
8883 | <para> | |
8884 | <code>~shared_future()</code> does <emphasis>not</emphasis> block the calling fiber. | |
8885 | </para> | |
8886 | </listitem> | |
8887 | </varlistentry> | |
8888 | </variablelist> | |
8889 | <para> | |
8890 | <bridgehead renderas="sect4" id="shared_future_operator_assign_bridgehead"> | |
8891 | <phrase id="shared_future_operator_assign"/> | |
8892 | <link linkend="shared_future_operator_assign">Member | |
8893 | function <code>operator=</code>()</link> | |
8894 | </bridgehead> | |
8895 | </para> | |
8896 | <programlisting><phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8897 | <phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8898 | <phrase role="identifier">shared_future</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">shared_future</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8899 | </programlisting> | |
8900 | <variablelist> | |
8901 | <title></title> | |
8902 | <varlistentry> | |
8903 | <term>Effects:</term> | |
8904 | <listitem> | |
8905 | <para> | |
8906 | Moves or copies the <link linkend="shared_state">shared state</link> | |
8907 | of other to <code><phrase role="keyword">this</phrase></code>. After | |
8908 | the assignment, the state of <code><phrase role="identifier">other</phrase><phrase | |
8909 | role="special">.</phrase><phrase role="identifier">valid</phrase><phrase | |
8910 | role="special">()</phrase></code> depends on which overload was invoked: | |
8911 | unchanged for the overload accepting <code><phrase role="identifier">shared_future</phrase> | |
8912 | <phrase role="keyword">const</phrase><phrase role="special">&</phrase></code>, | |
8913 | otherwise <code><phrase role="keyword">false</phrase></code>. | |
8914 | </para> | |
8915 | </listitem> | |
8916 | </varlistentry> | |
8917 | <varlistentry> | |
8918 | <term>Throws:</term> | |
8919 | <listitem> | |
8920 | <para> | |
8921 | Nothing. | |
8922 | </para> | |
8923 | </listitem> | |
8924 | </varlistentry> | |
8925 | </variablelist> | |
8926 | <para> | |
8927 | <bridgehead renderas="sect4" id="shared_future_valid_bridgehead"> | |
8928 | <phrase id="shared_future_valid"/> | |
8929 | <link linkend="shared_future_valid">Member | |
8930 | function <code>valid</code>()</link> | |
8931 | </bridgehead> | |
8932 | </para> | |
8933 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
8934 | </programlisting> | |
8935 | <variablelist> | |
8936 | <title></title> | |
8937 | <varlistentry> | |
8938 | <term>Effects:</term> | |
8939 | <listitem> | |
8940 | <para> | |
8941 | Returns <code><phrase role="keyword">true</phrase></code> if shared_future | |
8942 | contains a <link linkend="shared_state">shared state</link>. | |
8943 | </para> | |
8944 | </listitem> | |
8945 | </varlistentry> | |
8946 | <varlistentry> | |
8947 | <term>Throws:</term> | |
8948 | <listitem> | |
8949 | <para> | |
8950 | Nothing. | |
8951 | </para> | |
8952 | </listitem> | |
8953 | </varlistentry> | |
8954 | </variablelist> | |
8955 | <para> | |
8956 | <bridgehead renderas="sect4" id="shared_future_get_bridgehead"> | |
8957 | <phrase id="shared_future_get"/> | |
8958 | <link linkend="shared_future_get">Member function | |
8959 | <code>get</code>()</link> | |
8960 | </bridgehead> | |
8961 | </para> | |
8962 | <programlisting><phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of generic shared_future template</phrase> | |
8963 | <phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< R & > template specialization</phrase> | |
8964 | <phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of shared_future< void > template specialization</phrase> | |
8965 | </programlisting> | |
8966 | <variablelist> | |
8967 | <title></title> | |
8968 | <varlistentry> | |
8969 | <term>Precondition:</term> | |
8970 | <listitem> | |
8971 | <para> | |
8972 | <code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase> | |
8973 | <phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code> | |
8974 | </para> | |
8975 | </listitem> | |
8976 | </varlistentry> | |
8977 | <varlistentry> | |
8978 | <term>Returns:</term> | |
8979 | <listitem> | |
8980 | <para> | |
8981 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
8982 | called. If <link linkend="promise_set_value"><code>promise::set_value()</code></link> is called, returns | |
8983 | the value. If <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is called, | |
8984 | throws the indicated exception. | |
8985 | </para> | |
8986 | </listitem> | |
8987 | </varlistentry> | |
8988 | <varlistentry> | |
8989 | <term>Postcondition:</term> | |
8990 | <listitem> | |
8991 | <para> | |
8992 | <code><phrase role="keyword">false</phrase> <phrase role="special">==</phrase> | |
8993 | <phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code> | |
8994 | </para> | |
8995 | </listitem> | |
8996 | </varlistentry> | |
8997 | <varlistentry> | |
8998 | <term>Throws:</term> | |
8999 | <listitem> | |
9000 | <para> | |
9001 | <code><phrase role="identifier">future_error</phrase></code> with | |
9002 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
9003 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code>, | |
9004 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
9005 | role="identifier">broken_promise</phrase></code>. Any exception passed | |
9006 | to <code><phrase role="identifier">promise</phrase><phrase role="special">::</phrase><phrase | |
9007 | role="identifier">set_exception</phrase><phrase role="special">()</phrase></code>. | |
9008 | </para> | |
9009 | </listitem> | |
9010 | </varlistentry> | |
9011 | </variablelist> | |
9012 | <para> | |
9013 | <bridgehead renderas="sect4" id="shared_future_get_exception_ptr_bridgehead"> | |
9014 | <phrase id="shared_future_get_exception_ptr"/> | |
9015 | <link linkend="shared_future_get_exception_ptr">Member | |
9016 | function <code>get_exception_ptr</code>()</link> | |
9017 | </bridgehead> | |
9018 | </para> | |
9019 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase> | |
9020 | </programlisting> | |
9021 | <variablelist> | |
9022 | <title></title> | |
9023 | <varlistentry> | |
9024 | <term>Precondition:</term> | |
9025 | <listitem> | |
9026 | <para> | |
9027 | <code><phrase role="keyword">true</phrase> <phrase role="special">==</phrase> | |
9028 | <phrase role="identifier">valid</phrase><phrase role="special">()</phrase></code> | |
9029 | </para> | |
9030 | </listitem> | |
9031 | </varlistentry> | |
9032 | <varlistentry> | |
9033 | <term>Returns:</term> | |
9034 | <listitem> | |
9035 | <para> | |
9036 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
9037 | called. If <code><phrase role="identifier">set_value</phrase><phrase | |
9038 | role="special">()</phrase></code> is called, returns a default-constructed | |
9039 | <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
9040 | role="identifier">exception_ptr</phrase></code>. If <code><phrase | |
9041 | role="identifier">set_exception</phrase><phrase role="special">()</phrase></code> | |
9042 | is called, returns the passed <code><phrase role="identifier">std</phrase><phrase | |
9043 | role="special">::</phrase><phrase role="identifier">exception_ptr</phrase></code>. | |
9044 | </para> | |
9045 | </listitem> | |
9046 | </varlistentry> | |
9047 | <varlistentry> | |
9048 | <term>Throws:</term> | |
9049 | <listitem> | |
9050 | <para> | |
9051 | <code><phrase role="identifier">future_error</phrase></code> with | |
9052 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
9053 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code>. | |
9054 | </para> | |
9055 | </listitem> | |
9056 | </varlistentry> | |
9057 | <varlistentry> | |
9058 | <term>Note:</term> | |
9059 | <listitem> | |
9060 | <para> | |
9061 | <code><phrase role="identifier">get_exception_ptr</phrase><phrase | |
9062 | role="special">()</phrase></code> does <emphasis>not</emphasis> invalidate | |
9063 | the <code>shared_future</code>. After calling <code><phrase role="identifier">get_exception_ptr</phrase><phrase | |
9064 | role="special">()</phrase></code>, you may still call <link linkend="shared_future_get"><code>shared_future::get()</code></link>. | |
9065 | </para> | |
9066 | </listitem> | |
9067 | </varlistentry> | |
9068 | </variablelist> | |
9069 | <para> | |
9070 | <bridgehead renderas="sect4" id="shared_future_wait_bridgehead"> | |
9071 | <phrase id="shared_future_wait"/> | |
9072 | <link linkend="shared_future_wait">Member | |
9073 | function <code>wait</code>()</link> | |
9074 | </bridgehead> | |
9075 | </para> | |
9076 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
9077 | </programlisting> | |
9078 | <variablelist> | |
9079 | <title></title> | |
9080 | <varlistentry> | |
9081 | <term>Effects:</term> | |
9082 | <listitem> | |
9083 | <para> | |
9084 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
9085 | called. | |
9086 | </para> | |
9087 | </listitem> | |
9088 | </varlistentry> | |
9089 | <varlistentry> | |
9090 | <term>Throws:</term> | |
9091 | <listitem> | |
9092 | <para> | |
9093 | <code><phrase role="identifier">future_error</phrase></code> with | |
9094 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
9095 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code>. | |
9096 | </para> | |
9097 | </listitem> | |
9098 | </varlistentry> | |
9099 | </variablelist> | |
9100 | <para> | |
9101 | <bridgehead renderas="sect4" id="shared_future_wait_for_bridgehead"> | |
9102 | <phrase id="shared_future_wait_for"/> | |
9103 | <link linkend="shared_future_wait_for">Templated | |
9104 | member function <code>wait_for</code>()</link> | |
9105 | </bridgehead> | |
9106 | </para> | |
9107 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> | |
9108 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">duration</phrase><phrase role="special"><</phrase> <phrase role="identifier">Rep</phrase><phrase role="special">,</phrase> <phrase role="identifier">Period</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_duration</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
9109 | </programlisting> | |
9110 | <variablelist> | |
9111 | <title></title> | |
9112 | <varlistentry> | |
9113 | <term>Effects:</term> | |
9114 | <listitem> | |
9115 | <para> | |
9116 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
9117 | called, or <code><phrase role="identifier">timeout_duration</phrase></code> | |
9118 | has passed. | |
9119 | </para> | |
9120 | </listitem> | |
9121 | </varlistentry> | |
9122 | <varlistentry> | |
9123 | <term>Result:</term> | |
9124 | <listitem> | |
9125 | <para> | |
9126 | A <code><phrase role="identifier">future_status</phrase></code> is | |
9127 | returned indicating the reason for returning. | |
9128 | </para> | |
9129 | </listitem> | |
9130 | </varlistentry> | |
9131 | <varlistentry> | |
9132 | <term>Throws:</term> | |
9133 | <listitem> | |
9134 | <para> | |
9135 | <code><phrase role="identifier">future_error</phrase></code> with | |
9136 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
9137 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code> | |
9138 | or timeout-related exceptions. | |
9139 | </para> | |
9140 | </listitem> | |
9141 | </varlistentry> | |
9142 | </variablelist> | |
9143 | <para> | |
9144 | <bridgehead renderas="sect4" id="shared_future_wait_until_bridgehead"> | |
9145 | <phrase id="shared_future_wait_until"/> | |
9146 | <link linkend="shared_future_wait_until">Templated | |
9147 | member function <code>wait_until</code>()</link> | |
9148 | </bridgehead> | |
9149 | </para> | |
9150 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> | |
9151 | <phrase role="identifier">future_status</phrase> <phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special"><</phrase> <phrase role="identifier">Clock</phrase><phrase role="special">,</phrase> <phrase role="identifier">Duration</phrase> <phrase role="special">></phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">timeout_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase><phrase role="special">;</phrase> | |
9152 | </programlisting> | |
9153 | <variablelist> | |
9154 | <title></title> | |
9155 | <varlistentry> | |
9156 | <term>Effects:</term> | |
9157 | <listitem> | |
9158 | <para> | |
9159 | Waits until <link linkend="promise_set_value"><code>promise::set_value()</code></link> or <link linkend="promise_set_exception"><code>promise::set_exception()</code></link> is | |
9160 | called, or <code><phrase role="identifier">timeout_time</phrase></code> | |
9161 | has passed. | |
9162 | </para> | |
9163 | </listitem> | |
9164 | </varlistentry> | |
9165 | <varlistentry> | |
9166 | <term>Result:</term> | |
9167 | <listitem> | |
9168 | <para> | |
9169 | A <code><phrase role="identifier">future_status</phrase></code> is | |
9170 | returned indicating the reason for returning. | |
9171 | </para> | |
9172 | </listitem> | |
9173 | </varlistentry> | |
9174 | <varlistentry> | |
9175 | <term>Throws:</term> | |
9176 | <listitem> | |
9177 | <para> | |
9178 | <code><phrase role="identifier">future_error</phrase></code> with | |
9179 | error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
9180 | role="special">::</phrase><phrase role="identifier">no_state</phrase></code> | |
9181 | or timeout-related exceptions. | |
9182 | </para> | |
9183 | </listitem> | |
9184 | </varlistentry> | |
9185 | </variablelist> | |
9186 | <para> | |
9187 | <bridgehead renderas="sect4" id="fibers_async_bridgehead"> | |
9188 | <phrase id="fibers_async"/> | |
9189 | <link linkend="fibers_async">Non-member function <code>fibers::async()</code></link> | |
9190 | </bridgehead> | |
9191 | </para> | |
9192 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">/</phrase><phrase role="identifier">async</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
9193 | ||
9194 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
9195 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
9196 | ||
9197 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Function</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
9198 | <phrase role="identifier">future</phrase><phrase role="special"><</phrase> | |
9199 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of_t</phrase><phrase role="special"><</phrase> | |
9200 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Function</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> | |
9201 | <phrase role="special">></phrase> | |
9202 | <phrase role="special">></phrase> | |
9203 | <phrase role="identifier">async</phrase><phrase role="special">(</phrase> <phrase role="identifier">Function</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
9204 | ||
9205 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Function</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
9206 | <phrase role="identifier">future</phrase><phrase role="special"><</phrase> | |
9207 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of_t</phrase><phrase role="special"><</phrase> | |
9208 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Function</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> | |
9209 | <phrase role="special">></phrase> | |
9210 | <phrase role="special">></phrase> | |
9211 | <phrase role="identifier">async</phrase><phrase role="special">(</phrase> <link linkend="class_launch"><code><phrase role="identifier">launch</phrase></code></link> <phrase role="identifier">policy</phrase><phrase role="special">,</phrase> <phrase role="identifier">Function</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
9212 | ||
9213 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">Function</phrase><phrase role="special">,</phrase> <phrase role="keyword">class</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
9214 | <phrase role="identifier">future</phrase><phrase role="special"><</phrase> | |
9215 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of_t</phrase><phrase role="special"><</phrase> | |
9216 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Function</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> | |
9217 | <phrase role="special">></phrase> | |
9218 | <phrase role="special">></phrase> | |
9219 | <phrase role="identifier">async</phrase><phrase role="special">(</phrase> <link linkend="class_launch"><code><phrase role="identifier">launch</phrase></code></link> <phrase role="identifier">policy</phrase><phrase role="special">,</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link> <phrase role="identifier">salloc</phrase><phrase role="special">,</phrase> | |
9220 | <phrase role="identifier">Function</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">,</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
9221 | ||
9222 | <phrase role="special">}}</phrase> | |
9223 | </programlisting> | |
9224 | <variablelist> | |
9225 | <title></title> | |
9226 | <varlistentry> | |
9227 | <term>Effects:</term> | |
9228 | <listitem> | |
9229 | <para> | |
9230 | Executes <code><phrase role="identifier">fn</phrase></code> in a | |
9231 | <link linkend="class_fiber"><code>fiber</code></link> and returns an associated <link linkend="class_future"><code>future<></code></link>. | |
9232 | </para> | |
9233 | </listitem> | |
9234 | </varlistentry> | |
9235 | <varlistentry> | |
9236 | <term>Result:</term> | |
9237 | <listitem> | |
9238 | <para> | |
9239 | <programlisting><phrase role="identifier">future</phrase><phrase role="special"><</phrase> | |
9240 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of_t</phrase><phrase role="special"><</phrase> | |
9241 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Function</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay_t</phrase><phrase role="special"><</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> | |
9242 | <phrase role="special">></phrase> | |
9243 | <phrase role="special">></phrase></programlisting> | |
9244 | representing the <link linkend="shared_state">shared state</link> | |
9245 | associated with the asynchronous execution of <code><phrase role="identifier">fn</phrase></code>. | |
9246 | </para> | |
9247 | </listitem> | |
9248 | </varlistentry> | |
9249 | <varlistentry> | |
9250 | <term>Throws:</term> | |
9251 | <listitem> | |
9252 | <para> | |
9253 | <code><phrase role="identifier">fiber_error</phrase></code> or <code><phrase | |
9254 | role="identifier">future_error</phrase></code> if an error occurs. | |
9255 | </para> | |
9256 | </listitem> | |
9257 | </varlistentry> | |
9258 | <varlistentry> | |
9259 | <term>Notes:</term> | |
9260 | <listitem> | |
9261 | <para> | |
9262 | The overloads accepting <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase | |
9263 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
9264 | role="identifier">allocator_arg_t</phrase></code></ulink> use the | |
9265 | passed <link linkend="stack_allocator_concept"><code><phrase role="identifier">StackAllocator</phrase></code></link> | |
9266 | when constructing the launched <code><phrase role="identifier">fiber</phrase></code>. | |
9267 | The overloads accepting <link linkend="class_launch"><code>launch</code></link> use the passed <code><phrase | |
9268 | role="identifier">launch</phrase></code> when constructing the launched | |
9269 | <code><phrase role="identifier">fiber</phrase></code>. The default | |
9270 | <code><phrase role="identifier">launch</phrase></code> is <code><phrase | |
9271 | role="identifier">post</phrase></code>, as for the <code><phrase | |
9272 | role="identifier">fiber</phrase></code> constructor. | |
9273 | </para> | |
9274 | </listitem> | |
9275 | </varlistentry> | |
9276 | </variablelist> | |
9277 | <note> | |
9278 | <para> | |
9279 | Deferred futures are not supported. | |
9280 | </para> | |
9281 | </note> | |
9282 | </section> | |
9283 | <section id="fiber.synchronization.futures.promise"> | |
9284 | <title><anchor id="class_promise"/><link linkend="fiber.synchronization.futures.promise">Template | |
9285 | <code><phrase role="identifier">promise</phrase><phrase role="special"><></phrase></code></link></title> | |
9286 | <para> | |
9287 | A <link linkend="class_promise"><code>promise<></code></link> provides a mechanism to store a value (or | |
9288 | exception) that can later be retrieved from the corresponding <link linkend="class_future"><code>future<></code></link> object. | |
9289 | <code><phrase role="identifier">promise</phrase><phrase role="special"><></phrase></code> | |
9290 | and <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
9291 | communicate via their underlying <link linkend="shared_state">shared state</link>. | |
9292 | </para> | |
9293 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">/</phrase><phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
9294 | ||
9295 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
9296 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
9297 | ||
9298 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> | |
9299 | <phrase role="keyword">class</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">{</phrase> | |
9300 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
9301 | <phrase role="identifier">promise</phrase><phrase role="special">();</phrase> | |
9302 | ||
9303 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="special">></phrase> | |
9304 | <phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase><phrase role="special">);</phrase> | |
9305 | ||
9306 | <phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9307 | ||
9308 | <phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9309 | ||
9310 | <phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
9311 | ||
9312 | <phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">promise</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
9313 | ||
9314 | <phrase role="special">~</phrase><phrase role="identifier">promise</phrase><phrase role="special">();</phrase> | |
9315 | ||
9316 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9317 | ||
9318 | <phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase> | |
9319 | ||
9320 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&);</phrase> <phrase role="comment">// member only of generic promise template</phrase> | |
9321 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="special">&&);</phrase> <phrase role="comment">// member only of generic promise template</phrase> | |
9322 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="special">&);</phrase> <phrase role="comment">// member only of promise< R & > template</phrase> | |
9323 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of promise< void > template</phrase> | |
9324 | ||
9325 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_exception</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">p</phrase><phrase role="special">);</phrase> | |
9326 | <phrase role="special">};</phrase> | |
9327 | ||
9328 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> | |
9329 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&,</phrase> <phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9330 | ||
9331 | <phrase role="special">}</phrase> | |
9332 | </programlisting> | |
9333 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h0"> | |
9334 | <phrase id="fiber.synchronization.futures.promise.default_constructor"/><link | |
9335 | linkend="fiber.synchronization.futures.promise.default_constructor">Default | |
9336 | constructor</link> | |
9337 | </bridgehead> | |
9338 | <programlisting><phrase role="identifier">promise</phrase><phrase role="special">();</phrase> | |
9339 | </programlisting> | |
9340 | <variablelist> | |
9341 | <title></title> | |
9342 | <varlistentry> | |
9343 | <term>Effects:</term> | |
9344 | <listitem> | |
9345 | <para> | |
9346 | Creates a promise with an empty <link linkend="shared_state">shared | |
9347 | state</link>. | |
9348 | </para> | |
9349 | </listitem> | |
9350 | </varlistentry> | |
9351 | <varlistentry> | |
9352 | <term>Throws:</term> | |
9353 | <listitem> | |
9354 | <para> | |
9355 | Exceptions caused by memory allocation. | |
9356 | </para> | |
9357 | </listitem> | |
9358 | </varlistentry> | |
9359 | </variablelist> | |
9360 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h1"> | |
9361 | <phrase id="fiber.synchronization.futures.promise.constructor"/><link linkend="fiber.synchronization.futures.promise.constructor">Constructor</link> | |
9362 | </bridgehead> | |
9363 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="special">></phrase> | |
9364 | <phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="identifier">alloc</phrase><phrase role="special">);</phrase> | |
9365 | </programlisting> | |
9366 | <variablelist> | |
9367 | <title></title> | |
9368 | <varlistentry> | |
9369 | <term>Effects:</term> | |
9370 | <listitem> | |
9371 | <para> | |
9372 | Creates a promise with an empty <link linkend="shared_state">shared | |
9373 | state</link> by using <code><phrase role="identifier">alloc</phrase></code>. | |
9374 | </para> | |
9375 | </listitem> | |
9376 | </varlistentry> | |
9377 | <varlistentry> | |
9378 | <term>Throws:</term> | |
9379 | <listitem> | |
9380 | <para> | |
9381 | Exceptions caused by memory allocation. | |
9382 | </para> | |
9383 | </listitem> | |
9384 | </varlistentry> | |
9385 | <varlistentry> | |
9386 | <term>See also:</term> | |
9387 | <listitem> | |
9388 | <para> | |
9389 | <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase | |
9390 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
9391 | role="identifier">allocator_arg_t</phrase></code></ulink> | |
9392 | </para> | |
9393 | </listitem> | |
9394 | </varlistentry> | |
9395 | </variablelist> | |
9396 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h2"> | |
9397 | <phrase id="fiber.synchronization.futures.promise.move_constructor"/><link | |
9398 | linkend="fiber.synchronization.futures.promise.move_constructor">Move constructor</link> | |
9399 | </bridgehead> | |
9400 | <programlisting><phrase role="identifier">promise</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9401 | </programlisting> | |
9402 | <variablelist> | |
9403 | <title></title> | |
9404 | <varlistentry> | |
9405 | <term>Effects:</term> | |
9406 | <listitem> | |
9407 | <para> | |
9408 | Creates a promise by moving the <link linkend="shared_state">shared | |
9409 | state</link> from <code><phrase role="identifier">other</phrase></code>. | |
9410 | </para> | |
9411 | </listitem> | |
9412 | </varlistentry> | |
9413 | <varlistentry> | |
9414 | <term>Postcondition:</term> | |
9415 | <listitem> | |
9416 | <para> | |
9417 | <code><phrase role="identifier">other</phrase></code> contains no | |
9418 | valid shared state. | |
9419 | </para> | |
9420 | </listitem> | |
9421 | </varlistentry> | |
9422 | <varlistentry> | |
9423 | <term>Throws:</term> | |
9424 | <listitem> | |
9425 | <para> | |
9426 | Nothing. | |
9427 | </para> | |
9428 | </listitem> | |
9429 | </varlistentry> | |
9430 | </variablelist> | |
9431 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.promise.h3"> | |
9432 | <phrase id="fiber.synchronization.futures.promise.destructor"/><link linkend="fiber.synchronization.futures.promise.destructor">Destructor</link> | |
9433 | </bridgehead> | |
9434 | <programlisting><phrase role="special">~</phrase><phrase role="identifier">promise</phrase><phrase role="special">();</phrase> | |
9435 | </programlisting> | |
9436 | <variablelist> | |
9437 | <title></title> | |
9438 | <varlistentry> | |
9439 | <term>Effects:</term> | |
9440 | <listitem> | |
9441 | <para> | |
9442 | Destroys <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
9443 | and abandons the <link linkend="shared_state">shared state</link> | |
9444 | if shared state is ready; otherwise stores <code><phrase role="identifier">future_error</phrase></code> | |
9445 | with error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
9446 | role="special">::</phrase><phrase role="identifier">broken_promise</phrase></code> | |
9447 | as if by <link linkend="promise_set_exception"><code>promise::set_exception()</code></link>: the shared | |
9448 | state is set ready. | |
9449 | </para> | |
9450 | </listitem> | |
9451 | </varlistentry> | |
9452 | </variablelist> | |
9453 | <para> | |
9454 | <bridgehead renderas="sect4" id="promise_operator_assign_bridgehead"> | |
9455 | <phrase id="promise_operator_assign"/> | |
9456 | <link linkend="promise_operator_assign">Member | |
9457 | function <code>operator=</code>()</link> | |
9458 | </bridgehead> | |
9459 | </para> | |
9460 | <programlisting><phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9461 | </programlisting> | |
9462 | <variablelist> | |
9463 | <title></title> | |
9464 | <varlistentry> | |
9465 | <term>Effects:</term> | |
9466 | <listitem> | |
9467 | <para> | |
9468 | Transfers the ownership of <link linkend="shared_state">shared state</link> | |
9469 | to <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
9470 | </para> | |
9471 | </listitem> | |
9472 | </varlistentry> | |
9473 | <varlistentry> | |
9474 | <term>Postcondition:</term> | |
9475 | <listitem> | |
9476 | <para> | |
9477 | <code><phrase role="identifier">other</phrase></code> contains no | |
9478 | valid shared state. | |
9479 | </para> | |
9480 | </listitem> | |
9481 | </varlistentry> | |
9482 | <varlistentry> | |
9483 | <term>Throws:</term> | |
9484 | <listitem> | |
9485 | <para> | |
9486 | Nothing. | |
9487 | </para> | |
9488 | </listitem> | |
9489 | </varlistentry> | |
9490 | </variablelist> | |
9491 | <para> | |
9492 | <bridgehead renderas="sect4" id="promise_swap_bridgehead"> | |
9493 | <phrase id="promise_swap"/> | |
9494 | <link linkend="promise_swap">Member function <code>swap</code>()</link> | |
9495 | </bridgehead> | |
9496 | </para> | |
9497 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9498 | </programlisting> | |
9499 | <variablelist> | |
9500 | <title></title> | |
9501 | <varlistentry> | |
9502 | <term>Effects:</term> | |
9503 | <listitem> | |
9504 | <para> | |
9505 | Swaps the <link linkend="shared_state">shared state</link> between | |
9506 | other and <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
9507 | </para> | |
9508 | </listitem> | |
9509 | </varlistentry> | |
9510 | <varlistentry> | |
9511 | <term>Throws:</term> | |
9512 | <listitem> | |
9513 | <para> | |
9514 | Nothing. | |
9515 | </para> | |
9516 | </listitem> | |
9517 | </varlistentry> | |
9518 | </variablelist> | |
9519 | <para> | |
9520 | <bridgehead renderas="sect4" id="promise_get_future_bridgehead"> | |
9521 | <phrase id="promise_get_future"/> | |
9522 | <link linkend="promise_get_future">Member | |
9523 | function <code>get_future</code>()</link> | |
9524 | </bridgehead> | |
9525 | </para> | |
9526 | <programlisting><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase> | |
9527 | </programlisting> | |
9528 | <variablelist> | |
9529 | <title></title> | |
9530 | <varlistentry> | |
9531 | <term>Returns:</term> | |
9532 | <listitem> | |
9533 | <para> | |
9534 | A <link linkend="class_future"><code>future<></code></link> with the same <link linkend="shared_state">shared | |
9535 | state</link>. | |
9536 | </para> | |
9537 | </listitem> | |
9538 | </varlistentry> | |
9539 | <varlistentry> | |
9540 | <term>Throws:</term> | |
9541 | <listitem> | |
9542 | <para> | |
9543 | <code><phrase role="identifier">future_error</phrase></code> with | |
9544 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
9545 | role="identifier">future_already_retrieved</phrase></code> or <code><phrase | |
9546 | role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
9547 | role="identifier">no_state</phrase></code>. | |
9548 | </para> | |
9549 | </listitem> | |
9550 | </varlistentry> | |
9551 | </variablelist> | |
9552 | <para> | |
9553 | <bridgehead renderas="sect4" id="promise_set_value_bridgehead"> | |
9554 | <phrase id="promise_set_value"/> | |
9555 | <link linkend="promise_set_value">Member function | |
9556 | <code>set_value</code>()</link> | |
9557 | </bridgehead> | |
9558 | </para> | |
9559 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase> <phrase role="comment">// member only of generic promise template</phrase> | |
9560 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase> <phrase role="comment">// member only of generic promise template</phrase> | |
9561 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">R</phrase> <phrase role="special">&</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase> <phrase role="comment">// member only of promise< R & > template</phrase> | |
9562 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_value</phrase><phrase role="special">();</phrase> <phrase role="comment">// member only of promise< void > template</phrase> | |
9563 | </programlisting> | |
9564 | <variablelist> | |
9565 | <title></title> | |
9566 | <varlistentry> | |
9567 | <term>Effects:</term> | |
9568 | <listitem> | |
9569 | <para> | |
9570 | Store the result in the <link linkend="shared_state">shared state</link> | |
9571 | and marks the state as ready. | |
9572 | </para> | |
9573 | </listitem> | |
9574 | </varlistentry> | |
9575 | <varlistentry> | |
9576 | <term>Throws:</term> | |
9577 | <listitem> | |
9578 | <para> | |
9579 | <code><phrase role="identifier">future_error</phrase></code> with | |
9580 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
9581 | role="identifier">future_already_satisfied</phrase></code> or <code><phrase | |
9582 | role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
9583 | role="identifier">no_state</phrase></code>. | |
9584 | </para> | |
9585 | </listitem> | |
9586 | </varlistentry> | |
9587 | </variablelist> | |
9588 | <para> | |
9589 | <bridgehead renderas="sect4" id="promise_set_exception_bridgehead"> | |
9590 | <phrase id="promise_set_exception"/> | |
9591 | <link linkend="promise_set_exception">Member | |
9592 | function <code>set_exception</code>()</link> | |
9593 | </bridgehead> | |
9594 | </para> | |
9595 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">set_exception</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase><phrase role="special">);</phrase> | |
9596 | </programlisting> | |
9597 | <variablelist> | |
9598 | <title></title> | |
9599 | <varlistentry> | |
9600 | <term>Effects:</term> | |
9601 | <listitem> | |
9602 | <para> | |
9603 | Store an exception pointer in the <link linkend="shared_state">shared | |
9604 | state</link> and marks the state as ready. | |
9605 | </para> | |
9606 | </listitem> | |
9607 | </varlistentry> | |
9608 | <varlistentry> | |
9609 | <term>Throws:</term> | |
9610 | <listitem> | |
9611 | <para> | |
9612 | <code><phrase role="identifier">future_error</phrase></code> with | |
9613 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
9614 | role="identifier">future_already_satisfied</phrase></code> or <code><phrase | |
9615 | role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
9616 | role="identifier">no_state</phrase></code>. | |
9617 | </para> | |
9618 | </listitem> | |
9619 | </varlistentry> | |
9620 | </variablelist> | |
9621 | <para> | |
9622 | <bridgehead renderas="sect4" id="swap_for_promise_bridgehead"> | |
9623 | <phrase id="swap_for_promise"/> | |
9624 | <link linkend="swap_for_promise">Non-member function | |
9625 | <code>swap()</code></link> | |
9626 | </bridgehead> | |
9627 | </para> | |
9628 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> | |
9629 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9630 | </programlisting> | |
9631 | <variablelist> | |
9632 | <title></title> | |
9633 | <varlistentry> | |
9634 | <term>Effects:</term> | |
9635 | <listitem> | |
9636 | <para> | |
9637 | Same as <code><phrase role="identifier">l</phrase><phrase role="special">.</phrase><phrase | |
9638 | role="identifier">swap</phrase><phrase role="special">(</phrase> | |
9639 | <phrase role="identifier">r</phrase><phrase role="special">)</phrase></code>. | |
9640 | </para> | |
9641 | </listitem> | |
9642 | </varlistentry> | |
9643 | </variablelist> | |
9644 | </section> | |
9645 | <section id="fiber.synchronization.futures.packaged_task"> | |
9646 | <title><anchor id="class_packaged_task"/><link linkend="fiber.synchronization.futures.packaged_task">Template | |
9647 | <code><phrase role="identifier">packaged_task</phrase><phrase role="special"><></phrase></code></link></title> | |
9648 | <para> | |
9649 | A <link linkend="class_packaged_task"><code>packaged_task<></code></link> wraps a callable target that | |
9650 | returns a value so that the return value can be computed asynchronously. | |
9651 | </para> | |
9652 | <para> | |
9653 | Conventional usage of <code><phrase role="identifier">packaged_task</phrase><phrase | |
9654 | role="special"><></phrase></code> is like this: | |
9655 | </para> | |
9656 | <orderedlist> | |
9657 | <listitem> | |
9658 | <simpara> | |
9659 | Instantiate <code><phrase role="identifier">packaged_task</phrase><phrase | |
9660 | role="special"><></phrase></code> with template arguments matching | |
9661 | the signature of the callable. Pass the callable to the <link linkend="packaged_task_packaged_task">constructor</link>. | |
9662 | </simpara> | |
9663 | </listitem> | |
9664 | <listitem> | |
9665 | <simpara> | |
9666 | Call <link linkend="packaged_task_get_future"><code>packaged_task::get_future()</code></link> and capture | |
9667 | the returned <link linkend="class_future"><code>future<></code></link> instance. | |
9668 | </simpara> | |
9669 | </listitem> | |
9670 | <listitem> | |
9671 | <simpara> | |
9672 | Launch a <link linkend="class_fiber"><code>fiber</code></link> to run the new <code><phrase role="identifier">packaged_task</phrase><phrase | |
9673 | role="special"><></phrase></code>, passing any arguments required | |
9674 | by the original callable. | |
9675 | </simpara> | |
9676 | </listitem> | |
9677 | <listitem> | |
9678 | <simpara> | |
9679 | Call <link linkend="fiber_detach"><code>fiber::detach()</code></link> on the newly-launched <code><phrase | |
9680 | role="identifier">fiber</phrase></code>. | |
9681 | </simpara> | |
9682 | </listitem> | |
9683 | <listitem> | |
9684 | <simpara> | |
9685 | At some later point, retrieve the result from the <code><phrase role="identifier">future</phrase><phrase | |
9686 | role="special"><></phrase></code>. | |
9687 | </simpara> | |
9688 | </listitem> | |
9689 | </orderedlist> | |
9690 | <para> | |
9691 | This is, in fact, pretty much what <link linkend="fibers_async"><code>fibers::async()</code></link> | |
9692 | encapsulates. | |
9693 | </para> | |
9694 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">future</phrase><phrase role="special">/</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
9695 | ||
9696 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
9697 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
9698 | ||
9699 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">R</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">></phrase> | |
9700 | <phrase role="keyword">class</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase><phrase role="special">(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> <phrase role="special">></phrase> <phrase role="special">{</phrase> | |
9701 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
9702 | <phrase role="identifier">packaged_task</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9703 | ||
9704 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
9705 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&);</phrase> | |
9706 | ||
9707 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="special">></phrase> | |
9708 | <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="keyword">const</phrase><phrase role="special">&,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&);</phrase> | |
9709 | ||
9710 | <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9711 | ||
9712 | <phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9713 | ||
9714 | <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
9715 | ||
9716 | <phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
9717 | ||
9718 | <phrase role="special">~</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special">();</phrase> | |
9719 | ||
9720 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9721 | ||
9722 | <phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9723 | ||
9724 | <phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase> | |
9725 | ||
9726 | <phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">...);</phrase> | |
9727 | ||
9728 | <phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">();</phrase> | |
9729 | <phrase role="special">};</phrase> | |
9730 | ||
9731 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Signature</phrase> <phrase role="special">></phrase> | |
9732 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase> <phrase role="identifier">Signature</phrase> <phrase role="special">></phrase> <phrase role="special">&,</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase> <phrase role="identifier">Signature</phrase> <phrase role="special">></phrase> <phrase role="special">&)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9733 | ||
9734 | <phrase role="special">}}</phrase> | |
9735 | </programlisting> | |
9736 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h0"> | |
9737 | <phrase id="fiber.synchronization.futures.packaged_task.default_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_"/><link | |
9738 | linkend="fiber.synchronization.futures.packaged_task.default_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_">Default | |
9739 | constructor <code><phrase role="identifier">packaged_task</phrase><phrase | |
9740 | role="special">()</phrase></code></link> | |
9741 | </bridgehead> | |
9742 | <programlisting><phrase role="identifier">packaged_task</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9743 | </programlisting> | |
9744 | <variablelist> | |
9745 | <title></title> | |
9746 | <varlistentry> | |
9747 | <term>Effects:</term> | |
9748 | <listitem> | |
9749 | <para> | |
9750 | Constructs an object of class <code><phrase role="identifier">packaged_task</phrase></code> | |
9751 | with no <link linkend="shared_state">shared state</link>. | |
9752 | </para> | |
9753 | </listitem> | |
9754 | </varlistentry> | |
9755 | <varlistentry> | |
9756 | <term>Throws:</term> | |
9757 | <listitem> | |
9758 | <para> | |
9759 | Nothing. | |
9760 | </para> | |
9761 | </listitem> | |
9762 | </varlistentry> | |
9763 | </variablelist> | |
9764 | <anchor id="packaged_task_packaged_task"/> | |
9765 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h1"> | |
9766 | <phrase id="fiber.synchronization.futures.packaged_task.templated_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_"/><link | |
9767 | linkend="fiber.synchronization.futures.packaged_task.templated_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_">Templated | |
9768 | constructor <code><phrase role="identifier">packaged_task</phrase><phrase | |
9769 | role="special">()</phrase></code></link> | |
9770 | </bridgehead> | |
9771 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
9772 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase> | |
9773 | ||
9774 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <ulink url="http://en.cppreference.com/w/cpp/concept/Allocator"><code><phrase role="identifier">Allocator</phrase></code></ulink> <phrase role="special">></phrase> | |
9775 | <phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">allocator_arg_t</phrase></code></ulink><phrase role="special">,</phrase> <phrase role="identifier">Allocator</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">alloc</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">fn</phrase><phrase role="special">);</phrase> | |
9776 | </programlisting> | |
9777 | <variablelist> | |
9778 | <title></title> | |
9779 | <varlistentry> | |
9780 | <term>Effects:</term> | |
9781 | <listitem> | |
9782 | <para> | |
9783 | Constructs an object of class <code><phrase role="identifier">packaged_task</phrase></code> | |
9784 | with a <link linkend="shared_state">shared state</link> and copies | |
9785 | or moves the callable target <code><phrase role="identifier">fn</phrase></code> | |
9786 | to internal storage. | |
9787 | </para> | |
9788 | </listitem> | |
9789 | </varlistentry> | |
9790 | <varlistentry> | |
9791 | <term>Throws:</term> | |
9792 | <listitem> | |
9793 | <para> | |
9794 | Exceptions caused by memory allocation. | |
9795 | </para> | |
9796 | </listitem> | |
9797 | </varlistentry> | |
9798 | <varlistentry> | |
9799 | <term>Note:</term> | |
9800 | <listitem> | |
9801 | <para> | |
9802 | The signature of <code><phrase role="identifier">Fn</phrase></code> | |
9803 | should have a return type convertible to <code><phrase role="identifier">R</phrase></code>. | |
9804 | </para> | |
9805 | </listitem> | |
9806 | </varlistentry> | |
9807 | <varlistentry> | |
9808 | <term>See also:</term> | |
9809 | <listitem> | |
9810 | <para> | |
9811 | <ulink url="http://en.cppreference.com/w/cpp/memory/allocator_arg_t"><code><phrase | |
9812 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
9813 | role="identifier">allocator_arg_t</phrase></code></ulink> | |
9814 | </para> | |
9815 | </listitem> | |
9816 | </varlistentry> | |
9817 | </variablelist> | |
9818 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h2"> | |
9819 | <phrase id="fiber.synchronization.futures.packaged_task.move_constructor"/><link | |
9820 | linkend="fiber.synchronization.futures.packaged_task.move_constructor">Move | |
9821 | constructor</link> | |
9822 | </bridgehead> | |
9823 | <programlisting><phrase role="identifier">packaged_task</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9824 | </programlisting> | |
9825 | <variablelist> | |
9826 | <title></title> | |
9827 | <varlistentry> | |
9828 | <term>Effects:</term> | |
9829 | <listitem> | |
9830 | <para> | |
9831 | Creates a packaged_task by moving the <link linkend="shared_state">shared | |
9832 | state</link> from <code><phrase role="identifier">other</phrase></code>. | |
9833 | </para> | |
9834 | </listitem> | |
9835 | </varlistentry> | |
9836 | <varlistentry> | |
9837 | <term>Postcondition:</term> | |
9838 | <listitem> | |
9839 | <para> | |
9840 | <code><phrase role="identifier">other</phrase></code> contains no | |
9841 | valid shared state. | |
9842 | </para> | |
9843 | </listitem> | |
9844 | </varlistentry> | |
9845 | <varlistentry> | |
9846 | <term>Throws:</term> | |
9847 | <listitem> | |
9848 | <para> | |
9849 | Nothing. | |
9850 | </para> | |
9851 | </listitem> | |
9852 | </varlistentry> | |
9853 | </variablelist> | |
9854 | <bridgehead renderas="sect5" id="fiber.synchronization.futures.packaged_task.h3"> | |
9855 | <phrase id="fiber.synchronization.futures.packaged_task.destructor"/><link | |
9856 | linkend="fiber.synchronization.futures.packaged_task.destructor">Destructor</link> | |
9857 | </bridgehead> | |
9858 | <programlisting><phrase role="special">~</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special">();</phrase> | |
9859 | </programlisting> | |
9860 | <variablelist> | |
9861 | <title></title> | |
9862 | <varlistentry> | |
9863 | <term>Effects:</term> | |
9864 | <listitem> | |
9865 | <para> | |
9866 | Destroys <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
9867 | and abandons the <link linkend="shared_state">shared state</link> | |
9868 | if shared state is ready; otherwise stores <code><phrase role="identifier">future_error</phrase></code> | |
9869 | with error condition <code><phrase role="identifier">future_errc</phrase><phrase | |
9870 | role="special">::</phrase><phrase role="identifier">broken_promise</phrase></code> | |
9871 | as if by <link linkend="promise_set_exception"><code>promise::set_exception()</code></link>: the shared | |
9872 | state is set ready. | |
9873 | </para> | |
9874 | </listitem> | |
9875 | </varlistentry> | |
9876 | </variablelist> | |
9877 | <para> | |
9878 | <bridgehead renderas="sect4" id="packaged_task_operator_assign_bridgehead"> | |
9879 | <phrase id="packaged_task_operator_assign"/> | |
9880 | <link linkend="packaged_task_operator_assign">Member | |
9881 | function <code>operator=</code>()</link> | |
9882 | </bridgehead> | |
9883 | </para> | |
9884 | <programlisting><phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9885 | </programlisting> | |
9886 | <variablelist> | |
9887 | <title></title> | |
9888 | <varlistentry> | |
9889 | <term>Effects:</term> | |
9890 | <listitem> | |
9891 | <para> | |
9892 | Transfers the ownership of <link linkend="shared_state">shared state</link> | |
9893 | to <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
9894 | </para> | |
9895 | </listitem> | |
9896 | </varlistentry> | |
9897 | <varlistentry> | |
9898 | <term>Postcondition:</term> | |
9899 | <listitem> | |
9900 | <para> | |
9901 | <code><phrase role="identifier">other</phrase></code> contains no | |
9902 | valid shared state. | |
9903 | </para> | |
9904 | </listitem> | |
9905 | </varlistentry> | |
9906 | <varlistentry> | |
9907 | <term>Throws:</term> | |
9908 | <listitem> | |
9909 | <para> | |
9910 | Nothing. | |
9911 | </para> | |
9912 | </listitem> | |
9913 | </varlistentry> | |
9914 | </variablelist> | |
9915 | <para> | |
9916 | <bridgehead renderas="sect4" id="packaged_task_swap_bridgehead"> | |
9917 | <phrase id="packaged_task_swap"/> | |
9918 | <link linkend="packaged_task_swap">Member | |
9919 | function <code>swap</code>()</link> | |
9920 | </bridgehead> | |
9921 | </para> | |
9922 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase> <phrase role="special">&</phrase> <phrase role="identifier">other</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9923 | </programlisting> | |
9924 | <variablelist> | |
9925 | <title></title> | |
9926 | <varlistentry> | |
9927 | <term>Effects:</term> | |
9928 | <listitem> | |
9929 | <para> | |
9930 | Swaps the <link linkend="shared_state">shared state</link> between | |
9931 | other and <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
9932 | </para> | |
9933 | </listitem> | |
9934 | </varlistentry> | |
9935 | <varlistentry> | |
9936 | <term>Throws:</term> | |
9937 | <listitem> | |
9938 | <para> | |
9939 | Nothing. | |
9940 | </para> | |
9941 | </listitem> | |
9942 | </varlistentry> | |
9943 | </variablelist> | |
9944 | <para> | |
9945 | <bridgehead renderas="sect4" id="packaged_task_valid_bridgehead"> | |
9946 | <phrase id="packaged_task_valid"/> | |
9947 | <link linkend="packaged_task_valid">Member | |
9948 | function <code>valid</code>()</link> | |
9949 | </bridgehead> | |
9950 | </para> | |
9951 | <programlisting><phrase role="keyword">bool</phrase> <phrase role="identifier">valid</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
9952 | </programlisting> | |
9953 | <variablelist> | |
9954 | <title></title> | |
9955 | <varlistentry> | |
9956 | <term>Effects:</term> | |
9957 | <listitem> | |
9958 | <para> | |
9959 | Returns <code><phrase role="keyword">true</phrase></code> if <code><phrase | |
9960 | role="special">*</phrase><phrase role="keyword">this</phrase></code> | |
9961 | contains a <link linkend="shared_state">shared state</link>. | |
9962 | </para> | |
9963 | </listitem> | |
9964 | </varlistentry> | |
9965 | <varlistentry> | |
9966 | <term>Throws:</term> | |
9967 | <listitem> | |
9968 | <para> | |
9969 | Nothing. | |
9970 | </para> | |
9971 | </listitem> | |
9972 | </varlistentry> | |
9973 | </variablelist> | |
9974 | <para> | |
9975 | <bridgehead renderas="sect4" id="packaged_task_get_future_bridgehead"> | |
9976 | <phrase id="packaged_task_get_future"/> | |
9977 | <link linkend="packaged_task_get_future">Member | |
9978 | function <code>get_future</code>()</link> | |
9979 | </bridgehead> | |
9980 | </para> | |
9981 | <programlisting><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">R</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">();</phrase> | |
9982 | </programlisting> | |
9983 | <variablelist> | |
9984 | <title></title> | |
9985 | <varlistentry> | |
9986 | <term>Returns:</term> | |
9987 | <listitem> | |
9988 | <para> | |
9989 | A <link linkend="class_future"><code>future<></code></link> with the same <link linkend="shared_state">shared | |
9990 | state</link>. | |
9991 | </para> | |
9992 | </listitem> | |
9993 | </varlistentry> | |
9994 | <varlistentry> | |
9995 | <term>Throws:</term> | |
9996 | <listitem> | |
9997 | <para> | |
9998 | <code><phrase role="identifier">future_error</phrase></code> with | |
9999 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
10000 | role="identifier">future_already_retrieved</phrase></code> or <code><phrase | |
10001 | role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
10002 | role="identifier">no_state</phrase></code>. | |
10003 | </para> | |
10004 | </listitem> | |
10005 | </varlistentry> | |
10006 | </variablelist> | |
10007 | <para> | |
10008 | <bridgehead renderas="sect4" id="packaged_task_operator_apply_bridgehead"> | |
10009 | <phrase id="packaged_task_operator_apply"/> | |
10010 | <link linkend="packaged_task_operator_apply">Member | |
10011 | function <code>operator()</code>()</link> | |
10012 | </bridgehead> | |
10013 | </para> | |
10014 | <programlisting><phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">Args</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">args</phrase><phrase role="special">);</phrase> | |
10015 | </programlisting> | |
10016 | <variablelist> | |
10017 | <title></title> | |
10018 | <varlistentry> | |
10019 | <term>Effects:</term> | |
10020 | <listitem> | |
10021 | <para> | |
10022 | Invokes the stored callable target. Any exception thrown by the callable | |
10023 | target <code><phrase role="identifier">fn</phrase></code> is stored | |
10024 | in the <link linkend="shared_state">shared state</link> as if by | |
10025 | <link linkend="promise_set_exception"><code>promise::set_exception()</code></link>. Otherwise, the value | |
10026 | returned by <code><phrase role="identifier">fn</phrase></code> is | |
10027 | stored in the shared state as if by <link linkend="promise_set_value"><code>promise::set_value()</code></link>. | |
10028 | </para> | |
10029 | </listitem> | |
10030 | </varlistentry> | |
10031 | <varlistentry> | |
10032 | <term>Throws:</term> | |
10033 | <listitem> | |
10034 | <para> | |
10035 | <code><phrase role="identifier">future_error</phrase></code> with | |
10036 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
10037 | role="identifier">no_state</phrase></code>. | |
10038 | </para> | |
10039 | </listitem> | |
10040 | </varlistentry> | |
10041 | </variablelist> | |
10042 | <para> | |
10043 | <bridgehead renderas="sect4" id="packaged_task_reset_bridgehead"> | |
10044 | <phrase id="packaged_task_reset"/> | |
10045 | <link linkend="packaged_task_reset">Member | |
10046 | function <code>reset</code>()</link> | |
10047 | </bridgehead> | |
10048 | </para> | |
10049 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">();</phrase> | |
10050 | </programlisting> | |
10051 | <variablelist> | |
10052 | <title></title> | |
10053 | <varlistentry> | |
10054 | <term>Effects:</term> | |
10055 | <listitem> | |
10056 | <para> | |
10057 | Resets the <link linkend="shared_state">shared state</link> and abandons | |
10058 | the result of previous executions. A new shared state is constructed. | |
10059 | </para> | |
10060 | </listitem> | |
10061 | </varlistentry> | |
10062 | <varlistentry> | |
10063 | <term>Throws:</term> | |
10064 | <listitem> | |
10065 | <para> | |
10066 | <code><phrase role="identifier">future_error</phrase></code> with | |
10067 | <code><phrase role="identifier">future_errc</phrase><phrase role="special">::</phrase><phrase | |
10068 | role="identifier">no_state</phrase></code>. | |
10069 | </para> | |
10070 | </listitem> | |
10071 | </varlistentry> | |
10072 | </variablelist> | |
10073 | <para> | |
10074 | <bridgehead renderas="sect4" id="swap_for_packaged_task_bridgehead"> | |
10075 | <phrase id="swap_for_packaged_task"/> | |
10076 | <link linkend="swap_for_packaged_task">Non-member | |
10077 | function <code>swap()</code></link> | |
10078 | </bridgehead> | |
10079 | </para> | |
10080 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Signature</phrase> <phrase role="special">></phrase> | |
10081 | <phrase role="keyword">void</phrase> <phrase role="identifier">swap</phrase><phrase role="special">(</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase> <phrase role="identifier">Signature</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">l</phrase><phrase role="special">,</phrase> <phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase> <phrase role="identifier">Signature</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">r</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
10082 | </programlisting> | |
10083 | <variablelist> | |
10084 | <title></title> | |
10085 | <varlistentry> | |
10086 | <term>Effects:</term> | |
10087 | <listitem> | |
10088 | <para> | |
10089 | Same as <code><phrase role="identifier">l</phrase><phrase role="special">.</phrase><phrase | |
10090 | role="identifier">swap</phrase><phrase role="special">(</phrase> | |
10091 | <phrase role="identifier">r</phrase><phrase role="special">)</phrase></code>. | |
10092 | </para> | |
10093 | </listitem> | |
10094 | </varlistentry> | |
10095 | </variablelist> | |
10096 | </section> | |
10097 | </section> | |
10098 | </section> | |
10099 | <section id="fiber.fls"> | |
10100 | <title><link linkend="fiber.fls">Fiber local storage</link></title> | |
10101 | <bridgehead renderas="sect3" id="fiber.fls.h0"> | |
10102 | <phrase id="fiber.fls.synopsis"/><link linkend="fiber.fls.synopsis">Synopsis</link> | |
10103 | </bridgehead> | |
10104 | <para> | |
10105 | Fiber local storage allows a separate instance of a given data item for each | |
10106 | fiber. | |
10107 | </para> | |
10108 | <bridgehead renderas="sect3" id="fiber.fls.h1"> | |
10109 | <phrase id="fiber.fls.cleanup_at_fiber_exit"/><link linkend="fiber.fls.cleanup_at_fiber_exit">Cleanup | |
10110 | at fiber exit</link> | |
10111 | </bridgehead> | |
10112 | <para> | |
10113 | When a fiber exits, the objects associated with each <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> instance | |
10114 | are destroyed. By default, the object pointed to by a pointer <code><phrase | |
10115 | role="identifier">p</phrase></code> is destroyed by invoking <code><phrase | |
10116 | role="keyword">delete</phrase> <phrase role="identifier">p</phrase></code>, | |
10117 | but this can be overridden for a specific instance of <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> by | |
10118 | providing a cleanup routine <code><phrase role="identifier">func</phrase></code> | |
10119 | to the constructor. In this case, the object is destroyed by invoking <code><phrase | |
10120 | role="identifier">func</phrase><phrase role="special">(</phrase><phrase role="identifier">p</phrase><phrase | |
10121 | role="special">)</phrase></code>. The cleanup functions are called in an unspecified | |
10122 | order. | |
10123 | </para> | |
10124 | <para> | |
10125 | <bridgehead renderas="sect4" id="class_fiber_specific_ptr_bridgehead"> | |
10126 | <phrase id="class_fiber_specific_ptr"/> | |
10127 | <link linkend="class_fiber_specific_ptr">Class | |
10128 | <code>fiber_specific_ptr</code></link> | |
10129 | </bridgehead> | |
10130 | </para> | |
10131 | <programlisting><phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">fss</phrase><phrase role="special">.</phrase><phrase role="identifier">hpp</phrase><phrase role="special">></phrase> | |
10132 | ||
10133 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">boost</phrase> <phrase role="special">{</phrase> | |
10134 | <phrase role="keyword">namespace</phrase> <phrase role="identifier">fibers</phrase> <phrase role="special">{</phrase> | |
10135 | ||
10136 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> | |
10137 | <phrase role="keyword">class</phrase> <phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="special">{</phrase> | |
10138 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
10139 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">element_type</phrase><phrase role="special">;</phrase> | |
10140 | ||
10141 | <phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase> | |
10142 | ||
10143 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">(</phrase> <phrase role="keyword">void</phrase><phrase role="special">(*</phrase><phrase role="identifier">fn</phrase><phrase role="special">)(</phrase><phrase role="identifier">T</phrase><phrase role="special">*)</phrase> <phrase role="special">);</phrase> | |
10144 | ||
10145 | <phrase role="special">~</phrase><phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase> | |
10146 | ||
10147 | <phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
10148 | <phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">fiber_specific_ptr</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
10149 | ||
10150 | <phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
10151 | ||
10152 | <phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="keyword">operator</phrase><phrase role="special">->()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
10153 | ||
10154 | <phrase role="identifier">T</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">*()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
10155 | ||
10156 | <phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">release</phrase><phrase role="special">();</phrase> | |
10157 | ||
10158 | <phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">(</phrase> <phrase role="identifier">T</phrase> <phrase role="special">*);</phrase> | |
10159 | <phrase role="special">};</phrase> | |
10160 | ||
10161 | <phrase role="special">}}</phrase> | |
10162 | </programlisting> | |
10163 | <bridgehead renderas="sect3" id="fiber.fls.h2"> | |
10164 | <phrase id="fiber.fls.constructor"/><link linkend="fiber.fls.constructor">Constructor</link> | |
10165 | </bridgehead> | |
10166 | <programlisting><phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase> | |
10167 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">(</phrase> <phrase role="keyword">void</phrase><phrase role="special">(*</phrase><phrase role="identifier">fn</phrase><phrase role="special">)(</phrase><phrase role="identifier">T</phrase><phrase role="special">*)</phrase> <phrase role="special">);</phrase> | |
10168 | </programlisting> | |
10169 | <variablelist> | |
10170 | <title></title> | |
10171 | <varlistentry> | |
10172 | <term>Requires:</term> | |
10173 | <listitem> | |
10174 | <para> | |
10175 | <code><phrase role="keyword">delete</phrase> <phrase role="keyword">this</phrase><phrase | |
10176 | role="special">-></phrase><phrase role="identifier">get</phrase><phrase | |
10177 | role="special">()</phrase></code> is well-formed; <code><phrase role="identifier">fn</phrase><phrase | |
10178 | role="special">(</phrase><phrase role="keyword">this</phrase><phrase | |
10179 | role="special">-></phrase><phrase role="identifier">get</phrase><phrase | |
10180 | role="special">())</phrase></code> does not throw | |
10181 | </para> | |
10182 | </listitem> | |
10183 | </varlistentry> | |
10184 | <varlistentry> | |
10185 | <term>Effects:</term> | |
10186 | <listitem> | |
10187 | <para> | |
10188 | Construct a <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> object for storing | |
10189 | a pointer to an object of type <code><phrase role="identifier">T</phrase></code> | |
10190 | specific to each fiber. When <code><phrase role="identifier">reset</phrase><phrase | |
10191 | role="special">()</phrase></code> is called, or the fiber exits, <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> calls | |
10192 | <code><phrase role="identifier">fn</phrase><phrase role="special">(</phrase><phrase | |
10193 | role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10194 | role="identifier">get</phrase><phrase role="special">())</phrase></code>. | |
10195 | If the no-arguments constructor is used, the default <code><phrase role="keyword">delete</phrase></code>-based | |
10196 | cleanup function will be used to destroy the fiber-local objects. | |
10197 | </para> | |
10198 | </listitem> | |
10199 | </varlistentry> | |
10200 | <varlistentry> | |
10201 | <term>Throws:</term> | |
10202 | <listitem> | |
10203 | <para> | |
10204 | <code><phrase role="identifier">fiber_error</phrase></code> if an error | |
10205 | occurs. | |
10206 | </para> | |
10207 | </listitem> | |
10208 | </varlistentry> | |
10209 | </variablelist> | |
10210 | <bridgehead renderas="sect3" id="fiber.fls.h3"> | |
10211 | <phrase id="fiber.fls.destructor"/><link linkend="fiber.fls.destructor">Destructor</link> | |
10212 | </bridgehead> | |
10213 | <programlisting><phrase role="special">~</phrase><phrase role="identifier">fiber_specific_ptr</phrase><phrase role="special">();</phrase> | |
10214 | </programlisting> | |
10215 | <variablelist> | |
10216 | <title></title> | |
10217 | <varlistentry> | |
10218 | <term>Requires:</term> | |
10219 | <listitem> | |
10220 | <para> | |
10221 | All the fiber specific instances associated to this <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> | |
10222 | (except | |
10223 | maybe the one associated to this fiber) must be nullptr. | |
10224 | </para> | |
10225 | </listitem> | |
10226 | </varlistentry> | |
10227 | <varlistentry> | |
10228 | <term>Effects:</term> | |
10229 | <listitem> | |
10230 | <para> | |
10231 | Calls <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10232 | role="identifier">reset</phrase><phrase role="special">()</phrase></code> | |
10233 | to clean up the associated value for the current fiber, and destroys | |
10234 | <code><phrase role="special">*</phrase><phrase role="keyword">this</phrase></code>. | |
10235 | </para> | |
10236 | </listitem> | |
10237 | </varlistentry> | |
10238 | <varlistentry> | |
10239 | <term>Remarks:</term> | |
10240 | <listitem> | |
10241 | <para> | |
10242 | The requirement is an implementation restriction. If the destructor promised | |
10243 | to delete instances for all fibers, the implementation would be forced | |
10244 | to maintain a list of all the fibers having an associated specific ptr, | |
10245 | which is against the goal of fiber specific data. In general, a <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> should | |
10246 | outlive the fibers that use it. | |
10247 | </para> | |
10248 | </listitem> | |
10249 | </varlistentry> | |
10250 | </variablelist> | |
10251 | <note> | |
10252 | <para> | |
10253 | Care needs to be taken to ensure that any fibers still running after an instance | |
10254 | of <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> has been destroyed do not call | |
10255 | any member functions on that instance. | |
10256 | </para> | |
10257 | </note> | |
10258 | <para> | |
10259 | <bridgehead renderas="sect4" id="fiber_specific_ptr_get_bridgehead"> | |
10260 | <phrase id="fiber_specific_ptr_get"/> | |
10261 | <link linkend="fiber_specific_ptr_get">Member | |
10262 | function <code>get</code>()</link> | |
10263 | </bridgehead> | |
10264 | </para> | |
10265 | <programlisting><phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
10266 | </programlisting> | |
10267 | <variablelist> | |
10268 | <title></title> | |
10269 | <varlistentry> | |
10270 | <term>Returns:</term> | |
10271 | <listitem> | |
10272 | <para> | |
10273 | The pointer associated with the current fiber. | |
10274 | </para> | |
10275 | </listitem> | |
10276 | </varlistentry> | |
10277 | <varlistentry> | |
10278 | <term>Throws:</term> | |
10279 | <listitem> | |
10280 | <para> | |
10281 | Nothing. | |
10282 | </para> | |
10283 | </listitem> | |
10284 | </varlistentry> | |
10285 | </variablelist> | |
10286 | <note> | |
10287 | <para> | |
10288 | The initial value associated with an instance of <link linkend="class_fiber_specific_ptr"><code>fiber_specific_ptr</code></link> is | |
10289 | <code><phrase role="keyword">nullptr</phrase></code> for each fiber. | |
10290 | </para> | |
10291 | </note> | |
10292 | <para> | |
10293 | <bridgehead renderas="sect4" id="fiber_specific_ptr_operator_arrow_bridgehead"> | |
10294 | <phrase id="fiber_specific_ptr_operator_arrow"/> | |
10295 | <link linkend="fiber_specific_ptr_operator_arrow">Member | |
10296 | function <code>operator-></code>()</link> | |
10297 | </bridgehead> | |
10298 | </para> | |
10299 | <programlisting><phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="keyword">operator</phrase><phrase role="special">->()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
10300 | </programlisting> | |
10301 | <variablelist> | |
10302 | <title></title> | |
10303 | <varlistentry> | |
10304 | <term>Requires:</term> | |
10305 | <listitem> | |
10306 | <para> | |
10307 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10308 | role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
10309 | is not <code><phrase role="keyword">nullptr</phrase></code>. | |
10310 | </para> | |
10311 | </listitem> | |
10312 | </varlistentry> | |
10313 | <varlistentry> | |
10314 | <term>Returns:</term> | |
10315 | <listitem> | |
10316 | <para> | |
10317 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10318 | role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
10319 | </para> | |
10320 | </listitem> | |
10321 | </varlistentry> | |
10322 | <varlistentry> | |
10323 | <term>Throws:</term> | |
10324 | <listitem> | |
10325 | <para> | |
10326 | Nothing. | |
10327 | </para> | |
10328 | </listitem> | |
10329 | </varlistentry> | |
10330 | </variablelist> | |
10331 | <para> | |
10332 | <bridgehead renderas="sect4" id="fiber_specific_ptr_operator_star_bridgehead"> | |
10333 | <phrase id="fiber_specific_ptr_operator_star"/> | |
10334 | <link linkend="fiber_specific_ptr_operator_star">Member | |
10335 | function <code>operator*</code>()</link> | |
10336 | </bridgehead> | |
10337 | </para> | |
10338 | <programlisting><phrase role="identifier">T</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">*()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase><phrase role="special">;</phrase> | |
10339 | </programlisting> | |
10340 | <variablelist> | |
10341 | <title></title> | |
10342 | <varlistentry> | |
10343 | <term>Requires:</term> | |
10344 | <listitem> | |
10345 | <para> | |
10346 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10347 | role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
10348 | is not <code><phrase role="keyword">nullptr</phrase></code>. | |
10349 | </para> | |
10350 | </listitem> | |
10351 | </varlistentry> | |
10352 | <varlistentry> | |
10353 | <term>Returns:</term> | |
10354 | <listitem> | |
10355 | <para> | |
10356 | <code><phrase role="special">*(</phrase><phrase role="keyword">this</phrase><phrase | |
10357 | role="special">-></phrase><phrase role="identifier">get</phrase><phrase | |
10358 | role="special">())</phrase></code> | |
10359 | </para> | |
10360 | </listitem> | |
10361 | </varlistentry> | |
10362 | <varlistentry> | |
10363 | <term>Throws:</term> | |
10364 | <listitem> | |
10365 | <para> | |
10366 | Nothing. | |
10367 | </para> | |
10368 | </listitem> | |
10369 | </varlistentry> | |
10370 | </variablelist> | |
10371 | <para> | |
10372 | <bridgehead renderas="sect4" id="fiber_specific_ptr_release_bridgehead"> | |
10373 | <phrase id="fiber_specific_ptr_release"/> | |
10374 | <link linkend="fiber_specific_ptr_release">Member | |
10375 | function <code>release</code>()</link> | |
10376 | </bridgehead> | |
10377 | </para> | |
10378 | <programlisting><phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">release</phrase><phrase role="special">();</phrase> | |
10379 | </programlisting> | |
10380 | <variablelist> | |
10381 | <title></title> | |
10382 | <varlistentry> | |
10383 | <term>Effects:</term> | |
10384 | <listitem> | |
10385 | <para> | |
10386 | Return <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10387 | role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
10388 | and store <code><phrase role="keyword">nullptr</phrase></code> as the | |
10389 | pointer associated with the current fiber without invoking the cleanup | |
10390 | function. | |
10391 | </para> | |
10392 | </listitem> | |
10393 | </varlistentry> | |
10394 | <varlistentry> | |
10395 | <term>Postcondition:</term> | |
10396 | <listitem> | |
10397 | <para> | |
10398 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10399 | role="identifier">get</phrase><phrase role="special">()==</phrase><phrase | |
10400 | role="keyword">nullptr</phrase></code> | |
10401 | </para> | |
10402 | </listitem> | |
10403 | </varlistentry> | |
10404 | <varlistentry> | |
10405 | <term>Throws:</term> | |
10406 | <listitem> | |
10407 | <para> | |
10408 | Nothing. | |
10409 | </para> | |
10410 | </listitem> | |
10411 | </varlistentry> | |
10412 | </variablelist> | |
10413 | <para> | |
10414 | <bridgehead renderas="sect4" id="fiber_specific_ptr_reset_bridgehead"> | |
10415 | <phrase id="fiber_specific_ptr_reset"/> | |
10416 | <link linkend="fiber_specific_ptr_reset">Member | |
10417 | function <code>reset</code>()</link> | |
10418 | </bridgehead> | |
10419 | </para> | |
10420 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">reset</phrase><phrase role="special">(</phrase> <phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">new_value</phrase><phrase role="special">);</phrase> | |
10421 | </programlisting> | |
10422 | <variablelist> | |
10423 | <title></title> | |
10424 | <varlistentry> | |
10425 | <term>Effects:</term> | |
10426 | <listitem> | |
10427 | <para> | |
10428 | If <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10429 | role="identifier">get</phrase><phrase role="special">()!=</phrase><phrase | |
10430 | role="identifier">new_value</phrase></code> and <code><phrase role="keyword">this</phrase><phrase | |
10431 | role="special">-></phrase><phrase role="identifier">get</phrase><phrase | |
10432 | role="special">()</phrase></code> is not <code><phrase role="keyword">nullptr</phrase></code>, | |
10433 | invoke <code><phrase role="keyword">delete</phrase> <phrase role="keyword">this</phrase><phrase | |
10434 | role="special">-></phrase><phrase role="identifier">get</phrase><phrase | |
10435 | role="special">()</phrase></code> or <code><phrase role="identifier">fn</phrase><phrase | |
10436 | role="special">(</phrase><phrase role="keyword">this</phrase><phrase | |
10437 | role="special">-></phrase><phrase role="identifier">get</phrase><phrase | |
10438 | role="special">())</phrase></code> as appropriate. Store <code><phrase | |
10439 | role="identifier">new_value</phrase></code> as the pointer associated | |
10440 | with the current fiber. | |
10441 | </para> | |
10442 | </listitem> | |
10443 | </varlistentry> | |
10444 | <varlistentry> | |
10445 | <term>Postcondition:</term> | |
10446 | <listitem> | |
10447 | <para> | |
10448 | <code><phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase | |
10449 | role="identifier">get</phrase><phrase role="special">()==</phrase><phrase | |
10450 | role="identifier">new_value</phrase></code> | |
10451 | </para> | |
10452 | </listitem> | |
10453 | </varlistentry> | |
10454 | <varlistentry> | |
10455 | <term>Throws:</term> | |
10456 | <listitem> | |
10457 | <para> | |
10458 | Exception raised during cleanup of previous value. | |
10459 | </para> | |
10460 | </listitem> | |
10461 | </varlistentry> | |
10462 | </variablelist> | |
10463 | </section> | |
10464 | <section id="fiber.migration"> | |
10465 | <title><anchor id="migration"/><link linkend="fiber.migration">Migrating fibers | |
10466 | between threads</link></title> | |
10467 | <bridgehead renderas="sect3" id="fiber.migration.h0"> | |
10468 | <phrase id="fiber.migration.overview"/><link linkend="fiber.migration.overview">Overview</link> | |
10469 | </bridgehead> | |
10470 | <para> | |
10471 | Each fiber owns a stack and manages its execution state, including all registers | |
10472 | and CPU flags, the instruction pointer and the stack pointer. That means, in | |
10473 | general, a fiber is not bound to a specific thread.<footnote id="fiber.migration.f0"> | |
10474 | <para> | |
10475 | The <quote>main</quote> fiber on each thread, that is, the fiber on which | |
10476 | the thread is launched, cannot migrate to any other thread. Also <emphasis | |
10477 | role="bold">Boost.Fiber</emphasis> implicitly creates a dispatcher fiber | |
10478 | for each thread — this cannot migrate either. | |
10479 | </para> | |
10480 | </footnote><superscript>,</superscript><footnote id="fiber.migration.f1"> | |
10481 | <para> | |
10482 | Of course it would be problematic to migrate a fiber that relies on <link | |
10483 | linkend="thread_local_storage">thread-local storage</link>. | |
10484 | </para> | |
10485 | </footnote> | |
10486 | </para> | |
10487 | <para> | |
10488 | Migrating a fiber from a logical CPU with heavy workload to another logical | |
10489 | CPU with a lighter workload might speed up the overall execution. Note that | |
10490 | in the case of NUMA-architectures, it is not always advisable to migrate data | |
10491 | between threads. Suppose fiber <emphasis>f</emphasis> is running on logical | |
10492 | CPU <emphasis>cpu0</emphasis> which belongs to NUMA node <emphasis>node0</emphasis>. | |
10493 | The data of <emphasis>f</emphasis> are allocated on the physical memory located | |
10494 | at <emphasis>node0</emphasis>. Migrating the fiber from <emphasis>cpu0</emphasis> | |
10495 | to another logical CPU <emphasis>cpuX</emphasis> which is part of a different | |
10496 | NUMA node <emphasis>nodeX</emphasis> might reduce the performance of the application | |
10497 | due to increased latency of memory access. | |
10498 | </para> | |
10499 | <para> | |
10500 | Only fibers that are contained in <link linkend="class_algorithm"><code>algorithm</code></link>’s ready queue can | |
10501 | migrate between threads. You cannot migrate a running fiber, nor one that is | |
10502 | <link linkend="blocking"><emphasis>blocked</emphasis></link>. You cannot migrate | |
10503 | a fiber if its <link linkend="context_is_context"><code>context::is_context()</code></link> method returns <code><phrase | |
10504 | role="keyword">true</phrase></code> for <code><phrase role="identifier">pinned_context</phrase></code>. | |
10505 | </para> | |
10506 | <para> | |
10507 | In <emphasis role="bold">Boost.Fiber</emphasis> a fiber is migrated by invoking | |
10508 | <link linkend="context_detach"><code>context::detach()</code></link> on the thread from which the fiber migrates | |
10509 | and <link linkend="context_attach"><code>context::attach()</code></link> on the thread to which the fiber migrates. | |
10510 | </para> | |
10511 | <para> | |
10512 | Thus, fiber migration is accomplished by sharing state between instances of | |
10513 | a user-coded <link linkend="class_algorithm"><code>algorithm</code></link> implementation running on different threads. | |
10514 | The fiber’s original thread calls <link linkend="algorithm_awakened"><code>algorithm::awakened()</code></link>, passing | |
10515 | the fiber’s <link linkend="class_context"><code>context</code></link><literal>*</literal>. The <code><phrase role="identifier">awakened</phrase><phrase | |
10516 | role="special">()</phrase></code> implementation calls <link linkend="context_detach"><code>context::detach()</code></link>. | |
10517 | </para> | |
10518 | <para> | |
10519 | At some later point, when the same or a different thread calls <link linkend="algorithm_pick_next"><code>algorithm::pick_next()</code></link>, | |
10520 | the <code><phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase></code> | |
10521 | implementation selects a ready fiber and calls <link linkend="context_attach"><code>context::attach()</code></link> on | |
10522 | it before returning it. | |
10523 | </para> | |
10524 | <para> | |
10525 | As stated above, a <code><phrase role="identifier">context</phrase></code> | |
10526 | for which <code><phrase role="identifier">is_context</phrase><phrase role="special">(</phrase><phrase | |
10527 | role="identifier">pinned_context</phrase><phrase role="special">)</phrase> | |
10528 | <phrase role="special">==</phrase> <phrase role="keyword">true</phrase></code> | |
10529 | must never be passed to either <link linkend="context_detach"><code>context::detach()</code></link> or <link linkend="context_attach"><code>context::attach()</code></link>. | |
10530 | It may only be returned from <code><phrase role="identifier">pick_next</phrase><phrase | |
10531 | role="special">()</phrase></code> called by the <emphasis>same</emphasis> thread | |
10532 | that passed that context to <code><phrase role="identifier">awakened</phrase><phrase | |
10533 | role="special">()</phrase></code>. | |
10534 | </para> | |
10535 | <bridgehead renderas="sect3" id="fiber.migration.h1"> | |
10536 | <phrase id="fiber.migration.example_of_work_sharing"/><link linkend="fiber.migration.example_of_work_sharing">Example | |
10537 | of work sharing</link> | |
10538 | </bridgehead> | |
10539 | <para> | |
10540 | In the example <ulink url="../../examples/work_sharing.cpp">work_sharing.cpp</ulink> | |
10541 | multiple worker fibers are created on the main thread. Each fiber gets a character | |
10542 | as parameter at construction. This character is printed out ten times. Between | |
10543 | each iteration the fiber calls <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link>. That puts | |
10544 | the fiber in the ready queue of the fiber-scheduler <emphasis>shared_ready_queue</emphasis>, | |
10545 | running in the current thread. The next fiber ready to be executed is dequeued | |
10546 | from the shared ready queue and resumed by <emphasis>shared_ready_queue</emphasis> | |
10547 | running on <emphasis>any participating thread</emphasis>. | |
10548 | </para> | |
10549 | <para> | |
10550 | All instances of <emphasis>shared_ready_queue</emphasis> share one global concurrent | |
10551 | queue, used as ready queue. This mechanism shares all worker fibers between | |
10552 | all instances of <emphasis>shared_ready_queue</emphasis>, thus between all | |
10553 | participating threads. | |
10554 | </para> | |
10555 | <bridgehead renderas="sect3" id="fiber.migration.h2"> | |
10556 | <phrase id="fiber.migration.setup_of_threads_and_fibers"/><link linkend="fiber.migration.setup_of_threads_and_fibers">Setup | |
10557 | of threads and fibers</link> | |
10558 | </bridgehead> | |
10559 | <para> | |
10560 | In <code><phrase role="identifier">main</phrase><phrase role="special">()</phrase></code> | |
10561 | the fiber-scheduler is installed and the worker fibers and the threads are | |
10562 | launched. | |
10563 | </para> | |
10564 | <para> | |
10565 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">algo</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_work</phrase> <phrase role="special">>();</phrase> <co id="fiber.migration.c0" linkends="fiber.migration.c1" /> | |
10566 | ||
10567 | <phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="keyword">char</phrase> <phrase role="identifier">c</phrase> <phrase role="special">:</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase><phrase role="special">(</phrase><phrase role="string">"abcdefghijklmnopqrstuvwxyz"</phrase><phrase role="special">))</phrase> <phrase role="special">{</phrase> <co id="fiber.migration.c2" linkends="fiber.migration.c3" /> | |
10568 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">([</phrase><phrase role="identifier">c</phrase><phrase role="special">](){</phrase> <phrase role="identifier">whatevah</phrase><phrase role="special">(</phrase> <phrase role="identifier">c</phrase><phrase role="special">);</phrase> <phrase role="special">}).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
10569 | <phrase role="special">++</phrase><phrase role="identifier">fiber_count</phrase><phrase role="special">;</phrase> <co id="fiber.migration.c4" linkends="fiber.migration.c5" /> | |
10570 | <phrase role="special">}</phrase> | |
10571 | <phrase role="identifier">barrier</phrase> <phrase role="identifier">b</phrase><phrase role="special">(</phrase> <phrase role="number">4</phrase><phrase role="special">);</phrase> | |
10572 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">thread</phrase> <phrase role="identifier">threads</phrase><phrase role="special">[]</phrase> <phrase role="special">=</phrase> <phrase role="special">{</phrase> <co id="fiber.migration.c6" linkends="fiber.migration.c7" /> | |
10573 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">thread</phrase><phrase role="special">(</phrase> <phrase role="identifier">thread</phrase><phrase role="special">,</phrase> <phrase role="special">&</phrase> <phrase role="identifier">b</phrase><phrase role="special">),</phrase> | |
10574 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">thread</phrase><phrase role="special">(</phrase> <phrase role="identifier">thread</phrase><phrase role="special">,</phrase> <phrase role="special">&</phrase> <phrase role="identifier">b</phrase><phrase role="special">),</phrase> | |
10575 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">thread</phrase><phrase role="special">(</phrase> <phrase role="identifier">thread</phrase><phrase role="special">,</phrase> <phrase role="special">&</phrase> <phrase role="identifier">b</phrase><phrase role="special">)</phrase> | |
10576 | <phrase role="special">};</phrase> | |
10577 | <phrase role="identifier">b</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> <co id="fiber.migration.c8" linkends="fiber.migration.c9" /> | |
10578 | <phrase role="special">{</phrase> | |
10579 | <phrase role="identifier">lock_t</phrase><co id="fiber.migration.c10" linkends="fiber.migration.c11" /> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx_count</phrase><phrase role="special">);</phrase> | |
10580 | <phrase role="identifier">cnd_count</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="number">0</phrase> <phrase role="special">==</phrase> <phrase role="identifier">fiber_count</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase> <phrase role="special">);</phrase> <co id="fiber.migration.c12" linkends="fiber.migration.c13" /> | |
10581 | <phrase role="special">}</phrase> <co id="fiber.migration.c14" linkends="fiber.migration.c15" /> | |
10582 | <phrase role="identifier">BOOST_ASSERT</phrase><phrase role="special">(</phrase> <phrase role="number">0</phrase> <phrase role="special">==</phrase> <phrase role="identifier">fiber_count</phrase><phrase role="special">);</phrase> | |
10583 | <phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">thread</phrase> <phrase role="special">&</phrase> <phrase role="identifier">t</phrase> <phrase role="special">:</phrase> <phrase role="identifier">threads</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> <co id="fiber.migration.c16" linkends="fiber.migration.c17" /> | |
10584 | <phrase role="identifier">t</phrase><phrase role="special">.</phrase><phrase role="identifier">join</phrase><phrase role="special">();</phrase> | |
10585 | <phrase role="special">}</phrase> | |
10586 | </programlisting> | |
10587 | </para> | |
10588 | <calloutlist> | |
10589 | <callout arearefs="fiber.migration.c0" id="fiber.migration.c1"> | |
10590 | <para> | |
10591 | Install the scheduling algorithm <code><phrase role="identifier">boost</phrase><phrase | |
10592 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
10593 | role="special">::</phrase><phrase role="identifier">algo</phrase><phrase | |
10594 | role="special">::</phrase><phrase role="identifier">shared_work</phrase></code> | |
10595 | in the main thread too, so each new fiber gets launched into the shared | |
10596 | pool. | |
10597 | </para> | |
10598 | </callout> | |
10599 | <callout arearefs="fiber.migration.c2" id="fiber.migration.c3"> | |
10600 | <para> | |
10601 | Launch a number of worker fibers; each worker fiber picks up a character | |
10602 | that is passed as parameter to fiber-function <code><phrase role="identifier">whatevah</phrase></code>. | |
10603 | Each worker fiber gets detached. | |
10604 | </para> | |
10605 | </callout> | |
10606 | <callout arearefs="fiber.migration.c4" id="fiber.migration.c5"> | |
10607 | <para> | |
10608 | Increment fiber counter for each new fiber. | |
10609 | </para> | |
10610 | </callout> | |
10611 | <callout arearefs="fiber.migration.c6" id="fiber.migration.c7"> | |
10612 | <para> | |
10613 | Launch a couple of threads that join the work sharing. | |
10614 | </para> | |
10615 | </callout> | |
10616 | <callout arearefs="fiber.migration.c8" id="fiber.migration.c9"> | |
10617 | <para> | |
10618 | sync with other threads: allow them to start processing | |
10619 | </para> | |
10620 | </callout> | |
10621 | <callout arearefs="fiber.migration.c10" id="fiber.migration.c11"> | |
10622 | <para> | |
10623 | <code><phrase role="identifier">lock_t</phrase></code> is typedef'ed as | |
10624 | <ulink url="http://en.cppreference.com/w/cpp/thread/unique_lock"><code><phrase | |
10625 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
10626 | role="identifier">unique_lock</phrase></code></ulink>< <ulink url="http://en.cppreference.com/w/cpp/thread/mutex"><code><phrase | |
10627 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
10628 | role="identifier">mutex</phrase></code></ulink> > | |
10629 | </para> | |
10630 | </callout> | |
10631 | <callout arearefs="fiber.migration.c12" id="fiber.migration.c13"> | |
10632 | <para> | |
10633 | Suspend main fiber and resume worker fibers in the meanwhile. Main fiber | |
10634 | gets resumed (e.g returns from <code><phrase role="identifier">condition_variable_any</phrase><phrase | |
10635 | role="special">::</phrase><phrase role="identifier">wait</phrase><phrase | |
10636 | role="special">()</phrase></code>) if all worker fibers are complete. | |
10637 | </para> | |
10638 | </callout> | |
10639 | <callout arearefs="fiber.migration.c14" id="fiber.migration.c15"> | |
10640 | <para> | |
10641 | Releasing lock of mtx_count is required before joining the threads, otherwise | |
10642 | the other threads would be blocked inside condition_variable::wait() and | |
10643 | would never return (deadlock). | |
10644 | </para> | |
10645 | </callout> | |
10646 | <callout arearefs="fiber.migration.c16" id="fiber.migration.c17"> | |
10647 | <para> | |
10648 | wait for threads to terminate | |
10649 | </para> | |
10650 | </callout> | |
10651 | </calloutlist> | |
10652 | <para> | |
10653 | The start of the threads is synchronized with a barrier. The main fiber of | |
10654 | each thread (including main thread) is suspended until all worker fibers are | |
10655 | complete. When the main fiber returns from <link linkend="condition_variable_wait"><code>condition_variable::wait()</code></link>, | |
10656 | the thread terminates: the main thread joins all other threads. | |
10657 | </para> | |
10658 | <para> | |
10659 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">thread</phrase><phrase role="special">(</phrase> <phrase role="identifier">barrier</phrase> <phrase role="special">*</phrase> <phrase role="identifier">b</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10660 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ostringstream</phrase> <phrase role="identifier">buffer</phrase><phrase role="special">;</phrase> | |
10661 | <phrase role="identifier">buffer</phrase> <phrase role="special"><<</phrase> <phrase role="string">"thread started "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">this_thread</phrase><phrase role="special">::</phrase><phrase role="identifier">get_id</phrase><phrase role="special">()</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
10662 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">buffer</phrase><phrase role="special">.</phrase><phrase role="identifier">str</phrase><phrase role="special">()</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">flush</phrase><phrase role="special">;</phrase> | |
10663 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">algo</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_work</phrase> <phrase role="special">>();</phrase> <co id="fiber.migration.c18" linkends="fiber.migration.c19" /> | |
10664 | <phrase role="identifier">b</phrase><phrase role="special">-></phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> <co id="fiber.migration.c20" linkends="fiber.migration.c21" /> | |
10665 | <phrase role="identifier">lock_t</phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx_count</phrase><phrase role="special">);</phrase> | |
10666 | <phrase role="identifier">cnd_count</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="number">0</phrase> <phrase role="special">==</phrase> <phrase role="identifier">fiber_count</phrase><phrase role="special">;</phrase> <phrase role="special">}</phrase> <phrase role="special">);</phrase> <co id="fiber.migration.c22" linkends="fiber.migration.c23" /> | |
10667 | <phrase role="identifier">BOOST_ASSERT</phrase><phrase role="special">(</phrase> <phrase role="number">0</phrase> <phrase role="special">==</phrase> <phrase role="identifier">fiber_count</phrase><phrase role="special">);</phrase> | |
10668 | <phrase role="special">}</phrase> | |
10669 | </programlisting> | |
10670 | </para> | |
10671 | <calloutlist> | |
10672 | <callout arearefs="fiber.migration.c18" id="fiber.migration.c19"> | |
10673 | <para> | |
10674 | Install the scheduling algorithm <code><phrase role="identifier">boost</phrase><phrase | |
10675 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
10676 | role="special">::</phrase><phrase role="identifier">algo</phrase><phrase | |
10677 | role="special">::</phrase><phrase role="identifier">shared_work</phrase></code> | |
10678 | in order to join the work sharing. | |
10679 | </para> | |
10680 | </callout> | |
10681 | <callout arearefs="fiber.migration.c20" id="fiber.migration.c21"> | |
10682 | <para> | |
10683 | sync with other threads: allow them to start processing | |
10684 | </para> | |
10685 | </callout> | |
10686 | <callout arearefs="fiber.migration.c22" id="fiber.migration.c23"> | |
10687 | <para> | |
10688 | Suspend main fiber and resume worker fibers in the meanwhile. Main fiber | |
10689 | gets resumed (e.g returns from <code><phrase role="identifier">condition_variable_any</phrase><phrase | |
10690 | role="special">::</phrase><phrase role="identifier">wait</phrase><phrase | |
10691 | role="special">()</phrase></code>) if all worker fibers are complete. | |
10692 | </para> | |
10693 | </callout> | |
10694 | </calloutlist> | |
10695 | <para> | |
10696 | Each worker fiber executes function <code><phrase role="identifier">whatevah</phrase><phrase | |
10697 | role="special">()</phrase></code> with character <code><phrase role="identifier">me</phrase></code> | |
10698 | as parameter. The fiber yields in a loop and prints out a message if it was | |
10699 | migrated to another thread. | |
10700 | </para> | |
10701 | <para> | |
10702 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">whatevah</phrase><phrase role="special">(</phrase> <phrase role="keyword">char</phrase> <phrase role="identifier">me</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10703 | <phrase role="keyword">try</phrase> <phrase role="special">{</phrase> | |
10704 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">thread</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">my_thread</phrase> <phrase role="special">=</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">this_thread</phrase><phrase role="special">::</phrase><phrase role="identifier">get_id</phrase><phrase role="special">();</phrase> <co id="fiber.migration.c24" linkends="fiber.migration.c25" /> | |
10705 | <phrase role="special">{</phrase> | |
10706 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ostringstream</phrase> <phrase role="identifier">buffer</phrase><phrase role="special">;</phrase> | |
10707 | <phrase role="identifier">buffer</phrase> <phrase role="special"><<</phrase> <phrase role="string">"fiber "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">me</phrase> <phrase role="special"><<</phrase> <phrase role="string">" started on thread "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">my_thread</phrase> <phrase role="special"><<</phrase> <phrase role="char">'\n'</phrase><phrase role="special">;</phrase> | |
10708 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">buffer</phrase><phrase role="special">.</phrase><phrase role="identifier">str</phrase><phrase role="special">()</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">flush</phrase><phrase role="special">;</phrase> | |
10709 | <phrase role="special">}</phrase> | |
10710 | <phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="keyword">unsigned</phrase> <phrase role="identifier">i</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> <phrase role="identifier">i</phrase> <phrase role="special"><</phrase> <phrase role="number">10</phrase><phrase role="special">;</phrase> <phrase role="special">++</phrase><phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> <co id="fiber.migration.c26" linkends="fiber.migration.c27" /> | |
10711 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">yield</phrase><phrase role="special">();</phrase> <co id="fiber.migration.c28" linkends="fiber.migration.c29" /> | |
10712 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">thread</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">new_thread</phrase> <phrase role="special">=</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">this_thread</phrase><phrase role="special">::</phrase><phrase role="identifier">get_id</phrase><phrase role="special">();</phrase> <co id="fiber.migration.c30" linkends="fiber.migration.c31" /> | |
10713 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">new_thread</phrase> <phrase role="special">!=</phrase> <phrase role="identifier">my_thread</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> <co id="fiber.migration.c32" linkends="fiber.migration.c33" /> | |
10714 | <phrase role="identifier">my_thread</phrase> <phrase role="special">=</phrase> <phrase role="identifier">new_thread</phrase><phrase role="special">;</phrase> | |
10715 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ostringstream</phrase> <phrase role="identifier">buffer</phrase><phrase role="special">;</phrase> | |
10716 | <phrase role="identifier">buffer</phrase> <phrase role="special"><<</phrase> <phrase role="string">"fiber "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">me</phrase> <phrase role="special"><<</phrase> <phrase role="string">" switched to thread "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">my_thread</phrase> <phrase role="special"><<</phrase> <phrase role="char">'\n'</phrase><phrase role="special">;</phrase> | |
10717 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">buffer</phrase><phrase role="special">.</phrase><phrase role="identifier">str</phrase><phrase role="special">()</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">flush</phrase><phrase role="special">;</phrase> | |
10718 | <phrase role="special">}</phrase> | |
10719 | <phrase role="special">}</phrase> | |
10720 | <phrase role="special">}</phrase> <phrase role="keyword">catch</phrase> <phrase role="special">(</phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10721 | <phrase role="special">}</phrase> | |
10722 | <phrase role="identifier">lock_t</phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx_count</phrase><phrase role="special">);</phrase> | |
10723 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="number">0</phrase> <phrase role="special">==</phrase> <phrase role="special">--</phrase><phrase role="identifier">fiber_count</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> <co id="fiber.migration.c34" linkends="fiber.migration.c35" /> | |
10724 | <phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
10725 | <phrase role="identifier">cnd_count</phrase><phrase role="special">.</phrase><phrase role="identifier">notify_all</phrase><phrase role="special">();</phrase> <co id="fiber.migration.c36" linkends="fiber.migration.c37" /> | |
10726 | <phrase role="special">}</phrase> | |
10727 | <phrase role="special">}</phrase> | |
10728 | </programlisting> | |
10729 | </para> | |
10730 | <calloutlist> | |
10731 | <callout arearefs="fiber.migration.c24" id="fiber.migration.c25"> | |
10732 | <para> | |
10733 | get ID of initial thread | |
10734 | </para> | |
10735 | </callout> | |
10736 | <callout arearefs="fiber.migration.c26" id="fiber.migration.c27"> | |
10737 | <para> | |
10738 | loop ten times | |
10739 | </para> | |
10740 | </callout> | |
10741 | <callout arearefs="fiber.migration.c28" id="fiber.migration.c29"> | |
10742 | <para> | |
10743 | yield to other fibers | |
10744 | </para> | |
10745 | </callout> | |
10746 | <callout arearefs="fiber.migration.c30" id="fiber.migration.c31"> | |
10747 | <para> | |
10748 | get ID of current thread | |
10749 | </para> | |
10750 | </callout> | |
10751 | <callout arearefs="fiber.migration.c32" id="fiber.migration.c33"> | |
10752 | <para> | |
10753 | test if fiber was migrated to another thread | |
10754 | </para> | |
10755 | </callout> | |
10756 | <callout arearefs="fiber.migration.c34" id="fiber.migration.c35"> | |
10757 | <para> | |
10758 | Decrement fiber counter for each completed fiber. | |
10759 | </para> | |
10760 | </callout> | |
10761 | <callout arearefs="fiber.migration.c36" id="fiber.migration.c37"> | |
10762 | <para> | |
10763 | Notify all fibers waiting on <code><phrase role="identifier">cnd_count</phrase></code>. | |
10764 | </para> | |
10765 | </callout> | |
10766 | </calloutlist> | |
10767 | <bridgehead renderas="sect3" id="fiber.migration.h3"> | |
10768 | <phrase id="fiber.migration.scheduling_fibers"/><link linkend="fiber.migration.scheduling_fibers">Scheduling | |
10769 | fibers</link> | |
10770 | </bridgehead> | |
10771 | <para> | |
10772 | The fiber scheduler <code><phrase role="identifier">shared_ready_queue</phrase></code> | |
10773 | is like <code><phrase role="identifier">round_robin</phrase></code>, except | |
10774 | that it shares a common ready queue among all participating threads. A thread | |
10775 | participates in this pool by executing <link linkend="use_scheduling_algorithm"><code>use_scheduling_algorithm()</code></link> | |
10776 | before | |
10777 | any other <emphasis role="bold">Boost.Fiber</emphasis> operation. | |
10778 | </para> | |
10779 | <para> | |
10780 | The important point about the ready queue is that it’s a class static, common | |
10781 | to all instances of shared_ready_queue. Fibers that are enqueued via <link linkend="algorithm_awakened"><code>algorithm::awakened()</code></link> (fibers | |
10782 | that are ready to be resumed) are thus available to all threads. It is required | |
10783 | to reserve a separate, scheduler-specific queue for the thread’s main fiber | |
10784 | and dispatcher fibers: these may <emphasis>not</emphasis> be shared between | |
10785 | threads! When we’re passed either of these fibers, push it there instead of | |
10786 | in the shared queue: it would be Bad News for thread B to retrieve and attempt | |
10787 | to execute thread A’s main fiber. | |
10788 | </para> | |
10789 | <para> | |
10790 | [awakened_ws] | |
10791 | </para> | |
10792 | <para> | |
10793 | When <link linkend="algorithm_pick_next"><code>algorithm::pick_next()</code></link> gets called inside one thread, | |
10794 | a fiber is dequeued from <emphasis>rqueue_</emphasis> and will be resumed in | |
10795 | that thread. | |
10796 | </para> | |
10797 | <para> | |
10798 | [pick_next_ws] | |
10799 | </para> | |
10800 | <para> | |
10801 | The source code above is found in <ulink url="../../examples/work_sharing.cpp">work_sharing.cpp</ulink>. | |
10802 | </para> | |
10803 | </section> | |
10804 | <section id="fiber.callbacks"> | |
10805 | <title><anchor id="callbacks"/><link linkend="fiber.callbacks">Integrating Fibers | |
10806 | with Asynchronous Callbacks</link></title> | |
10807 | <section id="fiber.callbacks.overview"> | |
10808 | <title><link linkend="fiber.callbacks.overview">Overview</link></title> | |
10809 | <para> | |
10810 | One of the primary benefits of <emphasis role="bold">Boost.Fiber</emphasis> | |
10811 | is the ability to use asynchronous operations for efficiency, while at the | |
10812 | same time structuring the calling code <emphasis>as if</emphasis> the operations | |
10813 | were synchronous. Asynchronous operations provide completion notification | |
10814 | in a variety of ways, but most involve a callback function of some kind. | |
10815 | This section discusses tactics for interfacing <emphasis role="bold">Boost.Fiber</emphasis> | |
10816 | with an arbitrary async operation. | |
10817 | </para> | |
10818 | <para> | |
10819 | For purposes of illustration, consider the following hypothetical API: | |
10820 | </para> | |
10821 | <para> | |
10822 | <programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">AsyncAPI</phrase> <phrase role="special">{</phrase> | |
10823 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
10824 | <phrase role="comment">// constructor acquires some resource that can be read and written</phrase> | |
10825 | <phrase role="identifier">AsyncAPI</phrase><phrase role="special">();</phrase> | |
10826 | ||
10827 | <phrase role="comment">// callbacks accept an int error code; 0 == success</phrase> | |
10828 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">errorcode</phrase><phrase role="special">;</phrase> | |
10829 | ||
10830 | <phrase role="comment">// write callback only needs to indicate success or failure</phrase> | |
10831 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
10832 | <phrase role="keyword">void</phrase> <phrase role="identifier">init_write</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">callback</phrase><phrase role="special">);</phrase> | |
10833 | ||
10834 | <phrase role="comment">// read callback needs to accept both errorcode and data</phrase> | |
10835 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
10836 | <phrase role="keyword">void</phrase> <phrase role="identifier">init_read</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">callback</phrase><phrase role="special">);</phrase> | |
10837 | ||
10838 | <phrase role="comment">// ... other operations ...</phrase> | |
10839 | <phrase role="special">};</phrase> | |
10840 | </programlisting> | |
10841 | </para> | |
10842 | <para> | |
10843 | The significant points about each of <code><phrase role="identifier">init_write</phrase><phrase | |
10844 | role="special">()</phrase></code> and <code><phrase role="identifier">init_read</phrase><phrase | |
10845 | role="special">()</phrase></code> are: | |
10846 | </para> | |
10847 | <itemizedlist> | |
10848 | <listitem> | |
10849 | <simpara> | |
10850 | The <code><phrase role="identifier">AsyncAPI</phrase></code> method only | |
10851 | initiates the operation. It returns immediately, while the requested | |
10852 | operation is still pending. | |
10853 | </simpara> | |
10854 | </listitem> | |
10855 | <listitem> | |
10856 | <simpara> | |
10857 | The method accepts a callback. When the operation completes, the callback | |
10858 | is called with relevant parameters (error code, data if applicable). | |
10859 | </simpara> | |
10860 | </listitem> | |
10861 | </itemizedlist> | |
10862 | <para> | |
10863 | We would like to wrap these asynchronous methods in functions that appear | |
10864 | synchronous by blocking the calling fiber until the operation completes. | |
10865 | This lets us use the wrapper function’s return value to deliver relevant data. | |
10866 | </para> | |
10867 | <tip> | |
10868 | <para> | |
10869 | <link linkend="class_promise"><code>promise<></code></link> and <link linkend="class_future"><code>future<></code></link> are your friends | |
10870 | here. | |
10871 | </para> | |
10872 | </tip> | |
10873 | </section> | |
10874 | <section id="fiber.callbacks.return_errorcode"> | |
10875 | <title><link linkend="fiber.callbacks.return_errorcode">Return Errorcode</link></title> | |
10876 | <para> | |
10877 | The <code><phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase | |
10878 | role="identifier">init_write</phrase><phrase role="special">()</phrase></code> | |
10879 | callback passes only an <code><phrase role="identifier">errorcode</phrase></code>. | |
10880 | If we simply want the blocking wrapper to return that <code><phrase role="identifier">errorcode</phrase></code>, | |
10881 | this is an extremely straightforward use of <link linkend="class_promise"><code>promise<></code></link> and | |
10882 | <link linkend="class_future"><code>future<></code></link>: | |
10883 | </para> | |
10884 | <para> | |
10885 | <programlisting><phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">write_ec</phrase><phrase role="special">(</phrase> <phrase role="identifier">AsyncAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10886 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="special">></phrase> <phrase role="identifier">promise</phrase><phrase role="special">;</phrase> | |
10887 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="special">></phrase> <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
10888 | <phrase role="comment">// In general, even though we block waiting for future::get() and therefore</phrase> | |
10889 | <phrase role="comment">// won't destroy 'promise' until promise::set_value() has been called, we</phrase> | |
10890 | <phrase role="comment">// are advised that with threads it's possible for ~promise() to be</phrase> | |
10891 | <phrase role="comment">// entered before promise::set_value() has returned. While that shouldn't</phrase> | |
10892 | <phrase role="comment">// happen with fibers::promise, a robust way to deal with the lifespan</phrase> | |
10893 | <phrase role="comment">// issue is to bind 'promise' into our lambda. Since promise is move-only,</phrase> | |
10894 | <phrase role="comment">// use initialization capture.</phrase> | |
10895 | <phrase role="preprocessor">#if</phrase> <phrase role="special">!</phrase> <phrase role="identifier">defined</phrase><phrase role="special">(</phrase><phrase role="identifier">BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES</phrase><phrase role="special">)</phrase> | |
10896 | <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">init_write</phrase><phrase role="special">(</phrase> | |
10897 | <phrase role="identifier">data</phrase><phrase role="special">,</phrase> | |
10898 | <phrase role="special">[</phrase><phrase role="identifier">promise</phrase><phrase role="special">=</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">)](</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="keyword">mutable</phrase> <phrase role="special">{</phrase> | |
10899 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">);</phrase> | |
10900 | <phrase role="special">});</phrase> | |
10901 | ||
10902 | <phrase role="preprocessor">#else</phrase> <phrase role="comment">// defined(BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES)</phrase> | |
10903 | <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">init_write</phrase><phrase role="special">(</phrase> | |
10904 | <phrase role="identifier">data</phrase><phrase role="special">,</phrase> | |
10905 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">([](</phrase><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">promise</phrase><phrase role="special">,</phrase> | |
10906 | <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10907 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">);</phrase> | |
10908 | <phrase role="special">},</phrase> | |
10909 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">),</phrase> | |
10910 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">placeholders</phrase><phrase role="special">::</phrase><phrase role="identifier">_1</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
10911 | <phrase role="preprocessor">#endif</phrase> <phrase role="comment">// BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES</phrase> | |
10912 | ||
10913 | <phrase role="keyword">return</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">();</phrase> | |
10914 | <phrase role="special">}</phrase> | |
10915 | </programlisting> | |
10916 | </para> | |
10917 | <para> | |
10918 | All we have to do is: | |
10919 | </para> | |
10920 | <orderedlist> | |
10921 | <listitem> | |
10922 | <simpara> | |
10923 | Instantiate a <code><phrase role="identifier">promise</phrase><phrase | |
10924 | role="special"><></phrase></code> of correct type. | |
10925 | </simpara> | |
10926 | </listitem> | |
10927 | <listitem> | |
10928 | <simpara> | |
10929 | Obtain its <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code>. | |
10930 | </simpara> | |
10931 | </listitem> | |
10932 | <listitem> | |
10933 | <simpara> | |
10934 | Arrange for the callback to call <link linkend="promise_set_value"><code>promise::set_value()</code></link>. | |
10935 | </simpara> | |
10936 | </listitem> | |
10937 | <listitem> | |
10938 | <simpara> | |
10939 | Block on <link linkend="future_get"><code>future::get()</code></link>. | |
10940 | </simpara> | |
10941 | </listitem> | |
10942 | </orderedlist> | |
10943 | <note> | |
10944 | <para> | |
10945 | This tactic for resuming a pending fiber works even if the callback is | |
10946 | called on a different thread than the one on which the initiating fiber | |
10947 | is running. In fact, <ulink url="../../examples/adapt_callbacks.cpp">the | |
10948 | example program’s</ulink> dummy <code><phrase role="identifier">AsyncAPI</phrase></code> | |
10949 | implementation illustrates that: it simulates async I/O by launching a | |
10950 | new thread that sleeps briefly and then calls the relevant callback. | |
10951 | </para> | |
10952 | </note> | |
10953 | </section> | |
10954 | <section id="fiber.callbacks.success_or_exception"> | |
10955 | <title><link linkend="fiber.callbacks.success_or_exception">Success or Exception</link></title> | |
10956 | <para> | |
10957 | A wrapper more aligned with modern C++ practice would use an exception, rather | |
10958 | than an <code><phrase role="identifier">errorcode</phrase></code>, to communicate | |
10959 | failure to its caller. This is straightforward to code in terms of <code><phrase | |
10960 | role="identifier">write_ec</phrase><phrase role="special">()</phrase></code>: | |
10961 | </para> | |
10962 | <para> | |
10963 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">write</phrase><phrase role="special">(</phrase> <phrase role="identifier">AsyncAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10964 | <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase> <phrase role="special">=</phrase> <phrase role="identifier">write_ec</phrase><phrase role="special">(</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">data</phrase><phrase role="special">);</phrase> | |
10965 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10966 | <phrase role="keyword">throw</phrase> <phrase role="identifier">make_exception</phrase><phrase role="special">(</phrase><phrase role="string">"write"</phrase><phrase role="special">,</phrase> <phrase role="identifier">ec</phrase><phrase role="special">);</phrase> | |
10967 | <phrase role="special">}</phrase> | |
10968 | <phrase role="special">}</phrase> | |
10969 | </programlisting> | |
10970 | </para> | |
10971 | <para> | |
10972 | The point is that since each fiber has its own stack, you need not repeat | |
10973 | messy boilerplate: normal encapsulation works. | |
10974 | </para> | |
10975 | </section> | |
10976 | <section id="fiber.callbacks.return_errorcode_or_data"> | |
10977 | <title><link linkend="fiber.callbacks.return_errorcode_or_data">Return Errorcode | |
10978 | or Data</link></title> | |
10979 | <para> | |
10980 | Things get a bit more interesting when the async operation’s callback passes | |
10981 | multiple data items of interest. One approach would be to use <code><phrase | |
10982 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">pair</phrase><phrase | |
10983 | role="special"><></phrase></code> to capture both: | |
10984 | </para> | |
10985 | <para> | |
10986 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">pair</phrase><phrase role="special"><</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">read_ec</phrase><phrase role="special">(</phrase> <phrase role="identifier">AsyncAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
10987 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">pair</phrase><phrase role="special"><</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">result_pair</phrase><phrase role="special">;</phrase> | |
10988 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">result_pair</phrase> <phrase role="special">></phrase> <phrase role="identifier">promise</phrase><phrase role="special">;</phrase> | |
10989 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">result_pair</phrase> <phrase role="special">></phrase> <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
10990 | <phrase role="comment">// We promise that both 'promise' and 'future' will survive until our</phrase> | |
10991 | <phrase role="comment">// lambda has been called.</phrase> | |
10992 | <phrase role="preprocessor">#if</phrase> <phrase role="special">!</phrase> <phrase role="identifier">defined</phrase><phrase role="special">(</phrase><phrase role="identifier">BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES</phrase><phrase role="special">)</phrase> | |
10993 | <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">init_read</phrase><phrase role="special">([</phrase><phrase role="identifier">promise</phrase><phrase role="special">=</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">)](</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="keyword">mutable</phrase> <phrase role="special">{</phrase> | |
10994 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">result_pair</phrase><phrase role="special">(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
10995 | <phrase role="special">});</phrase> | |
10996 | <phrase role="preprocessor">#else</phrase> <phrase role="comment">// defined(BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES)</phrase> | |
10997 | <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">init_read</phrase><phrase role="special">(</phrase> | |
10998 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">([](</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">result_pair</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">promise</phrase><phrase role="special">,</phrase> | |
10999 | <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="keyword">mutable</phrase> <phrase role="special">{</phrase> | |
11000 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">result_pair</phrase><phrase role="special">(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11001 | <phrase role="special">},</phrase> | |
11002 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">),</phrase> | |
11003 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">placeholders</phrase><phrase role="special">::</phrase><phrase role="identifier">_1</phrase><phrase role="special">,</phrase> | |
11004 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">placeholders</phrase><phrase role="special">::</phrase><phrase role="identifier">_2</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11005 | <phrase role="preprocessor">#endif</phrase> <phrase role="comment">// BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES</phrase> | |
11006 | <phrase role="keyword">return</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">();</phrase> | |
11007 | <phrase role="special">}</phrase> | |
11008 | </programlisting> | |
11009 | </para> | |
11010 | <para> | |
11011 | Once you bundle the interesting data in <code><phrase role="identifier">std</phrase><phrase | |
11012 | role="special">::</phrase><phrase role="identifier">pair</phrase><phrase | |
11013 | role="special"><></phrase></code>, the code is effectively identical | |
11014 | to <code><phrase role="identifier">write_ec</phrase><phrase role="special">()</phrase></code>. | |
11015 | You can call it like this: | |
11016 | </para> | |
11017 | <para> | |
11018 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">tie</phrase><phrase role="special">(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="identifier">read_ec</phrase><phrase role="special">(</phrase> <phrase role="identifier">api</phrase><phrase role="special">);</phrase> | |
11019 | </programlisting> | |
11020 | </para> | |
11021 | </section> | |
11022 | <section id="fiber.callbacks.data_or_exception"> | |
11023 | <title><anchor id="Data_or_Exception"/><link linkend="fiber.callbacks.data_or_exception">Data | |
11024 | or Exception</link></title> | |
11025 | <para> | |
11026 | But a more natural API for a function that obtains data is to return only | |
11027 | the data on success, throwing an exception on error. | |
11028 | </para> | |
11029 | <para> | |
11030 | As with <code><phrase role="identifier">write</phrase><phrase role="special">()</phrase></code> | |
11031 | above, it’s certainly possible to code a <code><phrase role="identifier">read</phrase><phrase | |
11032 | role="special">()</phrase></code> wrapper in terms of <code><phrase role="identifier">read_ec</phrase><phrase | |
11033 | role="special">()</phrase></code>. But since a given application is unlikely | |
11034 | to need both, let’s code <code><phrase role="identifier">read</phrase><phrase | |
11035 | role="special">()</phrase></code> from scratch, leveraging <link linkend="promise_set_exception"><code>promise::set_exception()</code></link>: | |
11036 | </para> | |
11037 | <para> | |
11038 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">read</phrase><phrase role="special">(</phrase> <phrase role="identifier">AsyncAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11039 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">promise</phrase><phrase role="special">;</phrase> | |
11040 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
11041 | <phrase role="comment">// Both 'promise' and 'future' will survive until our lambda has been</phrase> | |
11042 | <phrase role="comment">// called.</phrase> | |
11043 | <phrase role="preprocessor">#if</phrase> <phrase role="special">!</phrase> <phrase role="identifier">defined</phrase><phrase role="special">(</phrase><phrase role="identifier">BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES</phrase><phrase role="special">)</phrase> | |
11044 | <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">init_read</phrase><phrase role="special">([&</phrase><phrase role="identifier">promise</phrase><phrase role="special">](</phrase> <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="keyword">mutable</phrase> <phrase role="special">{</phrase> | |
11045 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11046 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">data</phrase><phrase role="special">);</phrase> | |
11047 | <phrase role="special">}</phrase> <phrase role="keyword">else</phrase> <phrase role="special">{</phrase> | |
11048 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_exception</phrase><phrase role="special">(</phrase> | |
11049 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_exception_ptr</phrase><phrase role="special">(</phrase> | |
11050 | <phrase role="identifier">make_exception</phrase><phrase role="special">(</phrase><phrase role="string">"read"</phrase><phrase role="special">,</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11051 | <phrase role="special">}</phrase> | |
11052 | <phrase role="special">});</phrase> | |
11053 | <phrase role="preprocessor">#else</phrase> <phrase role="comment">// defined(BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES)</phrase> | |
11054 | <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">init_read</phrase><phrase role="special">(</phrase> | |
11055 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">([](</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">promise</phrase><phrase role="special">,</phrase> | |
11056 | <phrase role="identifier">AsyncAPI</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="keyword">mutable</phrase> <phrase role="special">{</phrase> | |
11057 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11058 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">data</phrase><phrase role="special">);</phrase> | |
11059 | <phrase role="special">}</phrase> <phrase role="keyword">else</phrase> <phrase role="special">{</phrase> | |
11060 | <phrase role="identifier">promise</phrase><phrase role="special">.</phrase><phrase role="identifier">set_exception</phrase><phrase role="special">(</phrase> | |
11061 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_exception_ptr</phrase><phrase role="special">(</phrase> | |
11062 | <phrase role="identifier">make_exception</phrase><phrase role="special">(</phrase><phrase role="string">"read"</phrase><phrase role="special">,</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11063 | <phrase role="special">}</phrase> | |
11064 | <phrase role="special">},</phrase> | |
11065 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">promise</phrase><phrase role="special">),</phrase> | |
11066 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">placeholders</phrase><phrase role="special">::</phrase><phrase role="identifier">_1</phrase><phrase role="special">,</phrase> | |
11067 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">placeholders</phrase><phrase role="special">::</phrase><phrase role="identifier">_2</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11068 | <phrase role="preprocessor">#endif</phrase> <phrase role="comment">// BOOST_NO_CXX14_INITIALIZED_LAMBDA_CAPTURES</phrase> | |
11069 | <phrase role="keyword">return</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">();</phrase> | |
11070 | <phrase role="special">}</phrase> | |
11071 | </programlisting> | |
11072 | </para> | |
11073 | <para> | |
11074 | <link linkend="future_get"><code>future::get()</code></link> will do the right thing, either returning <code><phrase | |
11075 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase></code> | |
11076 | or throwing an exception. | |
11077 | </para> | |
11078 | </section> | |
11079 | <section id="fiber.callbacks.success_error_virtual_methods"> | |
11080 | <title><link linkend="fiber.callbacks.success_error_virtual_methods">Success/Error | |
11081 | Virtual Methods</link></title> | |
11082 | <para> | |
11083 | One classic approach to completion notification is to define an abstract | |
11084 | base class with <code><phrase role="identifier">success</phrase><phrase role="special">()</phrase></code> | |
11085 | and <code><phrase role="identifier">error</phrase><phrase role="special">()</phrase></code> | |
11086 | methods. Code wishing to perform async I/O must derive a subclass, override | |
11087 | each of these methods and pass the async operation a pointer to a subclass | |
11088 | instance. The abstract base class might look like this: | |
11089 | </para> | |
11090 | <para> | |
11091 | <programlisting><phrase role="comment">// every async operation receives a subclass instance of this abstract base</phrase> | |
11092 | <phrase role="comment">// class through which to communicate its result</phrase> | |
11093 | <phrase role="keyword">struct</phrase> <phrase role="identifier">Response</phrase> <phrase role="special">{</phrase> | |
11094 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">Response</phrase> <phrase role="special">></phrase> <phrase role="identifier">ptr</phrase><phrase role="special">;</phrase> | |
11095 | ||
11096 | <phrase role="comment">// called if the operation succeeds</phrase> | |
11097 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">success</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
11098 | ||
11099 | <phrase role="comment">// called if the operation fails</phrase> | |
11100 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">error</phrase><phrase role="special">(</phrase> <phrase role="identifier">AsyncAPIBase</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
11101 | <phrase role="special">};</phrase> | |
11102 | </programlisting> | |
11103 | </para> | |
11104 | <para> | |
11105 | Now the <code><phrase role="identifier">AsyncAPI</phrase></code> operation | |
11106 | might look more like this: | |
11107 | </para> | |
11108 | <para> | |
11109 | <programlisting><phrase role="comment">// derive Response subclass, instantiate, pass Response::ptr</phrase> | |
11110 | <phrase role="keyword">void</phrase> <phrase role="identifier">init_read</phrase><phrase role="special">(</phrase> <phrase role="identifier">Response</phrase><phrase role="special">::</phrase><phrase role="identifier">ptr</phrase><phrase role="special">);</phrase> | |
11111 | </programlisting> | |
11112 | </para> | |
11113 | <para> | |
11114 | We can address this by writing a one-size-fits-all <code><phrase role="identifier">PromiseResponse</phrase></code>: | |
11115 | </para> | |
11116 | <para> | |
11117 | <programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">PromiseResponse</phrase><phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">Response</phrase> <phrase role="special">{</phrase> | |
11118 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11119 | <phrase role="comment">// called if the operation succeeds</phrase> | |
11120 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">success</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11121 | <phrase role="identifier">promise_</phrase><phrase role="special">.</phrase><phrase role="identifier">set_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">data</phrase><phrase role="special">);</phrase> | |
11122 | <phrase role="special">}</phrase> | |
11123 | ||
11124 | <phrase role="comment">// called if the operation fails</phrase> | |
11125 | <phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">error</phrase><phrase role="special">(</phrase> <phrase role="identifier">AsyncAPIBase</phrase><phrase role="special">::</phrase><phrase role="identifier">errorcode</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11126 | <phrase role="identifier">promise_</phrase><phrase role="special">.</phrase><phrase role="identifier">set_exception</phrase><phrase role="special">(</phrase> | |
11127 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_exception_ptr</phrase><phrase role="special">(</phrase> | |
11128 | <phrase role="identifier">make_exception</phrase><phrase role="special">(</phrase><phrase role="string">"read"</phrase><phrase role="special">,</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11129 | <phrase role="special">}</phrase> | |
11130 | ||
11131 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">get_future</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
11132 | <phrase role="keyword">return</phrase> <phrase role="identifier">promise_</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">();</phrase> | |
11133 | <phrase role="special">}</phrase> | |
11134 | ||
11135 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
11136 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">promise</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">promise_</phrase><phrase role="special">;</phrase> | |
11137 | <phrase role="special">};</phrase> | |
11138 | </programlisting> | |
11139 | </para> | |
11140 | <para> | |
11141 | Now we can simply obtain the <code><phrase role="identifier">future</phrase><phrase | |
11142 | role="special"><></phrase></code> from that <code><phrase role="identifier">PromiseResponse</phrase></code> | |
11143 | and wait on its <code><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code>: | |
11144 | </para> | |
11145 | <para> | |
11146 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">read</phrase><phrase role="special">(</phrase> <phrase role="identifier">AsyncAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11147 | <phrase role="comment">// Because init_read() requires a shared_ptr, we must allocate our</phrase> | |
11148 | <phrase role="comment">// ResponsePromise on the heap, even though we know its lifespan.</phrase> | |
11149 | <phrase role="keyword">auto</phrase> <phrase role="identifier">promisep</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">PromiseResponse</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
11150 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">promisep</phrase><phrase role="special">-></phrase><phrase role="identifier">get_future</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
11151 | <phrase role="comment">// Both 'promisep' and 'future' will survive until our lambda has been</phrase> | |
11152 | <phrase role="comment">// called.</phrase> | |
11153 | <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">init_read</phrase><phrase role="special">(</phrase> <phrase role="identifier">promisep</phrase><phrase role="special">);</phrase> | |
11154 | <phrase role="keyword">return</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">();</phrase> | |
11155 | <phrase role="special">}</phrase> | |
11156 | </programlisting> | |
11157 | </para> | |
11158 | <para> | |
11159 | The source code above is found in <ulink url="../../examples/adapt_callbacks.cpp">adapt_callbacks.cpp</ulink> | |
11160 | and <ulink url="../../examples/adapt_method_calls.cpp">adapt_method_calls.cpp</ulink>. | |
11161 | </para> | |
11162 | </section> | |
11163 | <section id="fiber.callbacks.then_there_s____boost_asio__"> | |
11164 | <title><anchor id="callbacks_asio"/><link linkend="fiber.callbacks.then_there_s____boost_asio__">Then | |
11165 | There’s <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink></link></title> | |
11166 | <para> | |
11167 | Since the simplest form of Boost.Asio asynchronous operation completion token | |
11168 | is a callback function, we could apply the same tactics for Asio as for our | |
11169 | hypothetical <code><phrase role="identifier">AsyncAPI</phrase></code> asynchronous | |
11170 | operations. | |
11171 | </para> | |
11172 | <para> | |
11173 | Fortunately we need not. Boost.Asio incorporates a mechanism<footnote id="fiber.callbacks.then_there_s____boost_asio__.f0"> | |
11174 | <para> | |
11175 | This mechanism has been proposed as a conventional way to allow the caller | |
11176 | of an arbitrary async function to specify completion handling: <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4045.pdf">N4045</ulink>. | |
11177 | </para> | |
11178 | </footnote> by which the caller can customize the notification behavior of | |
11179 | any async operation. Therefore we can construct a <emphasis>completion token</emphasis> | |
11180 | which, when passed to a <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink> | |
11181 | async operation, requests blocking for the calling fiber. | |
11182 | </para> | |
11183 | <para> | |
11184 | A typical Asio async function might look something like this:<footnote id="fiber.callbacks.then_there_s____boost_asio__.f1"> | |
11185 | <para> | |
11186 | per <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4045.pdf">N4045</ulink> | |
11187 | </para> | |
11188 | </footnote> | |
11189 | </para> | |
11190 | <programlisting><phrase role="keyword">template</phrase> <phrase role="special"><</phrase> <phrase role="special">...,</phrase> <phrase role="keyword">class</phrase> <phrase role="identifier">CompletionToken</phrase> <phrase role="special">></phrase> | |
11191 | <emphasis>deduced_return_type</emphasis> | |
11192 | <phrase role="identifier">async_something</phrase><phrase role="special">(</phrase> <phrase role="special">...</phrase> <phrase role="special">,</phrase> <phrase role="identifier">CompletionToken</phrase><phrase role="special">&&</phrase> <phrase role="identifier">token</phrase><phrase role="special">)</phrase> | |
11193 | <phrase role="special">{</phrase> | |
11194 | <phrase role="comment">// construct handler_type instance from CompletionToken</phrase> | |
11195 | <phrase role="identifier">handler_type</phrase><phrase role="special"><</phrase><phrase role="identifier">CompletionToken</phrase><phrase role="special">,</phrase> <phrase role="special">...>::</phrase><phrase role="identifier">type</phrase> <emphasis role="bold"><!--quickbook-escape-prefix--><code><!--quickbook-escape-postfix-->handler(token)<!--quickbook-escape-prefix--></code><!--quickbook-escape-postfix--></emphasis><phrase role="special">;</phrase> | |
11196 | <phrase role="comment">// construct async_result instance from handler_type</phrase> | |
11197 | <phrase role="identifier">async_result</phrase><phrase role="special"><</phrase><phrase role="keyword">decltype</phrase><phrase role="special">(</phrase><phrase role="identifier">handler</phrase><phrase role="special">)></phrase> <emphasis role="bold"><!--quickbook-escape-prefix--><code><!--quickbook-escape-postfix-->result(handler)<!--quickbook-escape-prefix--></code><!--quickbook-escape-postfix--></emphasis><phrase role="special">;</phrase> | |
11198 | ||
11199 | <phrase role="comment">// ... arrange to call handler on completion ...</phrase> | |
11200 | <phrase role="comment">// ... initiate actual I/O operation ...</phrase> | |
11201 | ||
11202 | <phrase role="keyword">return</phrase> <emphasis role="bold"><!--quickbook-escape-prefix--><code><!--quickbook-escape-postfix-->result.get()<!--quickbook-escape-prefix--></code><!--quickbook-escape-postfix--></emphasis><phrase role="special">;</phrase> | |
11203 | <phrase role="special">}</phrase> | |
11204 | </programlisting> | |
11205 | <para> | |
11206 | We will engage that mechanism, which is based on specializing Asio’s <code><phrase | |
11207 | role="identifier">handler_type</phrase><phrase role="special"><></phrase></code> | |
11208 | template for the <code><phrase role="identifier">CompletionToken</phrase></code> | |
11209 | type and the signature of the specific callback. The remainder of this discussion | |
11210 | will refer back to <code><phrase role="identifier">async_something</phrase><phrase | |
11211 | role="special">()</phrase></code> as the Asio async function under consideration. | |
11212 | </para> | |
11213 | <para> | |
11214 | The implementation described below uses lower-level facilities than <code><phrase | |
11215 | role="identifier">promise</phrase></code> and <code><phrase role="identifier">future</phrase></code> | |
11216 | because the <code><phrase role="identifier">promise</phrase></code> mechanism | |
11217 | interacts badly with <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/stop.html"><code><phrase | |
11218 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
11219 | role="identifier">stop</phrase><phrase role="special">()</phrase></code></ulink>. | |
11220 | It produces <code><phrase role="identifier">broken_promise</phrase></code> | |
11221 | exceptions. | |
11222 | </para> | |
11223 | <para> | |
11224 | <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
11225 | role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase | |
11226 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
11227 | role="identifier">yield</phrase></code> is a completion token of this kind. | |
11228 | <code><phrase role="identifier">yield</phrase></code> is an instance of | |
11229 | <code><phrase role="identifier">yield_t</phrase></code>: | |
11230 | </para> | |
11231 | <para> | |
11232 | <programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">yield_t</phrase> <phrase role="special">{</phrase> | |
11233 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11234 | <phrase role="identifier">yield_t</phrase><phrase role="special">()</phrase> <phrase role="special">=</phrase> <phrase role="keyword">default</phrase><phrase role="special">;</phrase> | |
11235 | ||
11236 | <phrase role="comment">/** | |
11237 | * @code | |
11238 | * static yield_t yield; | |
11239 | * boost::system::error_code myec; | |
11240 | * func(yield[myec]); | |
11241 | * @endcode | |
11242 | * @c yield[myec] returns an instance of @c yield_t whose @c ec_ points | |
11243 | * to @c myec. The expression @c yield[myec] "binds" @c myec to that | |
11244 | * (anonymous) @c yield_t instance, instructing @c func() to store any | |
11245 | * @c error_code it might produce into @c myec rather than throwing @c | |
11246 | * boost::system::system_error. | |
11247 | */</phrase> | |
11248 | <phrase role="identifier">yield_t</phrase> <phrase role="keyword">operator</phrase><phrase role="special">[](</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase> <phrase role="special">&</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="keyword">const</phrase> <phrase role="special">{</phrase> | |
11249 | <phrase role="identifier">yield_t</phrase> <phrase role="identifier">tmp</phrase><phrase role="special">;</phrase> | |
11250 | <phrase role="identifier">tmp</phrase><phrase role="special">.</phrase><phrase role="identifier">ec_</phrase> <phrase role="special">=</phrase> <phrase role="special">&</phrase> <phrase role="identifier">ec</phrase><phrase role="special">;</phrase> | |
11251 | <phrase role="keyword">return</phrase> <phrase role="identifier">tmp</phrase><phrase role="special">;</phrase> | |
11252 | <phrase role="special">}</phrase> | |
11253 | ||
11254 | <phrase role="comment">//private:</phrase> | |
11255 | <phrase role="comment">// ptr to bound error_code instance if any</phrase> | |
11256 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ec_</phrase><phrase role="special">{</phrase> <phrase role="keyword">nullptr</phrase> <phrase role="special">};</phrase> | |
11257 | <phrase role="special">};</phrase> | |
11258 | </programlisting> | |
11259 | </para> | |
11260 | <para> | |
11261 | <code><phrase role="identifier">yield_t</phrase></code> is in fact only a | |
11262 | placeholder, a way to trigger Boost.Asio customization. It can bind a <ulink | |
11263 | url="http://www.boost.org/doc/libs/release/libs/system/doc/reference.html#Class-error_code"><code><phrase | |
11264 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
11265 | role="identifier">system</phrase><phrase role="special">::</phrase><phrase | |
11266 | role="identifier">error_code</phrase></code></ulink> for use by the actual | |
11267 | handler. | |
11268 | </para> | |
11269 | <para> | |
11270 | <code><phrase role="identifier">yield</phrase></code> is declared as: | |
11271 | </para> | |
11272 | <para> | |
11273 | <programlisting><phrase role="comment">// canonical instance</phrase> | |
11274 | <phrase role="keyword">thread_local</phrase> <phrase role="identifier">yield_t</phrase> <phrase role="identifier">yield</phrase><phrase role="special">{};</phrase> | |
11275 | </programlisting> | |
11276 | </para> | |
11277 | <para> | |
11278 | Asio customization is engaged by specializing <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/handler_type.html"><code><phrase | |
11279 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
11280 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
11281 | role="identifier">handler_type</phrase><phrase role="special"><></phrase></code></ulink> | |
11282 | for <code><phrase role="identifier">yield_t</phrase></code>: | |
11283 | </para> | |
11284 | <para> | |
11285 | <programlisting><phrase role="comment">// Handler type specialisation for fibers::asio::yield.</phrase> | |
11286 | <phrase role="comment">// When 'yield' is passed as a completion handler which accepts only</phrase> | |
11287 | <phrase role="comment">// error_code, use yield_handler<void>. yield_handler will take care of the</phrase> | |
11288 | <phrase role="comment">// error_code one way or another.</phrase> | |
11289 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">ReturnType</phrase> <phrase role="special">></phrase> | |
11290 | <phrase role="keyword">struct</phrase> <phrase role="identifier">handler_type</phrase><phrase role="special"><</phrase> <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">yield_t</phrase><phrase role="special">,</phrase> <phrase role="identifier">ReturnType</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase><phrase role="special">)</phrase> <phrase role="special">></phrase> | |
11291 | <phrase role="special">{</phrase> <phrase role="keyword">typedef</phrase> <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase> <phrase role="keyword">void</phrase> <phrase role="special">></phrase> <phrase role="identifier">type</phrase><phrase role="special">;</phrase> <phrase role="special">};</phrase> | |
11292 | </programlisting> | |
11293 | </para> | |
11294 | <para> | |
11295 | (There are actually four different specializations in <ulink url="../../examples/asio/detail/yield.hpp">detail/yield.hpp</ulink>, | |
11296 | one for each of the four Asio async callback signatures we expect.) | |
11297 | </para> | |
11298 | <para> | |
11299 | The above directs Asio to use <code><phrase role="identifier">yield_handler</phrase></code> | |
11300 | as the actual handler for an async operation to which <code><phrase role="identifier">yield</phrase></code> | |
11301 | is passed. There’s a generic <code><phrase role="identifier">yield_handler</phrase><phrase | |
11302 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase role="special">></phrase></code> | |
11303 | implementation and a <code><phrase role="identifier">yield_handler</phrase><phrase | |
11304 | role="special"><</phrase><phrase role="keyword">void</phrase><phrase role="special">></phrase></code> | |
11305 | specialization. Let’s start with the <code><phrase role="special"><</phrase><phrase | |
11306 | role="keyword">void</phrase><phrase role="special">></phrase></code> specialization: | |
11307 | </para> | |
11308 | <para> | |
11309 | <programlisting><phrase role="comment">// yield_handler<void> is like yield_handler<T> without value_. In fact it's</phrase> | |
11310 | <phrase role="comment">// just like yield_handler_base.</phrase> | |
11311 | <phrase role="keyword">template</phrase><phrase role="special"><></phrase> | |
11312 | <phrase role="keyword">class</phrase> <phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase> <phrase role="keyword">void</phrase> <phrase role="special">>:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">yield_handler_base</phrase> <phrase role="special">{</phrase> | |
11313 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11314 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">yield_handler</phrase><phrase role="special">(</phrase> <phrase role="identifier">yield_t</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">y</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
11315 | <phrase role="identifier">yield_handler_base</phrase><phrase role="special">{</phrase> <phrase role="identifier">y</phrase> <phrase role="special">}</phrase> <phrase role="special">{</phrase> | |
11316 | <phrase role="special">}</phrase> | |
11317 | ||
11318 | <phrase role="comment">// nullary completion callback</phrase> | |
11319 | <phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()()</phrase> <phrase role="special">{</phrase> | |
11320 | <phrase role="special">(</phrase> <phrase role="special">*</phrase> <phrase role="keyword">this</phrase><phrase role="special">)(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
11321 | <phrase role="special">}</phrase> | |
11322 | ||
11323 | <phrase role="comment">// inherit operator()(error_code) overload from base class</phrase> | |
11324 | <phrase role="keyword">using</phrase> <phrase role="identifier">yield_handler_base</phrase><phrase role="special">::</phrase><phrase role="keyword">operator</phrase><phrase role="special">();</phrase> | |
11325 | <phrase role="special">};</phrase> | |
11326 | </programlisting> | |
11327 | </para> | |
11328 | <para> | |
11329 | <code><phrase role="identifier">async_something</phrase><phrase role="special">()</phrase></code>, | |
11330 | having consulted the <code><phrase role="identifier">handler_type</phrase><phrase | |
11331 | role="special"><></phrase></code> traits specialization, instantiates | |
11332 | a <code><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11333 | role="keyword">void</phrase><phrase role="special">></phrase></code> to | |
11334 | be passed as the actual callback for the async operation. <code><phrase role="identifier">yield_handler</phrase></code>’s | |
11335 | constructor accepts the <code><phrase role="identifier">yield_t</phrase></code> | |
11336 | instance (the <code><phrase role="identifier">yield</phrase></code> object | |
11337 | passed to the async function) and passes it along to <code><phrase role="identifier">yield_handler_base</phrase></code>: | |
11338 | </para> | |
11339 | <para> | |
11340 | <programlisting><phrase role="comment">// This class encapsulates common elements between yield_handler<T> (capturing</phrase> | |
11341 | <phrase role="comment">// a value to return from asio async function) and yield_handler<void> (no</phrase> | |
11342 | <phrase role="comment">// such value). See yield_handler<T> and its <void> specialization below. Both</phrase> | |
11343 | <phrase role="comment">// yield_handler<T> and yield_handler<void> are passed by value through</phrase> | |
11344 | <phrase role="comment">// various layers of asio functions. In other words, they're potentially</phrase> | |
11345 | <phrase role="comment">// copied multiple times. So key data such as the yield_completion instance</phrase> | |
11346 | <phrase role="comment">// must be stored in our async_result<yield_handler<>> specialization, which</phrase> | |
11347 | <phrase role="comment">// should be instantiated only once.</phrase> | |
11348 | <phrase role="keyword">class</phrase> <phrase role="identifier">yield_handler_base</phrase> <phrase role="special">{</phrase> | |
11349 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11350 | <phrase role="identifier">yield_handler_base</phrase><phrase role="special">(</phrase> <phrase role="identifier">yield_t</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">y</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
11351 | <phrase role="comment">// capture the context* associated with the running fiber</phrase> | |
11352 | <phrase role="identifier">ctx_</phrase><phrase role="special">{</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">active</phrase><phrase role="special">()</phrase> <phrase role="special">},</phrase> | |
11353 | <phrase role="comment">// capture the passed yield_t</phrase> | |
11354 | <phrase role="identifier">yt_</phrase><phrase role="special">(</phrase> <phrase role="identifier">y</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11355 | <phrase role="special">}</phrase> | |
11356 | ||
11357 | <phrase role="comment">// completion callback passing only (error_code)</phrase> | |
11358 | <phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11359 | <phrase role="identifier">BOOST_ASSERT_MSG</phrase><phrase role="special">(</phrase> <phrase role="identifier">ycomp_</phrase><phrase role="special">,</phrase> | |
11360 | <phrase role="string">"Must inject yield_completion* "</phrase> | |
11361 | <phrase role="string">"before calling yield_handler_base::operator()()"</phrase><phrase role="special">);</phrase> | |
11362 | <phrase role="identifier">BOOST_ASSERT_MSG</phrase><phrase role="special">(</phrase> <phrase role="identifier">yt_</phrase><phrase role="special">.</phrase><phrase role="identifier">ec_</phrase><phrase role="special">,</phrase> | |
11363 | <phrase role="string">"Must inject boost::system::error_code* "</phrase> | |
11364 | <phrase role="string">"before calling yield_handler_base::operator()()"</phrase><phrase role="special">);</phrase> | |
11365 | <phrase role="comment">// If originating fiber is busy testing completed_ flag, wait until it</phrase> | |
11366 | <phrase role="comment">// has observed (! completed_).</phrase> | |
11367 | <phrase role="identifier">yield_completion</phrase><phrase role="special">::</phrase><phrase role="identifier">lock_t</phrase> <phrase role="identifier">lk</phrase><phrase role="special">{</phrase> <phrase role="identifier">ycomp_</phrase><phrase role="special">-></phrase><phrase role="identifier">mtx_</phrase> <phrase role="special">};</phrase> | |
11368 | <phrase role="comment">// Notify a subsequent yield_completion::wait() call that it need not</phrase> | |
11369 | <phrase role="comment">// suspend.</phrase> | |
11370 | <phrase role="identifier">ycomp_</phrase><phrase role="special">-></phrase><phrase role="identifier">completed_</phrase> <phrase role="special">=</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
11371 | <phrase role="comment">// set the error_code bound by yield_t</phrase> | |
11372 | <phrase role="special">*</phrase> <phrase role="identifier">yt_</phrase><phrase role="special">.</phrase><phrase role="identifier">ec_</phrase> <phrase role="special">=</phrase> <phrase role="identifier">ec</phrase><phrase role="special">;</phrase> | |
11373 | <phrase role="comment">// If ctx_ is still active, e.g. because the async operation</phrase> | |
11374 | <phrase role="comment">// immediately called its callback (this method!) before the asio</phrase> | |
11375 | <phrase role="comment">// async function called async_result_base::get(), we must not set it</phrase> | |
11376 | <phrase role="comment">// ready.</phrase> | |
11377 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">active</phrase><phrase role="special">()</phrase> <phrase role="special">!=</phrase> <phrase role="identifier">ctx_</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11378 | <phrase role="comment">// wake the fiber</phrase> | |
11379 | <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">active</phrase><phrase role="special">()-></phrase><phrase role="identifier">set_ready</phrase><phrase role="special">(</phrase> <phrase role="identifier">ctx_</phrase><phrase role="special">);</phrase> | |
11380 | <phrase role="special">}</phrase> | |
11381 | <phrase role="special">}</phrase> | |
11382 | ||
11383 | <phrase role="comment">//private:</phrase> | |
11384 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ctx_</phrase><phrase role="special">;</phrase> | |
11385 | <phrase role="identifier">yield_t</phrase> <phrase role="identifier">yt_</phrase><phrase role="special">;</phrase> | |
11386 | <phrase role="comment">// We depend on this pointer to yield_completion, which will be injected</phrase> | |
11387 | <phrase role="comment">// by async_result.</phrase> | |
11388 | <phrase role="identifier">yield_completion</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ycomp_</phrase><phrase role="special">{</phrase> <phrase role="keyword">nullptr</phrase> <phrase role="special">};</phrase> | |
11389 | <phrase role="special">};</phrase> | |
11390 | </programlisting> | |
11391 | </para> | |
11392 | <para> | |
11393 | <code><phrase role="identifier">yield_handler_base</phrase></code> stores | |
11394 | a copy of the <code><phrase role="identifier">yield_t</phrase></code> instance | |
11395 | — which, as shown above, contains only an <code><phrase role="identifier">error_code</phrase><phrase | |
11396 | role="special">*</phrase></code>. It also captures the <link linkend="class_context"><code>context</code></link>* | |
11397 | for the currently-running fiber by calling <link linkend="context_active"><code>context::active()</code></link>. | |
11398 | </para> | |
11399 | <para> | |
11400 | You will notice that <code><phrase role="identifier">yield_handler_base</phrase></code> | |
11401 | has one more data member (<code><phrase role="identifier">ycomp_</phrase></code>) | |
11402 | that is initialized to <code><phrase role="keyword">nullptr</phrase></code> | |
11403 | by its constructor — though its <code><phrase role="keyword">operator</phrase><phrase | |
11404 | role="special">()()</phrase></code> method relies on <code><phrase role="identifier">ycomp_</phrase></code> | |
11405 | being non-null. More on this in a moment. | |
11406 | </para> | |
11407 | <para> | |
11408 | Having constructed the <code><phrase role="identifier">yield_handler</phrase><phrase | |
11409 | role="special"><</phrase><phrase role="keyword">void</phrase><phrase role="special">></phrase></code> | |
11410 | instance, <code><phrase role="identifier">async_something</phrase><phrase | |
11411 | role="special">()</phrase></code> goes on to construct an <code><phrase role="identifier">async_result</phrase></code> | |
11412 | specialized for the <code><phrase role="identifier">handler_type</phrase><phrase | |
11413 | role="special"><>::</phrase><phrase role="identifier">type</phrase></code>: | |
11414 | in this case, <code><phrase role="identifier">async_result</phrase><phrase | |
11415 | role="special"><</phrase><phrase role="identifier">yield_handler</phrase><phrase | |
11416 | role="special"><</phrase><phrase role="keyword">void</phrase><phrase role="special">>></phrase></code>. | |
11417 | It passes the <code><phrase role="identifier">yield_handler</phrase><phrase | |
11418 | role="special"><</phrase><phrase role="keyword">void</phrase><phrase role="special">></phrase></code> | |
11419 | instance to the new <code><phrase role="identifier">async_result</phrase></code> | |
11420 | instance. | |
11421 | </para> | |
11422 | <para> | |
11423 | <programlisting><phrase role="comment">// Without the need to handle a passed value, our yield_handler<void></phrase> | |
11424 | <phrase role="comment">// specialization is just like async_result_base.</phrase> | |
11425 | <phrase role="keyword">template</phrase><phrase role="special"><></phrase> | |
11426 | <phrase role="keyword">class</phrase> <phrase role="identifier">async_result</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase> <phrase role="keyword">void</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="special">:</phrase> | |
11427 | <phrase role="keyword">public</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">async_result_base</phrase> <phrase role="special">{</phrase> | |
11428 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11429 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">type</phrase><phrase role="special">;</phrase> | |
11430 | ||
11431 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">async_result</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase> <phrase role="keyword">void</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">h</phrase><phrase role="special">):</phrase> | |
11432 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">async_result_base</phrase><phrase role="special">{</phrase> <phrase role="identifier">h</phrase> <phrase role="special">}</phrase> <phrase role="special">{</phrase> | |
11433 | <phrase role="special">}</phrase> | |
11434 | <phrase role="special">};</phrase> | |
11435 | </programlisting> | |
11436 | </para> | |
11437 | <para> | |
11438 | Naturally that leads us straight to <code><phrase role="identifier">async_result_base</phrase></code>: | |
11439 | </para> | |
11440 | <para> | |
11441 | <programlisting><phrase role="comment">// Factor out commonality between async_result<yield_handler<T>> and</phrase> | |
11442 | <phrase role="comment">// async_result<yield_handler<void>></phrase> | |
11443 | <phrase role="keyword">class</phrase> <phrase role="identifier">async_result_base</phrase> <phrase role="special">{</phrase> | |
11444 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11445 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">async_result_base</phrase><phrase role="special">(</phrase> <phrase role="identifier">yield_handler_base</phrase> <phrase role="special">&</phrase> <phrase role="identifier">h</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11446 | <phrase role="comment">// Inject ptr to our yield_completion instance into this</phrase> | |
11447 | <phrase role="comment">// yield_handler<>.</phrase> | |
11448 | <phrase role="identifier">h</phrase><phrase role="special">.</phrase><phrase role="identifier">ycomp_</phrase> <phrase role="special">=</phrase> <phrase role="special">&</phrase> <phrase role="keyword">this</phrase><phrase role="special">-></phrase><phrase role="identifier">ycomp_</phrase><phrase role="special">;</phrase> | |
11449 | <phrase role="comment">// if yield_t didn't bind an error_code, make yield_handler_base's</phrase> | |
11450 | <phrase role="comment">// error_code* point to an error_code local to this object so</phrase> | |
11451 | <phrase role="comment">// yield_handler_base::operator() can unconditionally store through</phrase> | |
11452 | <phrase role="comment">// its error_code*</phrase> | |
11453 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">h</phrase><phrase role="special">.</phrase><phrase role="identifier">yt_</phrase><phrase role="special">.</phrase><phrase role="identifier">ec_</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11454 | <phrase role="identifier">h</phrase><phrase role="special">.</phrase><phrase role="identifier">yt_</phrase><phrase role="special">.</phrase><phrase role="identifier">ec_</phrase> <phrase role="special">=</phrase> <phrase role="special">&</phrase> <phrase role="identifier">ec_</phrase><phrase role="special">;</phrase> | |
11455 | <phrase role="special">}</phrase> | |
11456 | <phrase role="special">}</phrase> | |
11457 | ||
11458 | <phrase role="keyword">void</phrase> <phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
11459 | <phrase role="comment">// Unless yield_handler_base::operator() has already been called,</phrase> | |
11460 | <phrase role="comment">// suspend the calling fiber until that call.</phrase> | |
11461 | <phrase role="identifier">ycomp_</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
11462 | <phrase role="comment">// The only way our own ec_ member could have a non-default value is</phrase> | |
11463 | <phrase role="comment">// if our yield_handler did not have a bound error_code AND the</phrase> | |
11464 | <phrase role="comment">// completion callback passed a non-default error_code.</phrase> | |
11465 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">ec_</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11466 | <phrase role="identifier">throw_exception</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">system_error</phrase><phrase role="special">{</phrase> <phrase role="identifier">ec_</phrase> <phrase role="special">}</phrase> <phrase role="special">);</phrase> | |
11467 | <phrase role="special">}</phrase> | |
11468 | <phrase role="special">}</phrase> | |
11469 | ||
11470 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
11471 | <phrase role="comment">// If yield_t does not bind an error_code instance, store into here.</phrase> | |
11472 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase> <phrase role="identifier">ec_</phrase><phrase role="special">{};</phrase> | |
11473 | <phrase role="comment">// async_result_base owns the yield_completion because, unlike</phrase> | |
11474 | <phrase role="comment">// yield_handler<>, async_result<> is only instantiated once.</phrase> | |
11475 | <phrase role="identifier">yield_completion</phrase> <phrase role="identifier">ycomp_</phrase><phrase role="special">{};</phrase> | |
11476 | <phrase role="special">};</phrase> | |
11477 | </programlisting> | |
11478 | </para> | |
11479 | <para> | |
11480 | This is how <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11481 | role="special">::</phrase><phrase role="identifier">ycomp_</phrase></code> | |
11482 | becomes non-null: <code><phrase role="identifier">async_result_base</phrase></code>’s | |
11483 | constructor injects a pointer back to its own <code><phrase role="identifier">yield_completion</phrase></code> | |
11484 | member. | |
11485 | </para> | |
11486 | <para> | |
11487 | Recall that the canonical <code><phrase role="identifier">yield_t</phrase></code> | |
11488 | instance <code><phrase role="identifier">yield</phrase></code> initializes | |
11489 | its <code><phrase role="identifier">error_code</phrase><phrase role="special">*</phrase></code> | |
11490 | member <code><phrase role="identifier">ec_</phrase></code> to <code><phrase | |
11491 | role="keyword">nullptr</phrase></code>. If this instance is passed to <code><phrase | |
11492 | role="identifier">async_something</phrase><phrase role="special">()</phrase></code> | |
11493 | (<code><phrase role="identifier">ec_</phrase></code> is still <code><phrase | |
11494 | role="keyword">nullptr</phrase></code>), the copy stored in <code><phrase | |
11495 | role="identifier">yield_handler_base</phrase></code> will likewise have null | |
11496 | <code><phrase role="identifier">ec_</phrase></code>. <code><phrase role="identifier">async_result_base</phrase></code>’s | |
11497 | constructor sets <code><phrase role="identifier">yield_handler_base</phrase></code>’s | |
11498 | <code><phrase role="identifier">yield_t</phrase></code>’s <code><phrase role="identifier">ec_</phrase></code> | |
11499 | member to point to its own <code><phrase role="identifier">error_code</phrase></code> | |
11500 | member. | |
11501 | </para> | |
11502 | <para> | |
11503 | The stage is now set. <code><phrase role="identifier">async_something</phrase><phrase | |
11504 | role="special">()</phrase></code> initiates the actual async operation, arranging | |
11505 | to call its <code><phrase role="identifier">yield_handler</phrase><phrase | |
11506 | role="special"><</phrase><phrase role="keyword">void</phrase><phrase role="special">></phrase></code> | |
11507 | instance on completion. Let’s say, for the sake of argument, that the actual | |
11508 | async operation’s callback has signature <code><phrase role="keyword">void</phrase><phrase | |
11509 | role="special">(</phrase><phrase role="identifier">error_code</phrase><phrase | |
11510 | role="special">)</phrase></code>. | |
11511 | </para> | |
11512 | <para> | |
11513 | But since it’s an async operation, control returns at once to <code><phrase | |
11514 | role="identifier">async_something</phrase><phrase role="special">()</phrase></code>. | |
11515 | <code><phrase role="identifier">async_something</phrase><phrase role="special">()</phrase></code> | |
11516 | calls <code><phrase role="identifier">async_result</phrase><phrase role="special"><</phrase><phrase | |
11517 | role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11518 | role="keyword">void</phrase><phrase role="special">>>::</phrase><phrase | |
11519 | role="identifier">get</phrase><phrase role="special">()</phrase></code>, | |
11520 | and will return its return value. | |
11521 | </para> | |
11522 | <para> | |
11523 | <code><phrase role="identifier">async_result</phrase><phrase role="special"><</phrase><phrase | |
11524 | role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11525 | role="keyword">void</phrase><phrase role="special">>>::</phrase><phrase | |
11526 | role="identifier">get</phrase><phrase role="special">()</phrase></code> inherits | |
11527 | <code><phrase role="identifier">async_result_base</phrase><phrase role="special">::</phrase><phrase | |
11528 | role="identifier">get</phrase><phrase role="special">()</phrase></code>. | |
11529 | </para> | |
11530 | <para> | |
11531 | <code><phrase role="identifier">async_result_base</phrase><phrase role="special">::</phrase><phrase | |
11532 | role="identifier">get</phrase><phrase role="special">()</phrase></code> immediately | |
11533 | calls <code><phrase role="identifier">yield_completion</phrase><phrase role="special">::</phrase><phrase | |
11534 | role="identifier">wait</phrase><phrase role="special">()</phrase></code>. | |
11535 | </para> | |
11536 | <para> | |
11537 | <programlisting><phrase role="comment">// Bundle a completion bool flag with a spinlock to protect it.</phrase> | |
11538 | <phrase role="keyword">struct</phrase> <phrase role="identifier">yield_completion</phrase> <phrase role="special">{</phrase> | |
11539 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">spinlock</phrase> <phrase role="identifier">mutex_t</phrase><phrase role="special">;</phrase> | |
11540 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">mutex_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">lock_t</phrase><phrase role="special">;</phrase> | |
11541 | ||
11542 | <phrase role="identifier">mutex_t</phrase> <phrase role="identifier">mtx_</phrase><phrase role="special">{};</phrase> | |
11543 | <phrase role="keyword">bool</phrase> <phrase role="identifier">completed_</phrase><phrase role="special">{</phrase> <phrase role="keyword">false</phrase> <phrase role="special">};</phrase> | |
11544 | ||
11545 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
11546 | <phrase role="comment">// yield_handler_base::operator()() will set completed_ true and</phrase> | |
11547 | <phrase role="comment">// attempt to wake a suspended fiber. It would be Bad if that call</phrase> | |
11548 | <phrase role="comment">// happened between our detecting (! completed_) and suspending.</phrase> | |
11549 | <phrase role="identifier">lock_t</phrase> <phrase role="identifier">lk</phrase><phrase role="special">{</phrase> <phrase role="identifier">mtx_</phrase> <phrase role="special">};</phrase> | |
11550 | <phrase role="comment">// If completed_ is already set, we're done here: don't suspend.</phrase> | |
11551 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">completed_</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11552 | <phrase role="comment">// suspend(unique_lock<spinlock>) unlocks the lock in the act of</phrase> | |
11553 | <phrase role="comment">// resuming another fiber</phrase> | |
11554 | <phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase><phrase role="special">::</phrase><phrase role="identifier">active</phrase><phrase role="special">()-></phrase><phrase role="identifier">suspend</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">);</phrase> | |
11555 | <phrase role="special">}</phrase> | |
11556 | <phrase role="special">}</phrase> | |
11557 | <phrase role="special">};</phrase> | |
11558 | </programlisting> | |
11559 | </para> | |
11560 | <para> | |
11561 | Supposing that the pending async operation has not yet completed, <code><phrase | |
11562 | role="identifier">yield_completion</phrase><phrase role="special">::</phrase><phrase | |
11563 | role="identifier">completed_</phrase></code> will still be <code><phrase | |
11564 | role="keyword">false</phrase></code>, and <code><phrase role="identifier">wait</phrase><phrase | |
11565 | role="special">()</phrase></code> will call <link linkend="context_suspend"><code>context::suspend()</code></link> on | |
11566 | the currently-running fiber. | |
11567 | </para> | |
11568 | <para> | |
11569 | Other fibers will now have a chance to run. | |
11570 | </para> | |
11571 | <para> | |
11572 | Some time later, the async operation completes. It calls <code><phrase role="identifier">yield_handler</phrase><phrase | |
11573 | role="special"><</phrase><phrase role="keyword">void</phrase><phrase role="special">>::</phrase><phrase | |
11574 | role="keyword">operator</phrase><phrase role="special">()(</phrase><phrase | |
11575 | role="identifier">error_code</phrase> <phrase role="keyword">const</phrase><phrase | |
11576 | role="special">&)</phrase></code> with an <code><phrase role="identifier">error_code</phrase></code> | |
11577 | indicating either success or failure. We’ll consider both cases. | |
11578 | </para> | |
11579 | <para> | |
11580 | <code><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11581 | role="keyword">void</phrase><phrase role="special">></phrase></code> explicitly | |
11582 | inherits <code><phrase role="keyword">operator</phrase><phrase role="special">()(</phrase><phrase | |
11583 | role="identifier">error_code</phrase> <phrase role="keyword">const</phrase><phrase | |
11584 | role="special">&)</phrase></code> from <code><phrase role="identifier">yield_handler_base</phrase></code>. | |
11585 | </para> | |
11586 | <para> | |
11587 | <code><phrase role="identifier">yield_handler_base</phrase><phrase role="special">::</phrase><phrase | |
11588 | role="keyword">operator</phrase><phrase role="special">()(</phrase><phrase | |
11589 | role="identifier">error_code</phrase> <phrase role="keyword">const</phrase><phrase | |
11590 | role="special">&)</phrase></code> first sets <code><phrase role="identifier">yield_completion</phrase><phrase | |
11591 | role="special">::</phrase><phrase role="identifier">completed_</phrase></code> | |
11592 | <code><phrase role="keyword">true</phrase></code>. This way, if <code><phrase | |
11593 | role="identifier">async_something</phrase><phrase role="special">()</phrase></code>’s | |
11594 | async operation completes immediately — if <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11595 | role="special">::</phrase><phrase role="keyword">operator</phrase><phrase | |
11596 | role="special">()</phrase></code> is called even before <code><phrase role="identifier">async_result_base</phrase><phrase | |
11597 | role="special">::</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
11598 | — the calling fiber will <emphasis>not</emphasis> suspend. | |
11599 | </para> | |
11600 | <para> | |
11601 | The actual <code><phrase role="identifier">error_code</phrase></code> produced | |
11602 | by the async operation is then stored through the stored <code><phrase role="identifier">yield_t</phrase><phrase | |
11603 | role="special">::</phrase><phrase role="identifier">ec_</phrase></code> pointer. | |
11604 | If <code><phrase role="identifier">async_something</phrase><phrase role="special">()</phrase></code>’s | |
11605 | caller used (e.g.) <code><phrase role="identifier">yield</phrase><phrase | |
11606 | role="special">[</phrase><phrase role="identifier">my_ec</phrase><phrase | |
11607 | role="special">]</phrase></code> to bind a local <code><phrase role="identifier">error_code</phrase></code> | |
11608 | instance, the actual <code><phrase role="identifier">error_code</phrase></code> | |
11609 | value is stored into the caller’s variable. Otherwise, it is stored into | |
11610 | <code><phrase role="identifier">async_result_base</phrase><phrase role="special">::</phrase><phrase | |
11611 | role="identifier">ec_</phrase></code>. | |
11612 | </para> | |
11613 | <para> | |
11614 | If the stored fiber context <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11615 | role="special">::</phrase><phrase role="identifier">ctx_</phrase></code> | |
11616 | is not already running, it is marked as ready to run by passing it to <link linkend="context_set_ready"><code>context::set_ready()</code></link>. | |
11617 | Control then returns from <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11618 | role="special">::</phrase><phrase role="keyword">operator</phrase><phrase | |
11619 | role="special">()</phrase></code>: the callback is done. | |
11620 | </para> | |
11621 | <para> | |
11622 | In due course, that fiber is resumed. Control returns from <link linkend="context_suspend"><code>context::suspend()</code></link> to | |
11623 | <code><phrase role="identifier">yield_completion</phrase><phrase role="special">::</phrase><phrase | |
11624 | role="identifier">wait</phrase><phrase role="special">()</phrase></code>, | |
11625 | which returns to <code><phrase role="identifier">async_result_base</phrase><phrase | |
11626 | role="special">::</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code>. | |
11627 | </para> | |
11628 | <itemizedlist> | |
11629 | <listitem> | |
11630 | <simpara> | |
11631 | If the original caller passed <code><phrase role="identifier">yield</phrase><phrase | |
11632 | role="special">[</phrase><phrase role="identifier">my_ec</phrase><phrase | |
11633 | role="special">]</phrase></code> to <code><phrase role="identifier">async_something</phrase><phrase | |
11634 | role="special">()</phrase></code> to bind a local <code><phrase role="identifier">error_code</phrase></code> | |
11635 | instance, then <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11636 | role="special">::</phrase><phrase role="keyword">operator</phrase><phrase | |
11637 | role="special">()</phrase></code> stored its <code><phrase role="identifier">error_code</phrase></code> | |
11638 | to the caller’s <code><phrase role="identifier">my_ec</phrase></code> | |
11639 | instance, leaving <code><phrase role="identifier">async_result_base</phrase><phrase | |
11640 | role="special">::</phrase><phrase role="identifier">ec_</phrase></code> | |
11641 | initialized to success. | |
11642 | </simpara> | |
11643 | </listitem> | |
11644 | <listitem> | |
11645 | <simpara> | |
11646 | If the original caller passed <code><phrase role="identifier">yield</phrase></code> | |
11647 | to <code><phrase role="identifier">async_something</phrase><phrase role="special">()</phrase></code> | |
11648 | without binding a local <code><phrase role="identifier">error_code</phrase></code> | |
11649 | variable, then <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11650 | role="special">::</phrase><phrase role="keyword">operator</phrase><phrase | |
11651 | role="special">()</phrase></code> stored its <code><phrase role="identifier">error_code</phrase></code> | |
11652 | into <code><phrase role="identifier">async_result_base</phrase><phrase | |
11653 | role="special">::</phrase><phrase role="identifier">ec_</phrase></code>. | |
11654 | If in fact that <code><phrase role="identifier">error_code</phrase></code> | |
11655 | is success, then all is well. | |
11656 | </simpara> | |
11657 | </listitem> | |
11658 | <listitem> | |
11659 | <simpara> | |
11660 | Otherwise — the original caller did not bind a local <code><phrase role="identifier">error_code</phrase></code> | |
11661 | and <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11662 | role="special">::</phrase><phrase role="keyword">operator</phrase><phrase | |
11663 | role="special">()</phrase></code> was called with an <code><phrase role="identifier">error_code</phrase></code> | |
11664 | indicating error — <code><phrase role="identifier">async_result_base</phrase><phrase | |
11665 | role="special">::</phrase><phrase role="identifier">get</phrase><phrase | |
11666 | role="special">()</phrase></code> throws <code><phrase role="identifier">system_error</phrase></code> | |
11667 | with that <code><phrase role="identifier">error_code</phrase></code>. | |
11668 | </simpara> | |
11669 | </listitem> | |
11670 | </itemizedlist> | |
11671 | <para> | |
11672 | The case in which <code><phrase role="identifier">async_something</phrase><phrase | |
11673 | role="special">()</phrase></code>’s completion callback has signature <code><phrase | |
11674 | role="keyword">void</phrase><phrase role="special">()</phrase></code> is | |
11675 | similar. <code><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11676 | role="keyword">void</phrase><phrase role="special">>::</phrase><phrase | |
11677 | role="keyword">operator</phrase><phrase role="special">()()</phrase></code> | |
11678 | invokes the machinery above with a <quote>success</quote> <code><phrase role="identifier">error_code</phrase></code>. | |
11679 | </para> | |
11680 | <para> | |
11681 | A completion callback with signature <code><phrase role="keyword">void</phrase><phrase | |
11682 | role="special">(</phrase><phrase role="identifier">error_code</phrase><phrase | |
11683 | role="special">,</phrase> <phrase role="identifier">T</phrase><phrase role="special">)</phrase></code> | |
11684 | (that is: in addition to <code><phrase role="identifier">error_code</phrase></code>, | |
11685 | callback receives some data item) is handled somewhat differently. For this | |
11686 | kind of signature, <code><phrase role="identifier">handler_type</phrase><phrase | |
11687 | role="special"><>::</phrase><phrase role="identifier">type</phrase></code> | |
11688 | specifies <code><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11689 | role="identifier">T</phrase><phrase role="special">></phrase></code> (for | |
11690 | <code><phrase role="identifier">T</phrase></code> other than <code><phrase | |
11691 | role="keyword">void</phrase></code>). | |
11692 | </para> | |
11693 | <para> | |
11694 | A <code><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11695 | role="identifier">T</phrase><phrase role="special">></phrase></code> reserves | |
11696 | a <code><phrase role="identifier">value_</phrase></code> pointer to a value | |
11697 | of type <code><phrase role="identifier">T</phrase></code>: | |
11698 | </para> | |
11699 | <para> | |
11700 | <programlisting><phrase role="comment">// asio uses handler_type<completion token type, signature>::type to decide</phrase> | |
11701 | <phrase role="comment">// what to instantiate as the actual handler. Below, we specialize</phrase> | |
11702 | <phrase role="comment">// handler_type< yield_t, ... > to indicate yield_handler<>. So when you pass</phrase> | |
11703 | <phrase role="comment">// an instance of yield_t as an asio completion token, asio selects</phrase> | |
11704 | <phrase role="comment">// yield_handler<> as the actual handler class.</phrase> | |
11705 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> | |
11706 | <phrase role="keyword">class</phrase> <phrase role="identifier">yield_handler</phrase><phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">yield_handler_base</phrase> <phrase role="special">{</phrase> | |
11707 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11708 | <phrase role="comment">// asio passes the completion token to the handler constructor</phrase> | |
11709 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">yield_handler</phrase><phrase role="special">(</phrase> <phrase role="identifier">yield_t</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">y</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
11710 | <phrase role="identifier">yield_handler_base</phrase><phrase role="special">{</phrase> <phrase role="identifier">y</phrase> <phrase role="special">}</phrase> <phrase role="special">{</phrase> | |
11711 | <phrase role="special">}</phrase> | |
11712 | ||
11713 | <phrase role="comment">// completion callback passing only value (T)</phrase> | |
11714 | <phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">t</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11715 | <phrase role="comment">// just like callback passing success error_code</phrase> | |
11716 | <phrase role="special">(*</phrase><phrase role="keyword">this</phrase><phrase role="special">)(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase><phrase role="special">(),</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase><phrase role="identifier">t</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11717 | <phrase role="special">}</phrase> | |
11718 | ||
11719 | <phrase role="comment">// completion callback passing (error_code, T)</phrase> | |
11720 | <phrase role="keyword">void</phrase> <phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">ec</phrase><phrase role="special">,</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">t</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11721 | <phrase role="identifier">BOOST_ASSERT_MSG</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_</phrase><phrase role="special">,</phrase> | |
11722 | <phrase role="string">"Must inject value ptr "</phrase> | |
11723 | <phrase role="string">"before caling yield_handler<T>::operator()()"</phrase><phrase role="special">);</phrase> | |
11724 | <phrase role="comment">// move the value to async_result<> instance BEFORE waking up a</phrase> | |
11725 | <phrase role="comment">// suspended fiber</phrase> | |
11726 | <phrase role="special">*</phrase> <phrase role="identifier">value_</phrase> <phrase role="special">=</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">t</phrase><phrase role="special">);</phrase> | |
11727 | <phrase role="comment">// forward the call to base-class completion handler</phrase> | |
11728 | <phrase role="identifier">yield_handler_base</phrase><phrase role="special">::</phrase><phrase role="keyword">operator</phrase><phrase role="special">()(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">);</phrase> | |
11729 | <phrase role="special">}</phrase> | |
11730 | ||
11731 | <phrase role="comment">//private:</phrase> | |
11732 | <phrase role="comment">// pointer to destination for eventual value</phrase> | |
11733 | <phrase role="comment">// this must be injected by async_result before operator()() is called</phrase> | |
11734 | <phrase role="identifier">T</phrase> <phrase role="special">*</phrase> <phrase role="identifier">value_</phrase><phrase role="special">{</phrase> <phrase role="keyword">nullptr</phrase> <phrase role="special">};</phrase> | |
11735 | <phrase role="special">};</phrase> | |
11736 | </programlisting> | |
11737 | </para> | |
11738 | <para> | |
11739 | This pointer is initialized to <code><phrase role="keyword">nullptr</phrase></code>. | |
11740 | </para> | |
11741 | <para> | |
11742 | When <code><phrase role="identifier">async_something</phrase><phrase role="special">()</phrase></code> | |
11743 | instantiates <code><phrase role="identifier">async_result</phrase><phrase | |
11744 | role="special"><</phrase><phrase role="identifier">yield_handler</phrase><phrase | |
11745 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase role="special">>></phrase></code>: | |
11746 | </para> | |
11747 | <para> | |
11748 | <programlisting><phrase role="comment">// asio constructs an async_result<> instance from the yield_handler specified</phrase> | |
11749 | <phrase role="comment">// by handler_type<>::type. A particular asio async method constructs the</phrase> | |
11750 | <phrase role="comment">// yield_handler, constructs this async_result specialization from it, then</phrase> | |
11751 | <phrase role="comment">// returns the result of calling its get() method.</phrase> | |
11752 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> | |
11753 | <phrase role="keyword">class</phrase> <phrase role="identifier">async_result</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="special">:</phrase> | |
11754 | <phrase role="keyword">public</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">async_result_base</phrase> <phrase role="special">{</phrase> | |
11755 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11756 | <phrase role="comment">// type returned by get()</phrase> | |
11757 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">type</phrase><phrase role="special">;</phrase> | |
11758 | ||
11759 | <phrase role="keyword">explicit</phrase> <phrase role="identifier">async_result</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">h</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
11760 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">async_result_base</phrase><phrase role="special">{</phrase> <phrase role="identifier">h</phrase> <phrase role="special">}</phrase> <phrase role="special">{</phrase> | |
11761 | <phrase role="comment">// Inject ptr to our value_ member into yield_handler<>: result will</phrase> | |
11762 | <phrase role="comment">// be stored here.</phrase> | |
11763 | <phrase role="identifier">h</phrase><phrase role="special">.</phrase><phrase role="identifier">value_</phrase> <phrase role="special">=</phrase> <phrase role="special">&</phrase> <phrase role="identifier">value_</phrase><phrase role="special">;</phrase> | |
11764 | <phrase role="special">}</phrase> | |
11765 | ||
11766 | <phrase role="comment">// asio async method returns result of calling get()</phrase> | |
11767 | <phrase role="identifier">type</phrase> <phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
11768 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">detail</phrase><phrase role="special">::</phrase><phrase role="identifier">async_result_base</phrase><phrase role="special">::</phrase><phrase role="identifier">get</phrase><phrase role="special">();</phrase> | |
11769 | <phrase role="keyword">return</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">move</phrase><phrase role="special">(</phrase> <phrase role="identifier">value_</phrase><phrase role="special">);</phrase> | |
11770 | <phrase role="special">}</phrase> | |
11771 | ||
11772 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
11773 | <phrase role="identifier">type</phrase> <phrase role="identifier">value_</phrase><phrase role="special">{};</phrase> | |
11774 | <phrase role="special">};</phrase> | |
11775 | </programlisting> | |
11776 | </para> | |
11777 | <para> | |
11778 | this <code><phrase role="identifier">async_result</phrase><phrase role="special"><></phrase></code> | |
11779 | specialization reserves a member of type <code><phrase role="identifier">T</phrase></code> | |
11780 | to receive the passed data item, and sets <code><phrase role="identifier">yield_handler</phrase><phrase | |
11781 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase role="special">>::</phrase><phrase | |
11782 | role="identifier">value_</phrase></code> to point to its own data member. | |
11783 | </para> | |
11784 | <para> | |
11785 | <code><phrase role="identifier">async_result</phrase><phrase role="special"><</phrase><phrase | |
11786 | role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11787 | role="identifier">T</phrase><phrase role="special">>></phrase></code> | |
11788 | overrides <code><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code>. | |
11789 | The override calls <code><phrase role="identifier">async_result_base</phrase><phrase | |
11790 | role="special">::</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code>, | |
11791 | so the calling fiber suspends as described above. | |
11792 | </para> | |
11793 | <para> | |
11794 | <code><phrase role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11795 | role="identifier">T</phrase><phrase role="special">>::</phrase><phrase | |
11796 | role="keyword">operator</phrase><phrase role="special">()(</phrase><phrase | |
11797 | role="identifier">error_code</phrase><phrase role="special">,</phrase> <phrase | |
11798 | role="identifier">T</phrase><phrase role="special">)</phrase></code> stores | |
11799 | its passed <code><phrase role="identifier">T</phrase></code> value into | |
11800 | <code><phrase role="identifier">async_result</phrase><phrase role="special"><</phrase><phrase | |
11801 | role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11802 | role="identifier">T</phrase><phrase role="special">>>::</phrase><phrase | |
11803 | role="identifier">value_</phrase></code>. | |
11804 | </para> | |
11805 | <para> | |
11806 | Then it passes control to <code><phrase role="identifier">yield_handler_base</phrase><phrase | |
11807 | role="special">::</phrase><phrase role="keyword">operator</phrase><phrase | |
11808 | role="special">()(</phrase><phrase role="identifier">error_code</phrase><phrase | |
11809 | role="special">)</phrase></code> to deal with waking the original fiber as | |
11810 | described above. | |
11811 | </para> | |
11812 | <para> | |
11813 | When <code><phrase role="identifier">async_result</phrase><phrase role="special"><</phrase><phrase | |
11814 | role="identifier">yield_handler</phrase><phrase role="special"><</phrase><phrase | |
11815 | role="identifier">T</phrase><phrase role="special">>>::</phrase><phrase | |
11816 | role="identifier">get</phrase><phrase role="special">()</phrase></code> resumes, | |
11817 | it returns the stored <code><phrase role="identifier">value_</phrase></code> | |
11818 | to <code><phrase role="identifier">async_something</phrase><phrase role="special">()</phrase></code> | |
11819 | and ultimately to <code><phrase role="identifier">async_something</phrase><phrase | |
11820 | role="special">()</phrase></code>’s caller. | |
11821 | </para> | |
11822 | <para> | |
11823 | The case of a callback signature <code><phrase role="keyword">void</phrase><phrase | |
11824 | role="special">(</phrase><phrase role="identifier">T</phrase><phrase role="special">)</phrase></code> | |
11825 | is handled by having <code><phrase role="identifier">yield_handler</phrase><phrase | |
11826 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase role="special">>::</phrase><phrase | |
11827 | role="keyword">operator</phrase><phrase role="special">()(</phrase><phrase | |
11828 | role="identifier">T</phrase><phrase role="special">)</phrase></code> engage | |
11829 | the <code><phrase role="keyword">void</phrase><phrase role="special">(</phrase><phrase | |
11830 | role="identifier">error_code</phrase><phrase role="special">,</phrase> <phrase | |
11831 | role="identifier">T</phrase><phrase role="special">)</phrase></code> machinery, | |
11832 | passing a <quote>success</quote> <code><phrase role="identifier">error_code</phrase></code>. | |
11833 | </para> | |
11834 | <para> | |
11835 | The source code above is found in <ulink url="../../examples/asio/yield.hpp">yield.hpp</ulink> | |
11836 | and <ulink url="../../examples/asio/detail/yield.hpp">detail/yield.hpp</ulink>. | |
11837 | </para> | |
11838 | </section> | |
11839 | </section> | |
11840 | <section id="fiber.nonblocking"> | |
11841 | <title><anchor id="nonblocking"/><link linkend="fiber.nonblocking">Integrating | |
11842 | Fibers with Nonblocking I/O</link></title> | |
11843 | <bridgehead renderas="sect3" id="fiber.nonblocking.h0"> | |
11844 | <phrase id="fiber.nonblocking.overview"/><link linkend="fiber.nonblocking.overview">Overview</link> | |
11845 | </bridgehead> | |
11846 | <para> | |
11847 | <emphasis>Nonblocking</emphasis> I/O is distinct from <emphasis>asynchronous</emphasis> | |
11848 | I/O. A true async I/O operation promises to initiate the operation and notify | |
11849 | the caller on completion, usually via some sort of callback (as described in | |
11850 | <link linkend="callbacks">Integrating Fibers with Asynchronous Callbacks</link>). | |
11851 | </para> | |
11852 | <para> | |
11853 | In contrast, a nonblocking I/O operation refuses to start at all if it would | |
11854 | be necessary to block, returning an error code such as <ulink url="http://man7.org/linux/man-pages/man3/errno.3.html"><code><phrase | |
11855 | role="identifier">EWOULDBLOCK</phrase></code></ulink>. The operation is performed | |
11856 | only when it can complete immediately. In effect, the caller must repeatedly | |
11857 | retry the operation until it stops returning <code><phrase role="identifier">EWOULDBLOCK</phrase></code>. | |
11858 | </para> | |
11859 | <para> | |
11860 | In a classic event-driven program, it can be something of a headache to use | |
11861 | nonblocking I/O. At the point where the nonblocking I/O is attempted, a return | |
11862 | value of <code><phrase role="identifier">EWOULDBLOCK</phrase></code> requires | |
11863 | the caller to pass control back to the main event loop, arranging to retry | |
11864 | again on the next iteration. | |
11865 | </para> | |
11866 | <para> | |
11867 | Worse, a nonblocking I/O operation might <emphasis>partially</emphasis> succeed. | |
11868 | That means that the relevant business logic must continue receiving control | |
11869 | on every main loop iteration until all required data have been processed: a | |
11870 | doubly-nested loop, implemented as a callback-driven state machine. | |
11871 | </para> | |
11872 | <para> | |
11873 | <emphasis role="bold">Boost.Fiber</emphasis> can simplify this problem immensely. | |
11874 | Once you have integrated with the application's main loop as described in | |
11875 | <link linkend="integration">Sharing a Thread with Another Main Loop</link>, | |
11876 | waiting for the next main-loop iteration is as simple as calling <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link>. | |
11877 | </para> | |
11878 | <bridgehead renderas="sect3" id="fiber.nonblocking.h1"> | |
11879 | <phrase id="fiber.nonblocking.example_nonblocking_api"/><link linkend="fiber.nonblocking.example_nonblocking_api">Example | |
11880 | Nonblocking API</link> | |
11881 | </bridgehead> | |
11882 | <para> | |
11883 | For purposes of illustration, consider this API: | |
11884 | </para> | |
11885 | <para> | |
11886 | <programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">NonblockingAPI</phrase> <phrase role="special">{</phrase> | |
11887 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11888 | <phrase role="identifier">NonblockingAPI</phrase><phrase role="special">();</phrase> | |
11889 | ||
11890 | <phrase role="comment">// nonblocking operation: may return EWOULDBLOCK</phrase> | |
11891 | <phrase role="keyword">int</phrase> <phrase role="identifier">read</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">desired</phrase><phrase role="special">);</phrase> | |
11892 | ||
11893 | <phrase role="special">...</phrase> | |
11894 | <phrase role="special">};</phrase> | |
11895 | </programlisting> | |
11896 | </para> | |
11897 | <bridgehead renderas="sect3" id="fiber.nonblocking.h2"> | |
11898 | <phrase id="fiber.nonblocking.polling_for_completion"/><link linkend="fiber.nonblocking.polling_for_completion">Polling | |
11899 | for Completion</link> | |
11900 | </bridgehead> | |
11901 | <para> | |
11902 | We can build a low-level wrapper around <code><phrase role="identifier">NonblockingAPI</phrase><phrase | |
11903 | role="special">::</phrase><phrase role="identifier">read</phrase><phrase role="special">()</phrase></code> | |
11904 | that shields its caller from ever having to deal with <code><phrase role="identifier">EWOULDBLOCK</phrase></code>: | |
11905 | </para> | |
11906 | <para> | |
11907 | <programlisting><phrase role="comment">// guaranteed not to return EWOULDBLOCK</phrase> | |
11908 | <phrase role="keyword">int</phrase> <phrase role="identifier">read_chunk</phrase><phrase role="special">(</phrase> <phrase role="identifier">NonblockingAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">desired</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11909 | <phrase role="keyword">int</phrase> <phrase role="identifier">error</phrase><phrase role="special">;</phrase> | |
11910 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">EWOULDBLOCK</phrase> <phrase role="special">==</phrase> <phrase role="special">(</phrase> <phrase role="identifier">error</phrase> <phrase role="special">=</phrase> <phrase role="identifier">api</phrase><phrase role="special">.</phrase><phrase role="identifier">read</phrase><phrase role="special">(</phrase> <phrase role="identifier">data</phrase><phrase role="special">,</phrase> <phrase role="identifier">desired</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11911 | <phrase role="comment">// not ready yet -- try again on the next iteration of the</phrase> | |
11912 | <phrase role="comment">// application's main loop</phrase> | |
11913 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">yield</phrase><phrase role="special">();</phrase> | |
11914 | <phrase role="special">}</phrase> | |
11915 | <phrase role="keyword">return</phrase> <phrase role="identifier">error</phrase><phrase role="special">;</phrase> | |
11916 | <phrase role="special">}</phrase> | |
11917 | </programlisting> | |
11918 | </para> | |
11919 | <bridgehead renderas="sect3" id="fiber.nonblocking.h3"> | |
11920 | <phrase id="fiber.nonblocking.filling_all_desired_data"/><link linkend="fiber.nonblocking.filling_all_desired_data">Filling | |
11921 | All Desired Data</link> | |
11922 | </bridgehead> | |
11923 | <para> | |
11924 | Given <code><phrase role="identifier">read_chunk</phrase><phrase role="special">()</phrase></code>, | |
11925 | we can straightforwardly iterate until we have all desired data: | |
11926 | </para> | |
11927 | <para> | |
11928 | <programlisting><phrase role="comment">// keep reading until desired length, EOF or error</phrase> | |
11929 | <phrase role="comment">// may return both partial data and nonzero error</phrase> | |
11930 | <phrase role="keyword">int</phrase> <phrase role="identifier">read_desired</phrase><phrase role="special">(</phrase> <phrase role="identifier">NonblockingAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">desired</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11931 | <phrase role="comment">// we're going to accumulate results into 'data'</phrase> | |
11932 | <phrase role="identifier">data</phrase><phrase role="special">.</phrase><phrase role="identifier">clear</phrase><phrase role="special">();</phrase> | |
11933 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">chunk</phrase><phrase role="special">;</phrase> | |
11934 | <phrase role="keyword">int</phrase> <phrase role="identifier">error</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> | |
11935 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">data</phrase><phrase role="special">.</phrase><phrase role="identifier">length</phrase><phrase role="special">()</phrase> <phrase role="special"><</phrase> <phrase role="identifier">desired</phrase> <phrase role="special">&&</phrase> | |
11936 | <phrase role="special">(</phrase> <phrase role="identifier">error</phrase> <phrase role="special">=</phrase> <phrase role="identifier">read_chunk</phrase><phrase role="special">(</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">chunk</phrase><phrase role="special">,</phrase> <phrase role="identifier">desired</phrase> <phrase role="special">-</phrase> <phrase role="identifier">data</phrase><phrase role="special">.</phrase><phrase role="identifier">length</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">==</phrase> <phrase role="number">0</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11937 | <phrase role="identifier">data</phrase><phrase role="special">.</phrase><phrase role="identifier">append</phrase><phrase role="special">(</phrase> <phrase role="identifier">chunk</phrase><phrase role="special">);</phrase> | |
11938 | <phrase role="special">}</phrase> | |
11939 | <phrase role="keyword">return</phrase> <phrase role="identifier">error</phrase><phrase role="special">;</phrase> | |
11940 | <phrase role="special">}</phrase> | |
11941 | </programlisting> | |
11942 | </para> | |
11943 | <para> | |
11944 | (Of <emphasis>course</emphasis> there are more efficient ways to accumulate | |
11945 | string data. That's not the point of this example.) | |
11946 | </para> | |
11947 | <bridgehead renderas="sect3" id="fiber.nonblocking.h4"> | |
11948 | <phrase id="fiber.nonblocking.wrapping_it_up"/><link linkend="fiber.nonblocking.wrapping_it_up">Wrapping | |
11949 | it Up</link> | |
11950 | </bridgehead> | |
11951 | <para> | |
11952 | Finally, we can define a relevant exception: | |
11953 | </para> | |
11954 | <para> | |
11955 | <programlisting><phrase role="comment">// exception class augmented with both partially-read data and errorcode</phrase> | |
11956 | <phrase role="keyword">class</phrase> <phrase role="identifier">IncompleteRead</phrase> <phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">runtime_error</phrase> <phrase role="special">{</phrase> | |
11957 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
11958 | <phrase role="identifier">IncompleteRead</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">what</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">partial</phrase><phrase role="special">,</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
11959 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">runtime_error</phrase><phrase role="special">(</phrase> <phrase role="identifier">what</phrase><phrase role="special">),</phrase> | |
11960 | <phrase role="identifier">partial_</phrase><phrase role="special">(</phrase> <phrase role="identifier">partial</phrase><phrase role="special">),</phrase> | |
11961 | <phrase role="identifier">ec_</phrase><phrase role="special">(</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11962 | <phrase role="special">}</phrase> | |
11963 | ||
11964 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">get_partial</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="special">{</phrase> | |
11965 | <phrase role="keyword">return</phrase> <phrase role="identifier">partial_</phrase><phrase role="special">;</phrase> | |
11966 | <phrase role="special">}</phrase> | |
11967 | ||
11968 | <phrase role="keyword">int</phrase> <phrase role="identifier">get_errorcode</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="special">{</phrase> | |
11969 | <phrase role="keyword">return</phrase> <phrase role="identifier">ec_</phrase><phrase role="special">;</phrase> | |
11970 | <phrase role="special">}</phrase> | |
11971 | ||
11972 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
11973 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">partial_</phrase><phrase role="special">;</phrase> | |
11974 | <phrase role="keyword">int</phrase> <phrase role="identifier">ec_</phrase><phrase role="special">;</phrase> | |
11975 | <phrase role="special">};</phrase> | |
11976 | </programlisting> | |
11977 | </para> | |
11978 | <para> | |
11979 | and write a simple <code><phrase role="identifier">read</phrase><phrase role="special">()</phrase></code> | |
11980 | function that either returns all desired data or throws <code><phrase role="identifier">IncompleteRead</phrase></code>: | |
11981 | </para> | |
11982 | <para> | |
11983 | <programlisting><phrase role="comment">// read all desired data or throw IncompleteRead</phrase> | |
11984 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">read</phrase><phrase role="special">(</phrase> <phrase role="identifier">NonblockingAPI</phrase> <phrase role="special">&</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">desired</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11985 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">data</phrase><phrase role="special">;</phrase> | |
11986 | <phrase role="keyword">int</phrase> <phrase role="identifier">ec</phrase><phrase role="special">(</phrase> <phrase role="identifier">read_desired</phrase><phrase role="special">(</phrase> <phrase role="identifier">api</phrase><phrase role="special">,</phrase> <phrase role="identifier">data</phrase><phrase role="special">,</phrase> <phrase role="identifier">desired</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
11987 | ||
11988 | <phrase role="comment">// for present purposes, EOF isn't a failure</phrase> | |
11989 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="number">0</phrase> <phrase role="special">==</phrase> <phrase role="identifier">ec</phrase> <phrase role="special">||</phrase> <phrase role="identifier">EOF</phrase> <phrase role="special">==</phrase> <phrase role="identifier">ec</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
11990 | <phrase role="keyword">return</phrase> <phrase role="identifier">data</phrase><phrase role="special">;</phrase> | |
11991 | <phrase role="special">}</phrase> | |
11992 | ||
11993 | <phrase role="comment">// oh oh, partial read</phrase> | |
11994 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ostringstream</phrase> <phrase role="identifier">msg</phrase><phrase role="special">;</phrase> | |
11995 | <phrase role="identifier">msg</phrase> <phrase role="special"><<</phrase> <phrase role="string">"NonblockingAPI::read() error "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">ec</phrase> <phrase role="special"><<</phrase> <phrase role="string">" after "</phrase> | |
11996 | <phrase role="special"><<</phrase> <phrase role="identifier">data</phrase><phrase role="special">.</phrase><phrase role="identifier">length</phrase><phrase role="special">()</phrase> <phrase role="special"><<</phrase> <phrase role="string">" of "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">desired</phrase> <phrase role="special"><<</phrase> <phrase role="string">" characters"</phrase><phrase role="special">;</phrase> | |
11997 | <phrase role="keyword">throw</phrase> <phrase role="identifier">IncompleteRead</phrase><phrase role="special">(</phrase> <phrase role="identifier">msg</phrase><phrase role="special">.</phrase><phrase role="identifier">str</phrase><phrase role="special">(),</phrase> <phrase role="identifier">data</phrase><phrase role="special">,</phrase> <phrase role="identifier">ec</phrase><phrase role="special">);</phrase> | |
11998 | <phrase role="special">}</phrase> | |
11999 | </programlisting> | |
12000 | </para> | |
12001 | <para> | |
12002 | Once we can transparently wait for the next main-loop iteration using <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link>, | |
12003 | ordinary encapsulation Just Works. | |
12004 | </para> | |
12005 | <para> | |
12006 | The source code above is found in <ulink url="../../examples/adapt_nonblocking.cpp">adapt_nonblocking.cpp</ulink>. | |
12007 | </para> | |
12008 | </section> | |
12009 | <section id="fiber.when_any"> | |
12010 | <title><anchor id="when_any"/><link linkend="fiber.when_any">when_any / when_all | |
12011 | functionality</link></title> | |
12012 | <bridgehead renderas="sect3" id="fiber.when_any.h0"> | |
12013 | <phrase id="fiber.when_any.overview"/><link linkend="fiber.when_any.overview">Overview</link> | |
12014 | </bridgehead> | |
12015 | <para> | |
12016 | A bit of wisdom from the early days of computing still holds true today: prefer | |
12017 | to model program state using the instruction pointer rather than with Boolean | |
12018 | flags. In other words, if the program must <quote>do something</quote> and | |
12019 | then do something almost the same, but with minor changes... perhaps parts | |
12020 | of that something should be broken out as smaller separate functions, rather | |
12021 | than introducing flags to alter the internal behavior of a monolithic function. | |
12022 | </para> | |
12023 | <para> | |
12024 | To that we would add: prefer to describe control flow using C++ native constructs | |
12025 | such as function calls, <code><phrase role="keyword">if</phrase></code>, <code><phrase | |
12026 | role="keyword">while</phrase></code>, <code><phrase role="keyword">for</phrase></code>, | |
12027 | <code><phrase role="keyword">do</phrase></code> et al. rather than as chains | |
12028 | of callbacks. | |
12029 | </para> | |
12030 | <para> | |
12031 | One of the great strengths of <emphasis role="bold">Boost.Fiber</emphasis> | |
12032 | is the flexibility it confers on the coder to restructure an application from | |
12033 | chains of callbacks to straightforward C++ statement sequence, even when code | |
12034 | in that fiber is in fact interleaved with code running in other fibers. | |
12035 | </para> | |
12036 | <para> | |
12037 | There has been much recent discussion about the benefits of when_any and when_all | |
12038 | functionality. When dealing with asynchronous and possibly unreliable services, | |
12039 | these are valuable idioms. But of course when_any and when_all are closely | |
12040 | tied to the use of chains of callbacks. | |
12041 | </para> | |
12042 | <para> | |
12043 | This section presents recipes for achieving the same ends, in the context of | |
12044 | a fiber that wants to <quote>do something</quote> when one or more other independent | |
12045 | activities have completed. Accordingly, these are <code><phrase role="identifier">wait_something</phrase><phrase | |
12046 | role="special">()</phrase></code> functions rather than <code><phrase role="identifier">when_something</phrase><phrase | |
12047 | role="special">()</phrase></code> functions. The expectation is that the calling | |
12048 | fiber asks to launch those independent activities, then waits for them, then | |
12049 | sequentially proceeds with whatever processing depends on those results. | |
12050 | </para> | |
12051 | <para> | |
12052 | The function names shown (e.g. <link linkend="wait_first_simple"><code><phrase | |
12053 | role="identifier">wait_first_simple</phrase><phrase role="special">()</phrase></code></link>) | |
12054 | are for illustrative purposes only, because all these functions have been bundled | |
12055 | into a single source file. Presumably, if (say) <link linkend="wait_first_success"><code><phrase | |
12056 | role="identifier">wait_first_success</phrase><phrase role="special">()</phrase></code></link> | |
12057 | best suits your application needs, you could introduce that variant with the | |
12058 | name <code><phrase role="identifier">wait_any</phrase><phrase role="special">()</phrase></code>. | |
12059 | </para> | |
12060 | <note> | |
12061 | <para> | |
12062 | The functions presented in this section accept variadic argument lists of | |
12063 | task functions. Corresponding <code><phrase role="identifier">wait_something</phrase><phrase | |
12064 | role="special">()</phrase></code> functions accepting a container of task | |
12065 | functions are left as an exercise for the interested reader. Those should | |
12066 | actually be simpler. Most of the complexity would arise from overloading | |
12067 | the same name for both purposes. | |
12068 | </para> | |
12069 | </note> | |
12070 | <para> | |
12071 | All the source code for this section is found in <ulink url="../../examples/wait_stuff.cpp">wait_stuff.cpp</ulink>. | |
12072 | </para> | |
12073 | <bridgehead renderas="sect3" id="fiber.when_any.h1"> | |
12074 | <phrase id="fiber.when_any.example_task_function"/><link linkend="fiber.when_any.example_task_function">Example | |
12075 | Task Function</link> | |
12076 | </bridgehead> | |
12077 | <para> | |
12078 | <anchor id="wait_sleeper"/>We found it convenient to model an asynchronous | |
12079 | task using this function: | |
12080 | </para> | |
12081 | <para> | |
12082 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> | |
12083 | <phrase role="identifier">T</phrase> <phrase role="identifier">sleeper_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">T</phrase> <phrase role="identifier">item</phrase><phrase role="special">,</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">ms</phrase><phrase role="special">,</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">thrw</phrase> <phrase role="special">=</phrase> <phrase role="keyword">false</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12084 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ostringstream</phrase> <phrase role="identifier">descb</phrase><phrase role="special">,</phrase> <phrase role="identifier">funcb</phrase><phrase role="special">;</phrase> | |
12085 | <phrase role="identifier">descb</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">item</phrase><phrase role="special">;</phrase> | |
12086 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">desc</phrase><phrase role="special">(</phrase> <phrase role="identifier">descb</phrase><phrase role="special">.</phrase><phrase role="identifier">str</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12087 | <phrase role="identifier">funcb</phrase> <phrase role="special"><<</phrase> <phrase role="string">" sleeper("</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">item</phrase> <phrase role="special"><<</phrase> <phrase role="string">")"</phrase><phrase role="special">;</phrase> | |
12088 | <phrase role="identifier">Verbose</phrase> <phrase role="identifier">v</phrase><phrase role="special">(</phrase> <phrase role="identifier">funcb</phrase><phrase role="special">.</phrase><phrase role="identifier">str</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12089 | ||
12090 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">sleep_for</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">milliseconds</phrase><phrase role="special">(</phrase> <phrase role="identifier">ms</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12091 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">thrw</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12092 | <phrase role="keyword">throw</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">runtime_error</phrase><phrase role="special">(</phrase> <phrase role="identifier">desc</phrase><phrase role="special">);</phrase> | |
12093 | <phrase role="special">}</phrase> | |
12094 | <phrase role="keyword">return</phrase> <phrase role="identifier">item</phrase><phrase role="special">;</phrase> | |
12095 | <phrase role="special">}</phrase> | |
12096 | </programlisting> | |
12097 | </para> | |
12098 | <para> | |
12099 | with type-specific <code><phrase role="identifier">sleeper</phrase><phrase | |
12100 | role="special">()</phrase></code> <quote>front ends</quote> for <code><phrase | |
12101 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase></code>, | |
12102 | <code><phrase role="keyword">double</phrase></code> and <code><phrase role="keyword">int</phrase></code>. | |
12103 | </para> | |
12104 | <para> | |
12105 | <code><phrase role="identifier">Verbose</phrase></code> simply prints a message | |
12106 | to <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
12107 | role="identifier">cout</phrase></code> on construction and destruction. | |
12108 | </para> | |
12109 | <para> | |
12110 | Basically: | |
12111 | </para> | |
12112 | <orderedlist> | |
12113 | <listitem> | |
12114 | <simpara> | |
12115 | <code><phrase role="identifier">sleeper</phrase><phrase role="special">()</phrase></code> | |
12116 | prints a start message; | |
12117 | </simpara> | |
12118 | </listitem> | |
12119 | <listitem> | |
12120 | <simpara> | |
12121 | sleeps for the specified number of milliseconds; | |
12122 | </simpara> | |
12123 | </listitem> | |
12124 | <listitem> | |
12125 | <simpara> | |
12126 | if <code><phrase role="identifier">thrw</phrase></code> is passed as <code><phrase | |
12127 | role="keyword">true</phrase></code>, throws a string description of the | |
12128 | passed <code><phrase role="identifier">item</phrase></code>; | |
12129 | </simpara> | |
12130 | </listitem> | |
12131 | <listitem> | |
12132 | <simpara> | |
12133 | else returns the passed <code><phrase role="identifier">item</phrase></code>. | |
12134 | </simpara> | |
12135 | </listitem> | |
12136 | <listitem> | |
12137 | <simpara> | |
12138 | On the way out, <code><phrase role="identifier">sleeper</phrase><phrase | |
12139 | role="special">()</phrase></code> produces a stop message. | |
12140 | </simpara> | |
12141 | </listitem> | |
12142 | </orderedlist> | |
12143 | <para> | |
12144 | This function will feature in the example calls to the various functions presented | |
12145 | below. | |
12146 | </para> | |
12147 | <section id="fiber.when_any.when_any"> | |
12148 | <title><link linkend="fiber.when_any.when_any">when_any</link></title> | |
12149 | <section id="fiber.when_any.when_any.when_any__simple_completion"> | |
12150 | <title><anchor id="wait_first_simple_section"/><link linkend="fiber.when_any.when_any.when_any__simple_completion">when_any, | |
12151 | simple completion</link></title> | |
12152 | <para> | |
12153 | The simplest case is when you only need to know that the first of a set | |
12154 | of asynchronous tasks has completed — but you don't need to obtain a return | |
12155 | value, and you're confident that they will not throw exceptions. | |
12156 | </para> | |
12157 | <para> | |
12158 | <anchor id="wait_done"/>For this we introduce a <code><phrase role="identifier">Done</phrase></code> | |
12159 | class to wrap a <code><phrase role="keyword">bool</phrase></code> variable | |
12160 | with a <link linkend="class_condition_variable"><code>condition_variable</code></link> and a <link linkend="class_mutex"><code>mutex</code></link>: | |
12161 | </para> | |
12162 | <para> | |
12163 | <programlisting><phrase role="comment">// Wrap canonical pattern for condition_variable + bool flag</phrase> | |
12164 | <phrase role="keyword">struct</phrase> <phrase role="identifier">Done</phrase> <phrase role="special">{</phrase> | |
12165 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
12166 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">condition_variable</phrase> <phrase role="identifier">cond</phrase><phrase role="special">;</phrase> | |
12167 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="identifier">mutex</phrase><phrase role="special">;</phrase> | |
12168 | <phrase role="keyword">bool</phrase> <phrase role="identifier">ready</phrase> <phrase role="special">=</phrase> <phrase role="keyword">false</phrase><phrase role="special">;</phrase> | |
12169 | ||
12170 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
12171 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">Done</phrase> <phrase role="special">></phrase> <phrase role="identifier">ptr</phrase><phrase role="special">;</phrase> | |
12172 | ||
12173 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
12174 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lock</phrase><phrase role="special">(</phrase> <phrase role="identifier">mutex</phrase><phrase role="special">);</phrase> | |
12175 | <phrase role="identifier">cond</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lock</phrase><phrase role="special">,</phrase> <phrase role="special">[</phrase><phrase role="keyword">this</phrase><phrase role="special">](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">ready</phrase><phrase role="special">;</phrase> <phrase role="special">});</phrase> | |
12176 | <phrase role="special">}</phrase> | |
12177 | ||
12178 | <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
12179 | <phrase role="special">{</phrase> | |
12180 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lock</phrase><phrase role="special">(</phrase> <phrase role="identifier">mutex</phrase><phrase role="special">);</phrase> | |
12181 | <phrase role="identifier">ready</phrase> <phrase role="special">=</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
12182 | <phrase role="special">}</phrase> <phrase role="comment">// release mutex</phrase> | |
12183 | <phrase role="identifier">cond</phrase><phrase role="special">.</phrase><phrase role="identifier">notify_one</phrase><phrase role="special">();</phrase> | |
12184 | <phrase role="special">}</phrase> | |
12185 | <phrase role="special">};</phrase> | |
12186 | </programlisting> | |
12187 | </para> | |
12188 | <para> | |
12189 | The pattern we follow throughout this section is to pass a <ulink url="http://www.cplusplus.com/reference/memory/shared_ptr/"><code><phrase | |
12190 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
12191 | role="identifier">shared_ptr</phrase><phrase role="special"><></phrase></code></ulink> | |
12192 | to the relevant synchronization object to the various tasks' fiber functions. | |
12193 | This eliminates nagging questions about the lifespan of the synchronization | |
12194 | object relative to the last of the fibers. | |
12195 | </para> | |
12196 | <para> | |
12197 | <anchor id="wait_first_simple"/><code><phrase role="identifier">wait_first_simple</phrase><phrase | |
12198 | role="special">()</phrase></code> uses that tactic for <link linkend="wait_done"><code><phrase | |
12199 | role="identifier">Done</phrase></code></link>: | |
12200 | </para> | |
12201 | <para> | |
12202 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12203 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_first_simple</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12204 | <phrase role="comment">// Use shared_ptr because each function's fiber will bind it separately,</phrase> | |
12205 | <phrase role="comment">// and we're going to return before the last of them completes.</phrase> | |
12206 | <phrase role="keyword">auto</phrase> <phrase role="identifier">done</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">Done</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
12207 | <phrase role="identifier">wait_first_simple_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">done</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12208 | <phrase role="identifier">done</phrase><phrase role="special">-></phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
12209 | <phrase role="special">}</phrase> | |
12210 | </programlisting> | |
12211 | </para> | |
12212 | <para> | |
12213 | <anchor id="wait_first_simple_impl"/><code><phrase role="identifier">wait_first_simple_impl</phrase><phrase | |
12214 | role="special">()</phrase></code> is an ordinary recursion over the argument | |
12215 | pack, capturing <code><phrase role="identifier">Done</phrase><phrase role="special">::</phrase><phrase | |
12216 | role="identifier">ptr</phrase></code> for each new fiber: | |
12217 | </para> | |
12218 | <para> | |
12219 | <programlisting><phrase role="comment">// Degenerate case: when there are no functions to wait for, return</phrase> | |
12220 | <phrase role="comment">// immediately.</phrase> | |
12221 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_first_simple_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">Done</phrase><phrase role="special">::</phrase><phrase role="identifier">ptr</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12222 | <phrase role="special">}</phrase> | |
12223 | ||
12224 | <phrase role="comment">// When there's at least one function to wait for, launch it and recur to</phrase> | |
12225 | <phrase role="comment">// process the rest.</phrase> | |
12226 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12227 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_first_simple_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">Done</phrase><phrase role="special">::</phrase><phrase role="identifier">ptr</phrase> <phrase role="identifier">done</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12228 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="special">[</phrase><phrase role="identifier">done</phrase><phrase role="special">,</phrase> <phrase role="identifier">function</phrase><phrase role="special">](){</phrase> | |
12229 | <phrase role="identifier">function</phrase><phrase role="special">();</phrase> | |
12230 | <phrase role="identifier">done</phrase><phrase role="special">-></phrase><phrase role="identifier">notify</phrase><phrase role="special">();</phrase> | |
12231 | <phrase role="special">}).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
12232 | <phrase role="identifier">wait_first_simple_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">done</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12233 | <phrase role="special">}</phrase> | |
12234 | </programlisting> | |
12235 | </para> | |
12236 | <para> | |
12237 | The body of the fiber's lambda is extremely simple, as promised: call the | |
12238 | function, notify <link linkend="wait_done"><code><phrase role="identifier">Done</phrase></code></link> | |
12239 | when it returns. The first fiber to do so allows <code><phrase role="identifier">wait_first_simple</phrase><phrase | |
12240 | role="special">()</phrase></code> to return — which is why it's useful to | |
12241 | have <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
12242 | role="identifier">shared_ptr</phrase><phrase role="special"><</phrase><phrase | |
12243 | role="identifier">Done</phrase><phrase role="special">></phrase></code> | |
12244 | manage the lifespan of our <code><phrase role="identifier">Done</phrase></code> | |
12245 | object rather than declaring it as a stack variable in <code><phrase role="identifier">wait_first_simple</phrase><phrase | |
12246 | role="special">()</phrase></code>. | |
12247 | </para> | |
12248 | <para> | |
12249 | This is how you might call it: | |
12250 | </para> | |
12251 | <para> | |
12252 | <programlisting><phrase role="identifier">wait_first_simple</phrase><phrase role="special">(</phrase> | |
12253 | <phrase role="special">[](){</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfs_long"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12254 | <phrase role="special">[](){</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfs_medium"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12255 | <phrase role="special">[](){</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfs_short"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12256 | </programlisting> | |
12257 | </para> | |
12258 | <para> | |
12259 | In this example, control resumes after <code><phrase role="identifier">wait_first_simple</phrase><phrase | |
12260 | role="special">()</phrase></code> when <link linkend="wait_sleeper"><code><phrase | |
12261 | role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase | |
12262 | role="string">"wfs_short"</phrase><phrase role="special">,</phrase> | |
12263 | <phrase role="number">50</phrase><phrase role="special">)</phrase></code></link> | |
12264 | completes — even though the other two <code><phrase role="identifier">sleeper</phrase><phrase | |
12265 | role="special">()</phrase></code> fibers are still running. | |
12266 | </para> | |
12267 | </section> | |
12268 | <section id="fiber.when_any.when_any.when_any__return_value"> | |
12269 | <title><link linkend="fiber.when_any.when_any.when_any__return_value">when_any, | |
12270 | return value</link></title> | |
12271 | <para> | |
12272 | It seems more useful to add the ability to capture the return value from | |
12273 | the first of the task functions to complete. Again, we assume that none | |
12274 | will throw an exception. | |
12275 | </para> | |
12276 | <para> | |
12277 | One tactic would be to adapt our <link linkend="wait_done"><code><phrase | |
12278 | role="identifier">Done</phrase></code></link> class to store the first | |
12279 | of the return values, rather than a simple <code><phrase role="keyword">bool</phrase></code>. | |
12280 | However, we choose instead to use a <link linkend="class_unbounded_channel"><code>unbounded_channel<></code></link>. | |
12281 | We'll only need to enqueue the first value, so we'll <link linkend="unbounded_channel_close"><code>unbounded_channel::close()</code></link> it | |
12282 | once we've retrieved that value. Subsequent <code><phrase role="identifier">push</phrase><phrase | |
12283 | role="special">()</phrase></code> calls will return <code><phrase role="identifier">closed</phrase></code>. | |
12284 | </para> | |
12285 | <para> | |
12286 | <anchor id="wait_first_value"/> | |
12287 | <programlisting><phrase role="comment">// Assume that all passed functions have the same return type. The return type</phrase> | |
12288 | <phrase role="comment">// of wait_first_value() is the return type of the first passed function. It is</phrase> | |
12289 | <phrase role="comment">// simply invalid to pass NO functions.</phrase> | |
12290 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12291 | <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> | |
12292 | <phrase role="identifier">wait_first_value</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12293 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
12294 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase> | |
12295 | <phrase role="keyword">auto</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
12296 | <phrase role="comment">// launch all the relevant fibers</phrase> | |
12297 | <phrase role="identifier">wait_first_value_impl</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">,</phrase> | |
12298 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
12299 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12300 | <phrase role="comment">// retrieve the first value</phrase> | |
12301 | <phrase role="identifier">return_t</phrase> <phrase role="identifier">value</phrase><phrase role="special">(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12302 | <phrase role="comment">// close the channel: no subsequent push() has to succeed</phrase> | |
12303 | <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase> | |
12304 | <phrase role="keyword">return</phrase> <phrase role="identifier">value</phrase><phrase role="special">;</phrase> | |
12305 | <phrase role="special">}</phrase> | |
12306 | </programlisting> | |
12307 | </para> | |
12308 | <para> | |
12309 | <anchor id="wait_first_value_impl"/>The meat of the <code><phrase role="identifier">wait_first_value_impl</phrase><phrase | |
12310 | role="special">()</phrase></code> function is as you might expect: | |
12311 | </para> | |
12312 | <para> | |
12313 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
12314 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_first_value_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel</phrase><phrase role="special">,</phrase> | |
12315 | <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12316 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="special">[</phrase><phrase role="identifier">channel</phrase><phrase role="special">,</phrase> <phrase role="identifier">function</phrase><phrase role="special">](){</phrase> | |
12317 | <phrase role="comment">// Ignore channel_op_status returned by push():</phrase> | |
12318 | <phrase role="comment">// might be closed; we simply don't care.</phrase> | |
12319 | <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">function</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12320 | <phrase role="special">}).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
12321 | <phrase role="special">}</phrase> | |
12322 | </programlisting> | |
12323 | </para> | |
12324 | <para> | |
12325 | It calls the passed function, pushes its return value and ignores the | |
12326 | <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code> | |
12327 | result. You might call it like this: | |
12328 | </para> | |
12329 | <para> | |
12330 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">result</phrase> <phrase role="special">=</phrase> <phrase role="identifier">wait_first_value</phrase><phrase role="special">(</phrase> | |
12331 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfv_third"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12332 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfv_second"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12333 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfv_first"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12334 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_first_value() => "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">result</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
12335 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">result</phrase> <phrase role="special">==</phrase> <phrase role="string">"wfv_first"</phrase><phrase role="special">);</phrase> | |
12336 | </programlisting> | |
12337 | </para> | |
12338 | </section> | |
12339 | <section id="fiber.when_any.when_any.when_any__produce_first_outcome__whether_result_or_exception"> | |
12340 | <title><link linkend="fiber.when_any.when_any.when_any__produce_first_outcome__whether_result_or_exception">when_any, | |
12341 | produce first outcome, whether result or exception</link></title> | |
12342 | <para> | |
12343 | We may not be running in an environment in which we can guarantee no exception | |
12344 | will be thrown by any of our task functions. In that case, the above implementations | |
12345 | of <code><phrase role="identifier">wait_first_something</phrase><phrase | |
12346 | role="special">()</phrase></code> would be naïve: as mentioned in <link | |
12347 | linkend="exceptions">the section on Fiber Management</link>, an uncaught | |
12348 | exception in one of our task fibers would cause <code><phrase role="identifier">std</phrase><phrase | |
12349 | role="special">::</phrase><phrase role="identifier">terminate</phrase><phrase | |
12350 | role="special">()</phrase></code> to be called. | |
12351 | </para> | |
12352 | <para> | |
12353 | Let's at least ensure that such an exception would propagate to the fiber | |
12354 | awaiting the first result. We can use <link linkend="class_future"><code>future<></code></link> to transport | |
12355 | either a return value or an exception. Therefore, we will change <link | |
12356 | linkend="wait_first_value"><code><phrase role="identifier">wait_first_value</phrase><phrase | |
12357 | role="special">()</phrase></code></link>'s <link linkend="class_unbounded_channel"><code>unbounded_channel<></code></link> to | |
12358 | hold <code><phrase role="identifier">future</phrase><phrase role="special"><</phrase> | |
12359 | <phrase role="identifier">T</phrase> <phrase role="special">></phrase></code> | |
12360 | items instead of simply <code><phrase role="identifier">T</phrase></code>. | |
12361 | </para> | |
12362 | <para> | |
12363 | Once we have a <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12364 | in hand, all we need do is call <link linkend="future_get"><code>future::get()</code></link>, which will either | |
12365 | return the value or rethrow the exception. | |
12366 | </para> | |
12367 | <para> | |
12368 | <anchor id="wait_first_outcome"/> | |
12369 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12370 | <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> | |
12371 | <phrase role="identifier">wait_first_outcome</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12372 | <phrase role="comment">// In this case, the value we pass through the channel is actually a</phrase> | |
12373 | <phrase role="comment">// future -- which is already ready. future can carry either a value or an</phrase> | |
12374 | <phrase role="comment">// exception.</phrase> | |
12375 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
12376 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">future_t</phrase><phrase role="special">;</phrase> | |
12377 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">future_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase> | |
12378 | <phrase role="keyword">auto</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
12379 | <phrase role="comment">// launch all the relevant fibers</phrase> | |
12380 | <phrase role="identifier">wait_first_outcome_impl</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">,</phrase> | |
12381 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
12382 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12383 | <phrase role="comment">// retrieve the first future</phrase> | |
12384 | <phrase role="identifier">future_t</phrase> <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12385 | <phrase role="comment">// close the channel: no subsequent push() has to succeed</phrase> | |
12386 | <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase> | |
12387 | <phrase role="comment">// either return value or throw exception</phrase> | |
12388 | <phrase role="keyword">return</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">();</phrase> | |
12389 | <phrase role="special">}</phrase> | |
12390 | </programlisting> | |
12391 | </para> | |
12392 | <para> | |
12393 | So far so good — but there's a timing issue. How should we obtain the <code><phrase | |
12394 | role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12395 | to <link linkend="unbounded_channel_push"><code>unbounded_channel::push()</code></link> on the channel? | |
12396 | </para> | |
12397 | <para> | |
12398 | We could call <link linkend="fibers_async"><code>fibers::async()</code></link>. That would certainly produce | |
12399 | a <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12400 | for the task function. The trouble is that it would return too quickly! | |
12401 | We only want <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12402 | items for <emphasis>completed</emphasis> tasks on our <code><phrase role="identifier">unbounded_channel</phrase><phrase | |
12403 | role="special"><></phrase></code>. In fact, we only want the <code><phrase | |
12404 | role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12405 | for the one that completes first. If each fiber launched by <code><phrase | |
12406 | role="identifier">wait_first_outcome</phrase><phrase role="special">()</phrase></code> | |
12407 | were to <code><phrase role="identifier">push</phrase><phrase role="special">()</phrase></code> | |
12408 | the result of calling <code><phrase role="identifier">async</phrase><phrase | |
12409 | role="special">()</phrase></code>, the channel would only ever report the | |
12410 | result of the leftmost task item — <emphasis>not</emphasis> the one that | |
12411 | completes most quickly. | |
12412 | </para> | |
12413 | <para> | |
12414 | Calling <link linkend="future_get"><code>future::get()</code></link> on the future returned by <code><phrase | |
12415 | role="identifier">async</phrase><phrase role="special">()</phrase></code> | |
12416 | wouldn't be right. You can only call <code><phrase role="identifier">get</phrase><phrase | |
12417 | role="special">()</phrase></code> once per <code><phrase role="identifier">future</phrase><phrase | |
12418 | role="special"><></phrase></code> instance! And if there were an | |
12419 | exception, it would be rethrown inside the helper fiber at the producer | |
12420 | end of the channel, rather than propagated to the consumer end. | |
12421 | </para> | |
12422 | <para> | |
12423 | We could call <link linkend="future_wait"><code>future::wait()</code></link>. That would block the helper fiber | |
12424 | until the <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12425 | became ready, at which point we could <code><phrase role="identifier">push</phrase><phrase | |
12426 | role="special">()</phrase></code> it to be retrieved by <code><phrase role="identifier">wait_first_outcome</phrase><phrase | |
12427 | role="special">()</phrase></code>. | |
12428 | </para> | |
12429 | <para> | |
12430 | That would work — but there's a simpler tactic that avoids creating an extra | |
12431 | fiber. We can wrap the task function in a <link linkend="class_packaged_task"><code>packaged_task<></code></link>. | |
12432 | While one naturally thinks of passing a <code><phrase role="identifier">packaged_task</phrase><phrase | |
12433 | role="special"><></phrase></code> to a new fiber — that is, in fact, | |
12434 | what <code><phrase role="identifier">async</phrase><phrase role="special">()</phrase></code> | |
12435 | does — in this case, we're already running in the helper fiber at the producer | |
12436 | end of the channel! We can simply <emphasis>call</emphasis> the <code><phrase | |
12437 | role="identifier">packaged_task</phrase><phrase role="special"><></phrase></code>. | |
12438 | On return from that call, the task function has completed, meaning that | |
12439 | the <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12440 | obtained from the <code><phrase role="identifier">packaged_task</phrase><phrase | |
12441 | role="special"><></phrase></code> is certain to be ready. At that | |
12442 | point we can simply <code><phrase role="identifier">push</phrase><phrase | |
12443 | role="special">()</phrase></code> it to the channel. | |
12444 | </para> | |
12445 | <para> | |
12446 | <anchor id="wait_first_outcome_impl"/> | |
12447 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">CHANNELP</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
12448 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_first_outcome_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">CHANNELP</phrase> <phrase role="identifier">channel</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12449 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> | |
12450 | <phrase role="comment">// Use std::bind() here for C++11 compatibility. C++11 lambda capture</phrase> | |
12451 | <phrase role="comment">// can't move a move-only Fn type, but bind() can. Let bind() move the</phrase> | |
12452 | <phrase role="comment">// channel pointer and the function into the bound object, passing</phrase> | |
12453 | <phrase role="comment">// references into the lambda.</phrase> | |
12454 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">(</phrase> | |
12455 | <phrase role="special">[](</phrase> <phrase role="identifier">CHANNELP</phrase> <phrase role="special">&</phrase> <phrase role="identifier">channel</phrase><phrase role="special">,</phrase> | |
12456 | <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">function</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12457 | <phrase role="comment">// Instantiate a packaged_task to capture any exception thrown by</phrase> | |
12458 | <phrase role="comment">// function.</phrase> | |
12459 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">packaged_task</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase><phrase role="special">()</phrase> <phrase role="special">></phrase> <phrase role="identifier">task</phrase><phrase role="special">(</phrase> <phrase role="identifier">function</phrase><phrase role="special">);</phrase> | |
12460 | <phrase role="comment">// Immediately run this packaged_task on same fiber. We want</phrase> | |
12461 | <phrase role="comment">// function() to have completed BEFORE we push the future.</phrase> | |
12462 | <phrase role="identifier">task</phrase><phrase role="special">();</phrase> | |
12463 | <phrase role="comment">// Pass the corresponding future to consumer. Ignore</phrase> | |
12464 | <phrase role="comment">// channel_op_status returned by push(): might be closed; we</phrase> | |
12465 | <phrase role="comment">// simply don't care.</phrase> | |
12466 | <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">task</phrase><phrase role="special">.</phrase><phrase role="identifier">get_future</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12467 | <phrase role="special">},</phrase> | |
12468 | <phrase role="identifier">channel</phrase><phrase role="special">,</phrase> | |
12469 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">)</phrase> | |
12470 | <phrase role="special">)).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
12471 | <phrase role="special">}</phrase> | |
12472 | </programlisting> | |
12473 | </para> | |
12474 | <para> | |
12475 | Calling it might look like this: | |
12476 | </para> | |
12477 | <para> | |
12478 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">result</phrase> <phrase role="special">=</phrase> <phrase role="identifier">wait_first_outcome</phrase><phrase role="special">(</phrase> | |
12479 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfos_first"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12480 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfos_second"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12481 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfos_third"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12482 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_first_outcome(success) => "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">result</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
12483 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">result</phrase> <phrase role="special">==</phrase> <phrase role="string">"wfos_first"</phrase><phrase role="special">);</phrase> | |
12484 | ||
12485 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">thrown</phrase><phrase role="special">;</phrase> | |
12486 | <phrase role="keyword">try</phrase> <phrase role="special">{</phrase> | |
12487 | <phrase role="identifier">result</phrase> <phrase role="special">=</phrase> <phrase role="identifier">wait_first_outcome</phrase><phrase role="special">(</phrase> | |
12488 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfof_first"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">,</phrase> <phrase role="keyword">true</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12489 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfof_second"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12490 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfof_third"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12491 | <phrase role="special">}</phrase> <phrase role="keyword">catch</phrase> <phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">e</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12492 | <phrase role="identifier">thrown</phrase> <phrase role="special">=</phrase> <phrase role="identifier">e</phrase><phrase role="special">.</phrase><phrase role="identifier">what</phrase><phrase role="special">();</phrase> | |
12493 | <phrase role="special">}</phrase> | |
12494 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_first_outcome(fail) threw '"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">thrown</phrase> | |
12495 | <phrase role="special"><<</phrase> <phrase role="string">"'"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
12496 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">thrown</phrase> <phrase role="special">==</phrase> <phrase role="string">"wfof_first"</phrase><phrase role="special">);</phrase> | |
12497 | </programlisting> | |
12498 | </para> | |
12499 | </section> | |
12500 | <section id="fiber.when_any.when_any.when_any__produce_first_success"> | |
12501 | <title><link linkend="fiber.when_any.when_any.when_any__produce_first_success">when_any, | |
12502 | produce first success</link></title> | |
12503 | <para> | |
12504 | One scenario for <quote>when_any</quote> functionality is when we're redundantly | |
12505 | contacting some number of possibly-unreliable web services. Not only might | |
12506 | they be slow — any one of them might produce a failure rather than the desired | |
12507 | result. | |
12508 | </para> | |
12509 | <para> | |
12510 | In such a case, <link linkend="wait_first_outcome"><code><phrase role="identifier">wait_first_outcome</phrase><phrase | |
12511 | role="special">()</phrase></code></link> isn't the right approach. If one | |
12512 | of the services produces an error quickly, while another follows up with | |
12513 | a real answer, we don't want to prefer the error just because it arrived | |
12514 | first! | |
12515 | </para> | |
12516 | <para> | |
12517 | Given the <code><phrase role="identifier">unbounded_channel</phrase><phrase | |
12518 | role="special"><</phrase> <phrase role="identifier">future</phrase><phrase | |
12519 | role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase | |
12520 | role="special">></phrase> <phrase role="special">></phrase></code> | |
12521 | we already constructed for <code><phrase role="identifier">wait_first_outcome</phrase><phrase | |
12522 | role="special">()</phrase></code>, though, we can readily recast the interface | |
12523 | function to deliver the first <emphasis>successful</emphasis> result. | |
12524 | </para> | |
12525 | <para> | |
12526 | That does beg the question: what if <emphasis>all</emphasis> the task functions | |
12527 | throw an exception? In that case we'd probably better know about it. | |
12528 | </para> | |
12529 | <para> | |
12530 | <anchor id="exception_list"/>The <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4407.html#parallel.exceptions.synopsis">C++ | |
12531 | Parallelism Draft Technical Specification</ulink> proposes a <code><phrase | |
12532 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
12533 | role="identifier">exception_list</phrase></code> exception capable of delivering | |
12534 | a collection of <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
12535 | role="identifier">exception_ptr</phrase></code>s. Until that becomes universally | |
12536 | available, let's fake up an <code><phrase role="identifier">exception_list</phrase></code> | |
12537 | of our own: | |
12538 | </para> | |
12539 | <para> | |
12540 | <programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">exception_list</phrase> <phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">runtime_error</phrase> <phrase role="special">{</phrase> | |
12541 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
12542 | <phrase role="identifier">exception_list</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">what</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
12543 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">runtime_error</phrase><phrase role="special">(</phrase> <phrase role="identifier">what</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12544 | <phrase role="special">}</phrase> | |
12545 | ||
12546 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="special">></phrase> <phrase role="identifier">bundle_t</phrase><phrase role="special">;</phrase> | |
12547 | ||
12548 | <phrase role="comment">// N4407 proposed std::exception_list API</phrase> | |
12549 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">bundle_t</phrase><phrase role="special">::</phrase><phrase role="identifier">const_iterator</phrase> <phrase role="identifier">iterator</phrase><phrase role="special">;</phrase> | |
12550 | ||
12551 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">size</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
12552 | <phrase role="keyword">return</phrase> <phrase role="identifier">bundle_</phrase><phrase role="special">.</phrase><phrase role="identifier">size</phrase><phrase role="special">();</phrase> | |
12553 | <phrase role="special">}</phrase> | |
12554 | ||
12555 | <phrase role="identifier">iterator</phrase> <phrase role="identifier">begin</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
12556 | <phrase role="keyword">return</phrase> <phrase role="identifier">bundle_</phrase><phrase role="special">.</phrase><phrase role="identifier">begin</phrase><phrase role="special">();</phrase> | |
12557 | <phrase role="special">}</phrase> | |
12558 | ||
12559 | <phrase role="identifier">iterator</phrase> <phrase role="identifier">end</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
12560 | <phrase role="keyword">return</phrase> <phrase role="identifier">bundle_</phrase><phrase role="special">.</phrase><phrase role="identifier">end</phrase><phrase role="special">();</phrase> | |
12561 | <phrase role="special">}</phrase> | |
12562 | ||
12563 | <phrase role="comment">// extension to populate</phrase> | |
12564 | <phrase role="keyword">void</phrase> <phrase role="identifier">add</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">ep</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12565 | <phrase role="identifier">bundle_</phrase><phrase role="special">.</phrase><phrase role="identifier">push_back</phrase><phrase role="special">(</phrase> <phrase role="identifier">ep</phrase><phrase role="special">);</phrase> | |
12566 | <phrase role="special">}</phrase> | |
12567 | ||
12568 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
12569 | <phrase role="identifier">bundle_t</phrase> <phrase role="identifier">bundle_</phrase><phrase role="special">;</phrase> | |
12570 | <phrase role="special">};</phrase> | |
12571 | </programlisting> | |
12572 | </para> | |
12573 | <para> | |
12574 | Now we can build <code><phrase role="identifier">wait_first_success</phrase><phrase | |
12575 | role="special">()</phrase></code>, using <link linkend="wait_first_outcome_impl"><code><phrase | |
12576 | role="identifier">wait_first_outcome_impl</phrase><phrase role="special">()</phrase></code></link>. | |
12577 | </para> | |
12578 | <para> | |
12579 | Instead of retrieving only the first <code><phrase role="identifier">future</phrase><phrase | |
12580 | role="special"><></phrase></code> from the channel, we must now loop | |
12581 | over <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12582 | items. Of course we must limit that iteration! If we launch only <code><phrase | |
12583 | role="identifier">count</phrase></code> producer fibers, the <code><phrase | |
12584 | role="special">(</phrase><phrase role="identifier">count</phrase><phrase | |
12585 | role="special">+</phrase><phrase role="number">1</phrase><phrase role="special">)</phrase></code><superscript>st</superscript> | |
12586 | <link linkend="unbounded_channel_pop"><code>unbounded_channel::pop()</code></link> call | |
12587 | would block forever. | |
12588 | </para> | |
12589 | <para> | |
12590 | Given a ready <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code>, | |
12591 | we can distinguish failure by calling <link linkend="future_get_exception_ptr"><code>future::get_exception_ptr()</code></link>. | |
12592 | If the <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code> | |
12593 | in fact contains a result rather than an exception, <code><phrase role="identifier">get_exception_ptr</phrase><phrase | |
12594 | role="special">()</phrase></code> returns <code><phrase role="keyword">nullptr</phrase></code>. | |
12595 | In that case, we can confidently call <link linkend="future_get"><code>future::get()</code></link> to return | |
12596 | that result to our caller. | |
12597 | </para> | |
12598 | <para> | |
12599 | If the <code><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase | |
12600 | role="identifier">exception_ptr</phrase></code> is <emphasis>not</emphasis> | |
12601 | <code><phrase role="keyword">nullptr</phrase></code>, though, we collect | |
12602 | it into our pending <code><phrase role="identifier">exception_list</phrase></code> | |
12603 | and loop back for the next <code><phrase role="identifier">future</phrase><phrase | |
12604 | role="special"><></phrase></code> from the channel. | |
12605 | </para> | |
12606 | <para> | |
12607 | If we fall out of the loop — if every single task fiber threw an exception | |
12608 | — we throw the <code><phrase role="identifier">exception_list</phrase></code> | |
12609 | exception into which we've been collecting those <code><phrase role="identifier">std</phrase><phrase | |
12610 | role="special">::</phrase><phrase role="identifier">exception_ptr</phrase></code>s. | |
12611 | </para> | |
12612 | <para> | |
12613 | <anchor id="wait_first_success"/> | |
12614 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12615 | <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> | |
12616 | <phrase role="identifier">wait_first_success</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12617 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">count</phrase><phrase role="special">(</phrase> <phrase role="number">1</phrase> <phrase role="special">+</phrase> <phrase role="keyword">sizeof</phrase> <phrase role="special">...</phrase> <phrase role="special">(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12618 | <phrase role="comment">// In this case, the value we pass through the channel is actually a</phrase> | |
12619 | <phrase role="comment">// future -- which is already ready. future can carry either a value or an</phrase> | |
12620 | <phrase role="comment">// exception.</phrase> | |
12621 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
12622 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">future_t</phrase><phrase role="special">;</phrase> | |
12623 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">future_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase> | |
12624 | <phrase role="keyword">auto</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
12625 | <phrase role="comment">// launch all the relevant fibers</phrase> | |
12626 | <phrase role="identifier">wait_first_outcome_impl</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">,</phrase> | |
12627 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
12628 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12629 | <phrase role="comment">// instantiate exception_list, just in case</phrase> | |
12630 | <phrase role="identifier">exception_list</phrase> <phrase role="identifier">exceptions</phrase><phrase role="special">(</phrase><phrase role="string">"wait_first_success() produced only errors"</phrase><phrase role="special">);</phrase> | |
12631 | <phrase role="comment">// retrieve up to 'count' results -- but stop there!</phrase> | |
12632 | <phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">i</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> <phrase role="identifier">i</phrase> <phrase role="special"><</phrase> <phrase role="identifier">count</phrase><phrase role="special">;</phrase> <phrase role="special">++</phrase><phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12633 | <phrase role="comment">// retrieve the next future</phrase> | |
12634 | <phrase role="identifier">future_t</phrase> <phrase role="identifier">future</phrase><phrase role="special">(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12635 | <phrase role="comment">// retrieve exception_ptr if any</phrase> | |
12636 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">error</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get_exception_ptr</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12637 | <phrase role="comment">// if no error, then yay, return value</phrase> | |
12638 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">error</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12639 | <phrase role="comment">// close the channel: no subsequent push() has to succeed</phrase> | |
12640 | <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase> | |
12641 | <phrase role="comment">// show caller the value we got</phrase> | |
12642 | <phrase role="keyword">return</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">();</phrase> | |
12643 | <phrase role="special">}</phrase> | |
12644 | ||
12645 | <phrase role="comment">// error is non-null: collect</phrase> | |
12646 | <phrase role="identifier">exceptions</phrase><phrase role="special">.</phrase><phrase role="identifier">add</phrase><phrase role="special">(</phrase> <phrase role="identifier">error</phrase><phrase role="special">);</phrase> | |
12647 | <phrase role="special">}</phrase> | |
12648 | <phrase role="comment">// We only arrive here when every passed function threw an exception.</phrase> | |
12649 | <phrase role="comment">// Throw our collection to inform caller.</phrase> | |
12650 | <phrase role="keyword">throw</phrase> <phrase role="identifier">exceptions</phrase><phrase role="special">;</phrase> | |
12651 | <phrase role="special">}</phrase> | |
12652 | </programlisting> | |
12653 | </para> | |
12654 | <para> | |
12655 | A call might look like this: | |
12656 | </para> | |
12657 | <para> | |
12658 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">result</phrase> <phrase role="special">=</phrase> <phrase role="identifier">wait_first_success</phrase><phrase role="special">(</phrase> | |
12659 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfss_first"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">,</phrase> <phrase role="keyword">true</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12660 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfss_second"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12661 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfss_third"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12662 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_first_success(success) => "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">result</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
12663 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">result</phrase> <phrase role="special">==</phrase> <phrase role="string">"wfss_second"</phrase><phrase role="special">);</phrase> | |
12664 | </programlisting> | |
12665 | </para> | |
12666 | </section> | |
12667 | <section id="fiber.when_any.when_any.when_any__heterogeneous_types"> | |
12668 | <title><link linkend="fiber.when_any.when_any.when_any__heterogeneous_types">when_any, | |
12669 | heterogeneous types</link></title> | |
12670 | <para> | |
12671 | We would be remiss to ignore the case in which the various task functions | |
12672 | have distinct return types. That means that the value returned by the first | |
12673 | of them might have any one of those types. We can express that with <ulink | |
12674 | url="http://www.boost.org/doc/libs/release/doc/html/variant.html">Boost.Variant</ulink>. | |
12675 | </para> | |
12676 | <para> | |
12677 | To keep the example simple, we'll revert to pretending that none of them | |
12678 | can throw an exception. That makes <code><phrase role="identifier">wait_first_value_het</phrase><phrase | |
12679 | role="special">()</phrase></code> strongly resemble <link linkend="wait_first_value"><code><phrase | |
12680 | role="identifier">wait_first_value</phrase><phrase role="special">()</phrase></code></link>. | |
12681 | We can actually reuse <link linkend="wait_first_value_impl"><code><phrase | |
12682 | role="identifier">wait_first_value_impl</phrase><phrase role="special">()</phrase></code></link>, | |
12683 | merely passing <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
12684 | role="identifier">variant</phrase><phrase role="special"><</phrase><phrase | |
12685 | role="identifier">T0</phrase><phrase role="special">,</phrase> <phrase | |
12686 | role="identifier">T1</phrase><phrase role="special">,</phrase> <phrase | |
12687 | role="special">...></phrase></code> as the channel's value type rather | |
12688 | than the common <code><phrase role="identifier">T</phrase></code>! | |
12689 | </para> | |
12690 | <para> | |
12691 | Naturally this could be extended to use <link linkend="wait_first_success"><code><phrase | |
12692 | role="identifier">wait_first_success</phrase><phrase role="special">()</phrase></code></link> | |
12693 | semantics instead. | |
12694 | </para> | |
12695 | <para> | |
12696 | <programlisting><phrase role="comment">// No need to break out the first Fn for interface function: let the compiler</phrase> | |
12697 | <phrase role="comment">// complain if empty.</phrase> | |
12698 | <phrase role="comment">// Our functions have different return types, and we might have to return any</phrase> | |
12699 | <phrase role="comment">// of them. Use a variant, expanding std::result_of<Fn()>::type for each Fn in</phrase> | |
12700 | <phrase role="comment">// parameter pack.</phrase> | |
12701 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12702 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">variant</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">...</phrase> <phrase role="special">></phrase> | |
12703 | <phrase role="identifier">wait_first_value_het</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12704 | <phrase role="comment">// Use unbounded_channel<boost::variant<T1, T2, ...>>; see remarks above.</phrase> | |
12705 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">variant</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">...</phrase> <phrase role="special">></phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
12706 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase> | |
12707 | <phrase role="keyword">auto</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
12708 | <phrase role="comment">// launch all the relevant fibers</phrase> | |
12709 | <phrase role="identifier">wait_first_value_impl</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">,</phrase> | |
12710 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12711 | <phrase role="comment">// retrieve the first value</phrase> | |
12712 | <phrase role="identifier">return_t</phrase> <phrase role="identifier">value</phrase><phrase role="special">(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">value_pop</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
12713 | <phrase role="comment">// close the channel: no subsequent push() has to succeed</phrase> | |
12714 | <phrase role="identifier">channelp</phrase><phrase role="special">-></phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase> | |
12715 | <phrase role="keyword">return</phrase> <phrase role="identifier">value</phrase><phrase role="special">;</phrase> | |
12716 | <phrase role="special">}</phrase> | |
12717 | </programlisting> | |
12718 | </para> | |
12719 | <para> | |
12720 | It might be called like this: | |
12721 | </para> | |
12722 | <para> | |
12723 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">variant</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase><phrase role="special">,</phrase> <phrase role="keyword">double</phrase><phrase role="special">,</phrase> <phrase role="keyword">int</phrase> <phrase role="special">></phrase> <phrase role="identifier">result</phrase> <phrase role="special">=</phrase> | |
12724 | <phrase role="identifier">wait_first_value_het</phrase><phrase role="special">(</phrase> | |
12725 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wfvh_third"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12726 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="number">3.14</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12727 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="number">17</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12728 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_first_value_het() => "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">result</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
12729 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">get</phrase><phrase role="special"><</phrase> <phrase role="keyword">int</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">result</phrase><phrase role="special">)</phrase> <phrase role="special">==</phrase> <phrase role="number">17</phrase><phrase role="special">);</phrase> | |
12730 | </programlisting> | |
12731 | </para> | |
12732 | </section> | |
12733 | <section id="fiber.when_any.when_any.when_any__a_dubious_alternative"> | |
12734 | <title><link linkend="fiber.when_any.when_any.when_any__a_dubious_alternative">when_any, | |
12735 | a dubious alternative</link></title> | |
12736 | <para> | |
12737 | Certain topics in C++ can arouse strong passions, and exceptions are no | |
12738 | exception. We cannot resist mentioning — for purely informational purposes | |
12739 | — that when you need only the <emphasis>first</emphasis> result from some | |
12740 | number of concurrently-running fibers, it would be possible to pass a | |
12741 | <literal>shared_ptr<<link linkend="class_promise"><code>promise<></code></link>></literal> to the | |
12742 | participating fibers, then cause the initiating fiber to call <link linkend="future_get"><code>future::get()</code></link> on | |
12743 | its <link linkend="class_future"><code>future<></code></link>. The first fiber to call <link linkend="promise_set_value"><code>promise::set_value()</code></link> on | |
12744 | that shared <code><phrase role="identifier">promise</phrase></code> will | |
12745 | succeed; subsequent <code><phrase role="identifier">set_value</phrase><phrase | |
12746 | role="special">()</phrase></code> calls on the same <code><phrase role="identifier">promise</phrase></code> | |
12747 | instance will throw <code><phrase role="identifier">future_error</phrase></code>. | |
12748 | </para> | |
12749 | <para> | |
12750 | Use this information at your own discretion. Beware the dark side. | |
12751 | </para> | |
12752 | </section> | |
12753 | </section> | |
12754 | <section id="fiber.when_any.when_all_functionality"> | |
12755 | <title><link linkend="fiber.when_any.when_all_functionality">when_all functionality</link></title> | |
12756 | <section id="fiber.when_any.when_all_functionality.when_all__simple_completion"> | |
12757 | <title><link linkend="fiber.when_any.when_all_functionality.when_all__simple_completion">when_all, | |
12758 | simple completion</link></title> | |
12759 | <para> | |
12760 | For the case in which we must wait for <emphasis>all</emphasis> task functions | |
12761 | to complete — but we don't need results (or expect exceptions) from any of | |
12762 | them — we can write <code><phrase role="identifier">wait_all_simple</phrase><phrase | |
12763 | role="special">()</phrase></code> that looks remarkably like <link linkend="wait_first_simple"><code><phrase | |
12764 | role="identifier">wait_first_simple</phrase><phrase role="special">()</phrase></code></link>. | |
12765 | The difference is that instead of our <link linkend="wait_done"><code><phrase | |
12766 | role="identifier">Done</phrase></code></link> class, we instantiate a <link linkend="class_barrier"><code>barrier</code></link> and | |
12767 | call its <link linkend="barrier_wait"><code>barrier::wait()</code></link>. | |
12768 | </para> | |
12769 | <para> | |
12770 | We initialize the <code><phrase role="identifier">barrier</phrase></code> | |
12771 | with <code><phrase role="special">(</phrase><phrase role="identifier">count</phrase><phrase | |
12772 | role="special">+</phrase><phrase role="number">1</phrase><phrase role="special">)</phrase></code> | |
12773 | because we are launching <code><phrase role="identifier">count</phrase></code> | |
12774 | fibers, plus the <code><phrase role="identifier">wait</phrase><phrase role="special">()</phrase></code> | |
12775 | call within <code><phrase role="identifier">wait_all_simple</phrase><phrase | |
12776 | role="special">()</phrase></code> itself. | |
12777 | </para> | |
12778 | <para> | |
12779 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12780 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_all_simple</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12781 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">count</phrase><phrase role="special">(</phrase> <phrase role="keyword">sizeof</phrase> <phrase role="special">...</phrase> <phrase role="special">(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12782 | <phrase role="comment">// Initialize a barrier(count+1) because we'll immediately wait on it. We</phrase> | |
12783 | <phrase role="comment">// don't want to wake up until 'count' more fibers wait on it. Even though</phrase> | |
12784 | <phrase role="comment">// we'll stick around until the last of them completes, use shared_ptr</phrase> | |
12785 | <phrase role="comment">// anyway because it's easier to be confident about lifespan issues.</phrase> | |
12786 | <phrase role="keyword">auto</phrase> <phrase role="identifier">barrier</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">barrier</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">count</phrase> <phrase role="special">+</phrase> <phrase role="number">1</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12787 | <phrase role="identifier">wait_all_simple_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">barrier</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12788 | <phrase role="identifier">barrier</phrase><phrase role="special">-></phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
12789 | <phrase role="special">}</phrase> | |
12790 | </programlisting> | |
12791 | </para> | |
12792 | <para> | |
12793 | As stated above, the only difference between <code><phrase role="identifier">wait_all_simple_impl</phrase><phrase | |
12794 | role="special">()</phrase></code> and <link linkend="wait_first_simple_impl"><code><phrase | |
12795 | role="identifier">wait_first_simple_impl</phrase><phrase role="special">()</phrase></code></link> | |
12796 | is that the former calls <code><phrase role="identifier">barrier</phrase><phrase | |
12797 | role="special">::</phrase><phrase role="identifier">wait</phrase><phrase | |
12798 | role="special">()</phrase></code> rather than <code><phrase role="identifier">Done</phrase><phrase | |
12799 | role="special">::</phrase><phrase role="identifier">notify</phrase><phrase | |
12800 | role="special">()</phrase></code>: | |
12801 | </para> | |
12802 | <para> | |
12803 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12804 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_all_simple_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">barrier</phrase> <phrase role="special">></phrase> <phrase role="identifier">barrier</phrase><phrase role="special">,</phrase> | |
12805 | <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12806 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> | |
12807 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">bind</phrase><phrase role="special">(</phrase> | |
12808 | <phrase role="special">[](</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">barrier</phrase> <phrase role="special">></phrase> <phrase role="special">&</phrase> <phrase role="identifier">barrier</phrase><phrase role="special">,</phrase> | |
12809 | <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">decay</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">&</phrase> <phrase role="identifier">function</phrase><phrase role="special">)</phrase> <phrase role="keyword">mutable</phrase> <phrase role="special">{</phrase> | |
12810 | <phrase role="identifier">function</phrase><phrase role="special">();</phrase> | |
12811 | <phrase role="identifier">barrier</phrase><phrase role="special">-></phrase><phrase role="identifier">wait</phrase><phrase role="special">();</phrase> | |
12812 | <phrase role="special">},</phrase> | |
12813 | <phrase role="identifier">barrier</phrase><phrase role="special">,</phrase> | |
12814 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">)</phrase> | |
12815 | <phrase role="special">)).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
12816 | <phrase role="identifier">wait_all_simple_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">barrier</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12817 | <phrase role="special">}</phrase> | |
12818 | </programlisting> | |
12819 | </para> | |
12820 | <para> | |
12821 | You might call it like this: | |
12822 | </para> | |
12823 | <para> | |
12824 | <programlisting><phrase role="identifier">wait_all_simple</phrase><phrase role="special">(</phrase> | |
12825 | <phrase role="special">[](){</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"was_long"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12826 | <phrase role="special">[](){</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"was_medium"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12827 | <phrase role="special">[](){</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"was_short"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12828 | </programlisting> | |
12829 | </para> | |
12830 | <para> | |
12831 | Control will not return from the <code><phrase role="identifier">wait_all_simple</phrase><phrase | |
12832 | role="special">()</phrase></code> call until the last of its task functions | |
12833 | has completed. | |
12834 | </para> | |
12835 | </section> | |
12836 | <section id="fiber.when_any.when_all_functionality.when_all__return_values"> | |
12837 | <title><link linkend="fiber.when_any.when_all_functionality.when_all__return_values">when_all, | |
12838 | return values</link></title> | |
12839 | <para> | |
12840 | As soon as we want to collect return values from all the task functions, | |
12841 | we can see right away how to reuse <link linkend="wait_first_value"><code><phrase | |
12842 | role="identifier">wait_first_value</phrase><phrase role="special">()</phrase></code></link>'s | |
12843 | channel<T> for the purpose. All we have to do is avoid closing it | |
12844 | after the first value! | |
12845 | </para> | |
12846 | <para> | |
12847 | But in fact, collecting multiple values raises an interesting question: | |
12848 | do we <emphasis>really</emphasis> want to wait until the slowest of them | |
12849 | has arrived? Wouldn't we rather process each result as soon as it becomes | |
12850 | available? | |
12851 | </para> | |
12852 | <para> | |
12853 | Fortunately we can present both APIs. Let's define <code><phrase role="identifier">wait_all_values_source</phrase><phrase | |
12854 | role="special">()</phrase></code> to return <code><phrase role="identifier">shared_ptr</phrase><phrase | |
12855 | role="special"><</phrase><phrase role="identifier">unbounded_channel</phrase><phrase | |
12856 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase | |
12857 | role="special">>></phrase></code>.<footnote id="fiber.when_any.when_all_functionality.when_all__return_values.f0"> | |
12858 | <para> | |
12859 | We could have used either <link linkend="class_bounded_channel"><code>bounded_channel<></code></link> or | |
12860 | <link linkend="class_unbounded_channel"><code>unbounded_channel<></code></link>. We chose <code><phrase | |
12861 | role="identifier">unbounded_channel</phrase><phrase role="special"><></phrase></code> | |
12862 | on the assumption that its simpler semantics imply a cheaper implementation. | |
12863 | </para> | |
12864 | </footnote> | |
12865 | </para> | |
12866 | <para> | |
12867 | <anchor id="wait_all_values"/>Given <code><phrase role="identifier">wait_all_values_source</phrase><phrase | |
12868 | role="special">()</phrase></code>, it's straightforward to implement <code><phrase | |
12869 | role="identifier">wait_all_values</phrase><phrase role="special">()</phrase></code>: | |
12870 | </para> | |
12871 | <para> | |
12872 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12873 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">></phrase> | |
12874 | <phrase role="identifier">wait_all_values</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12875 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">count</phrase><phrase role="special">(</phrase> <phrase role="number">1</phrase> <phrase role="special">+</phrase> <phrase role="keyword">sizeof</phrase> <phrase role="special">...</phrase> <phrase role="special">(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12876 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
12877 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">vector_t</phrase><phrase role="special">;</phrase> | |
12878 | <phrase role="identifier">vector_t</phrase> <phrase role="identifier">results</phrase><phrase role="special">;</phrase> | |
12879 | <phrase role="identifier">results</phrase><phrase role="special">.</phrase><phrase role="identifier">reserve</phrase><phrase role="special">(</phrase> <phrase role="identifier">count</phrase><phrase role="special">);</phrase> | |
12880 | ||
12881 | <phrase role="comment">// get channel</phrase> | |
12882 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel</phrase> <phrase role="special">=</phrase> | |
12883 | <phrase role="identifier">wait_all_values_source</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
12884 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12885 | <phrase role="comment">// fill results vector</phrase> | |
12886 | <phrase role="identifier">return_t</phrase> <phrase role="identifier">value</phrase><phrase role="special">;</phrase> | |
12887 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">==</phrase> <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">pop</phrase><phrase role="special">(</phrase><phrase role="identifier">value</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12888 | <phrase role="identifier">results</phrase><phrase role="special">.</phrase><phrase role="identifier">push_back</phrase><phrase role="special">(</phrase> <phrase role="identifier">value</phrase><phrase role="special">);</phrase> | |
12889 | <phrase role="special">}</phrase> | |
12890 | <phrase role="comment">// return vector to caller</phrase> | |
12891 | <phrase role="keyword">return</phrase> <phrase role="identifier">results</phrase><phrase role="special">;</phrase> | |
12892 | <phrase role="special">}</phrase> | |
12893 | </programlisting> | |
12894 | </para> | |
12895 | <para> | |
12896 | It might be called like this: | |
12897 | </para> | |
12898 | <para> | |
12899 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">values</phrase> <phrase role="special">=</phrase> | |
12900 | <phrase role="identifier">wait_all_values</phrase><phrase role="special">(</phrase> | |
12901 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wav_late"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12902 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wav_middle"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
12903 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wav_early"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
12904 | </programlisting> | |
12905 | </para> | |
12906 | <para> | |
12907 | As you can see from the loop in <code><phrase role="identifier">wait_all_values</phrase><phrase | |
12908 | role="special">()</phrase></code>, instead of requiring its caller to count | |
12909 | values, we define <code><phrase role="identifier">wait_all_values_source</phrase><phrase | |
12910 | role="special">()</phrase></code> to <link linkend="unbounded_channel_close"><code>unbounded_channel::close()</code></link> the | |
12911 | channel when done. But how do we do that? Each producer fiber is independent. | |
12912 | It has no idea whether it is the last one to <link linkend="unbounded_channel_push"><code>unbounded_channel::push()</code></link> a | |
12913 | value. | |
12914 | </para> | |
12915 | <para> | |
12916 | <anchor id="wait_nchannel"/>We can address that problem with a counting | |
12917 | façade for the <code><phrase role="identifier">unbounded_channel</phrase><phrase | |
12918 | role="special"><></phrase></code>. In fact, our façade need only | |
12919 | support the producer end of the channel. | |
12920 | </para> | |
12921 | <para> | |
12922 | <programlisting><phrase role="comment">// Introduce a channel facade that closes the channel once a specific number</phrase> | |
12923 | <phrase role="comment">// of items has been pushed. This allows an arbitrary consumer to read until</phrase> | |
12924 | <phrase role="comment">// 'closed' without itself having to count items.</phrase> | |
12925 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> | |
12926 | <phrase role="keyword">class</phrase> <phrase role="identifier">nchannel</phrase> <phrase role="special">{</phrase> | |
12927 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
12928 | <phrase role="identifier">nchannel</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">cp</phrase><phrase role="special">,</phrase> | |
12929 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">lm</phrase><phrase role="special">):</phrase> | |
12930 | <phrase role="identifier">channel_</phrase><phrase role="special">(</phrase> <phrase role="identifier">cp</phrase><phrase role="special">),</phrase> | |
12931 | <phrase role="identifier">limit_</phrase><phrase role="special">(</phrase> <phrase role="identifier">lm</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12932 | <phrase role="identifier">assert</phrase><phrase role="special">(</phrase><phrase role="identifier">channel_</phrase><phrase role="special">);</phrase> | |
12933 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="number">0</phrase> <phrase role="special">==</phrase> <phrase role="identifier">limit_</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12934 | <phrase role="identifier">channel_</phrase><phrase role="special">-></phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase> | |
12935 | <phrase role="special">}</phrase> | |
12936 | <phrase role="special">}</phrase> | |
12937 | ||
12938 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">T</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">va</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12939 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase> <phrase role="identifier">ok</phrase> <phrase role="special">=</phrase> | |
12940 | <phrase role="identifier">channel_</phrase><phrase role="special">-></phrase><phrase role="identifier">push</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">va</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12941 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">ok</phrase> <phrase role="special">==</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">&&</phrase> | |
12942 | <phrase role="special">--</phrase><phrase role="identifier">limit_</phrase> <phrase role="special">==</phrase> <phrase role="number">0</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12943 | <phrase role="comment">// after the 'limit_'th successful push, close the channel</phrase> | |
12944 | <phrase role="identifier">channel_</phrase><phrase role="special">-></phrase><phrase role="identifier">close</phrase><phrase role="special">();</phrase> | |
12945 | <phrase role="special">}</phrase> | |
12946 | <phrase role="keyword">return</phrase> <phrase role="identifier">ok</phrase><phrase role="special">;</phrase> | |
12947 | <phrase role="special">}</phrase> | |
12948 | ||
12949 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
12950 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_</phrase><phrase role="special">;</phrase> | |
12951 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">limit_</phrase><phrase role="special">;</phrase> | |
12952 | <phrase role="special">};</phrase> | |
12953 | </programlisting> | |
12954 | </para> | |
12955 | <para> | |
12956 | <anchor id="wait_all_values_source"/>Armed with <code><phrase role="identifier">nchannel</phrase><phrase | |
12957 | role="special"><></phrase></code>, we can implement <code><phrase | |
12958 | role="identifier">wait_all_values_source</phrase><phrase role="special">()</phrase></code>. | |
12959 | It starts just like <link linkend="wait_first_value"><code><phrase role="identifier">wait_first_value</phrase><phrase | |
12960 | role="special">()</phrase></code></link>. The difference is that we wrap | |
12961 | the <code><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase><phrase | |
12962 | role="identifier">T</phrase><phrase role="special">></phrase></code> | |
12963 | with an <code><phrase role="identifier">nchannel</phrase><phrase role="special"><</phrase><phrase | |
12964 | role="identifier">T</phrase><phrase role="special">></phrase></code> | |
12965 | to pass to the producer fibers. | |
12966 | </para> | |
12967 | <para> | |
12968 | Then, of course, instead of popping the first value, closing the channel | |
12969 | and returning it, we simply return the <code><phrase role="identifier">shared_ptr</phrase><phrase | |
12970 | role="special"><</phrase><phrase role="identifier">unbounded_channel</phrase><phrase | |
12971 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase | |
12972 | role="special">>></phrase></code>. | |
12973 | </para> | |
12974 | <para> | |
12975 | <programlisting><phrase role="comment">// Return a shared_ptr<unbounded_channel<T>> from which the caller can</phrase> | |
12976 | <phrase role="comment">// retrieve each new result as it arrives, until 'closed'.</phrase> | |
12977 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
12978 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> | |
12979 | <phrase role="identifier">wait_all_values_source</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
12980 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">count</phrase><phrase role="special">(</phrase> <phrase role="number">1</phrase> <phrase role="special">+</phrase> <phrase role="keyword">sizeof</phrase> <phrase role="special">...</phrase> <phrase role="special">(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12981 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
12982 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase> | |
12983 | <phrase role="comment">// make the channel</phrase> | |
12984 | <phrase role="keyword">auto</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
12985 | <phrase role="comment">// and make an nchannel facade to close it after 'count' items</phrase> | |
12986 | <phrase role="keyword">auto</phrase> <phrase role="identifier">ncp</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">nchannel</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="special">>(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">,</phrase> <phrase role="identifier">count</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
12987 | <phrase role="comment">// pass that nchannel facade to all the relevant fibers</phrase> | |
12988 | <phrase role="identifier">wait_all_values_impl</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">ncp</phrase><phrase role="special">,</phrase> | |
12989 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
12990 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
12991 | <phrase role="comment">// then return the channel for consumer</phrase> | |
12992 | <phrase role="keyword">return</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">;</phrase> | |
12993 | <phrase role="special">}</phrase> | |
12994 | </programlisting> | |
12995 | </para> | |
12996 | <para> | |
12997 | For example: | |
12998 | </para> | |
12999 | <para> | |
13000 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel</phrase> <phrase role="special">=</phrase> | |
13001 | <phrase role="identifier">wait_all_values_source</phrase><phrase role="special">(</phrase> | |
13002 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wavs_third"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13003 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wavs_second"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13004 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wavs_first"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
13005 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">value</phrase><phrase role="special">;</phrase> | |
13006 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">==</phrase> <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">pop</phrase><phrase role="special">(</phrase><phrase role="identifier">value</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13007 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_all_values_source() => '"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">value</phrase> | |
13008 | <phrase role="special"><<</phrase> <phrase role="string">"'"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
13009 | <phrase role="special">}</phrase> | |
13010 | </programlisting> | |
13011 | </para> | |
13012 | <para> | |
13013 | <anchor id="wait_all_values_impl"/><code><phrase role="identifier">wait_all_values_impl</phrase><phrase | |
13014 | role="special">()</phrase></code> really is just like <link linkend="wait_first_value_impl"><code><phrase | |
13015 | role="identifier">wait_first_value_impl</phrase><phrase role="special">()</phrase></code></link> | |
13016 | except for the use of <code><phrase role="identifier">nchannel</phrase><phrase | |
13017 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase | |
13018 | role="special">></phrase></code> rather than <code><phrase role="identifier">unbounded_channel</phrase><phrase | |
13019 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase | |
13020 | role="special">></phrase></code>: | |
13021 | </para> | |
13022 | <para> | |
13023 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">T</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
13024 | <phrase role="keyword">void</phrase> <phrase role="identifier">wait_all_values_impl</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">nchannel</phrase><phrase role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel</phrase><phrase role="special">,</phrase> | |
13025 | <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13026 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="special">[</phrase><phrase role="identifier">channel</phrase><phrase role="special">,</phrase> <phrase role="identifier">function</phrase><phrase role="special">](){</phrase> | |
13027 | <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">push</phrase><phrase role="special">(</phrase><phrase role="identifier">function</phrase><phrase role="special">());</phrase> | |
13028 | <phrase role="special">}).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
13029 | <phrase role="special">}</phrase> | |
13030 | </programlisting> | |
13031 | </para> | |
13032 | </section> | |
13033 | <section id="fiber.when_any.when_all_functionality.when_all_until_first_exception"> | |
13034 | <title><link linkend="fiber.when_any.when_all_functionality.when_all_until_first_exception">when_all | |
13035 | until first exception</link></title> | |
13036 | <para> | |
13037 | Naturally, just as with <link linkend="wait_first_outcome"><code><phrase | |
13038 | role="identifier">wait_first_outcome</phrase><phrase role="special">()</phrase></code></link>, | |
13039 | we can elaborate <link linkend="wait_all_values"><code><phrase role="identifier">wait_all_values</phrase><phrase | |
13040 | role="special">()</phrase></code></link> and <link linkend="wait_all_values_source"><code><phrase | |
13041 | role="identifier">wait_all_values_source</phrase><phrase role="special">()</phrase></code></link> | |
13042 | by passing <code><phrase role="identifier">future</phrase><phrase role="special"><</phrase> | |
13043 | <phrase role="identifier">T</phrase> <phrase role="special">></phrase></code> | |
13044 | instead of plain <code><phrase role="identifier">T</phrase></code>. | |
13045 | </para> | |
13046 | <para> | |
13047 | <anchor id="wait_all_until_error"/><code><phrase role="identifier">wait_all_until_error</phrase><phrase | |
13048 | role="special">()</phrase></code> pops that <code><phrase role="identifier">future</phrase><phrase | |
13049 | role="special"><</phrase> <phrase role="identifier">T</phrase> <phrase | |
13050 | role="special">></phrase></code> and calls its <link linkend="future_get"><code>future::get()</code></link>: | |
13051 | </para> | |
13052 | <para> | |
13053 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
13054 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">></phrase> | |
13055 | <phrase role="identifier">wait_all_until_error</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13056 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">count</phrase><phrase role="special">(</phrase> <phrase role="number">1</phrase> <phrase role="special">+</phrase> <phrase role="keyword">sizeof</phrase> <phrase role="special">...</phrase> <phrase role="special">(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
13057 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
13058 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">future_t</phrase><phrase role="special">;</phrase> | |
13059 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">vector_t</phrase><phrase role="special">;</phrase> | |
13060 | <phrase role="identifier">vector_t</phrase> <phrase role="identifier">results</phrase><phrase role="special">;</phrase> | |
13061 | <phrase role="identifier">results</phrase><phrase role="special">.</phrase><phrase role="identifier">reserve</phrase><phrase role="special">(</phrase> <phrase role="identifier">count</phrase><phrase role="special">);</phrase> | |
13062 | ||
13063 | <phrase role="comment">// get channel</phrase> | |
13064 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> | |
13065 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">future_t</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel</phrase><phrase role="special">(</phrase> | |
13066 | <phrase role="identifier">wait_all_until_error_source</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
13067 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
13068 | <phrase role="comment">// fill results vector</phrase> | |
13069 | <phrase role="identifier">future_t</phrase> <phrase role="identifier">future</phrase><phrase role="special">;</phrase> | |
13070 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">==</phrase> <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13071 | <phrase role="identifier">results</phrase><phrase role="special">.</phrase><phrase role="identifier">push_back</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
13072 | <phrase role="special">}</phrase> | |
13073 | <phrase role="comment">// return vector to caller</phrase> | |
13074 | <phrase role="keyword">return</phrase> <phrase role="identifier">results</phrase><phrase role="special">;</phrase> | |
13075 | <phrase role="special">}</phrase> | |
13076 | </programlisting> | |
13077 | </para> | |
13078 | <para> | |
13079 | For example: | |
13080 | </para> | |
13081 | <para> | |
13082 | <programlisting><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">thrown</phrase><phrase role="special">;</phrase> | |
13083 | <phrase role="keyword">try</phrase> <phrase role="special">{</phrase> | |
13084 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">values</phrase> <phrase role="special">=</phrase> <phrase role="identifier">wait_all_until_error</phrase><phrase role="special">(</phrase> | |
13085 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"waue_late"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13086 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"waue_middle"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">,</phrase> <phrase role="keyword">true</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13087 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"waue_early"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
13088 | <phrase role="special">}</phrase> <phrase role="keyword">catch</phrase> <phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">e</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13089 | <phrase role="identifier">thrown</phrase> <phrase role="special">=</phrase> <phrase role="identifier">e</phrase><phrase role="special">.</phrase><phrase role="identifier">what</phrase><phrase role="special">();</phrase> | |
13090 | <phrase role="special">}</phrase> | |
13091 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_all_until_error(fail) threw '"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">thrown</phrase> | |
13092 | <phrase role="special"><<</phrase> <phrase role="string">"'"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
13093 | </programlisting> | |
13094 | </para> | |
13095 | <para> | |
13096 | <anchor id="wait_all_until_error_source"/>Naturally this complicates the | |
13097 | API for <code><phrase role="identifier">wait_all_until_error_source</phrase><phrase | |
13098 | role="special">()</phrase></code>. The caller must both retrieve a <code><phrase | |
13099 | role="identifier">future</phrase><phrase role="special"><</phrase> | |
13100 | <phrase role="identifier">T</phrase> <phrase role="special">></phrase></code> | |
13101 | and call its <code><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
13102 | method. It would, of course, be possible to return a façade over the consumer | |
13103 | end of the channel that would implicitly perform the <code><phrase role="identifier">get</phrase><phrase | |
13104 | role="special">()</phrase></code> and return a simple <code><phrase role="identifier">T</phrase></code> | |
13105 | (or throw). | |
13106 | </para> | |
13107 | <para> | |
13108 | The implementation is just as you would expect. Notice, however, that we | |
13109 | can reuse <link linkend="wait_first_outcome_impl"><code><phrase role="identifier">wait_first_outcome_impl</phrase><phrase | |
13110 | role="special">()</phrase></code></link>, passing the <code><phrase role="identifier">nchannel</phrase><phrase | |
13111 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase | |
13112 | role="special">></phrase></code> rather than <code><phrase role="identifier">unbounded_channel</phrase><phrase | |
13113 | role="special"><</phrase><phrase role="identifier">T</phrase><phrase | |
13114 | role="special">></phrase></code>. | |
13115 | </para> | |
13116 | <para> | |
13117 | <programlisting><phrase role="comment">// Return a shared_ptr<unbounded_channel<future<T>>> from which the caller can</phrase> | |
13118 | <phrase role="comment">// get() each new result as it arrives, until 'closed'.</phrase> | |
13119 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
13120 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> | |
13121 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> | |
13122 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> | |
13123 | <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> | |
13124 | <phrase role="identifier">wait_all_until_error_source</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13125 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">count</phrase><phrase role="special">(</phrase> <phrase role="number">1</phrase> <phrase role="special">+</phrase> <phrase role="keyword">sizeof</phrase> <phrase role="special">...</phrase> <phrase role="special">(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
13126 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
13127 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">future_t</phrase><phrase role="special">;</phrase> | |
13128 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">future_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">channel_t</phrase><phrase role="special">;</phrase> | |
13129 | <phrase role="comment">// make the channel</phrase> | |
13130 | <phrase role="keyword">auto</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">channel_t</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
13131 | <phrase role="comment">// and make an nchannel facade to close it after 'count' items</phrase> | |
13132 | <phrase role="keyword">auto</phrase> <phrase role="identifier">ncp</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">make_shared</phrase><phrase role="special"><</phrase> <phrase role="identifier">nchannel</phrase><phrase role="special"><</phrase> <phrase role="identifier">future_t</phrase> <phrase role="special">></phrase> <phrase role="special">>(</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">,</phrase> <phrase role="identifier">count</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
13133 | <phrase role="comment">// pass that nchannel facade to all the relevant fibers</phrase> | |
13134 | <phrase role="identifier">wait_first_outcome_impl</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">ncp</phrase><phrase role="special">,</phrase> | |
13135 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
13136 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
13137 | <phrase role="comment">// then return the channel for consumer</phrase> | |
13138 | <phrase role="keyword">return</phrase> <phrase role="identifier">channelp</phrase><phrase role="special">;</phrase> | |
13139 | <phrase role="special">}</phrase> | |
13140 | </programlisting> | |
13141 | </para> | |
13142 | <para> | |
13143 | For example: | |
13144 | </para> | |
13145 | <para> | |
13146 | <programlisting><phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="identifier">future_t</phrase><phrase role="special">;</phrase> | |
13147 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">future_t</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel</phrase> <phrase role="special">=</phrase> | |
13148 | <phrase role="identifier">wait_all_until_error_source</phrase><phrase role="special">(</phrase> | |
13149 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wauess_third"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13150 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wauess_second"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13151 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wauess_first"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
13152 | <phrase role="identifier">future_t</phrase> <phrase role="identifier">future</phrase><phrase role="special">;</phrase> | |
13153 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">==</phrase> <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13154 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">value</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
13155 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_all_until_error_source(success) => '"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">value</phrase> | |
13156 | <phrase role="special"><<</phrase> <phrase role="string">"'"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
13157 | <phrase role="special">}</phrase> | |
13158 | </programlisting> | |
13159 | </para> | |
13160 | </section> | |
13161 | <section id="fiber.when_any.when_all_functionality.wait_all__collecting_all_exceptions"> | |
13162 | <title><link linkend="fiber.when_any.when_all_functionality.wait_all__collecting_all_exceptions">wait_all, | |
13163 | collecting all exceptions</link></title> | |
13164 | <para> | |
13165 | <anchor id="wait_all_collect_errors"/>Given <link linkend="wait_all_until_error_source"><code><phrase | |
13166 | role="identifier">wait_all_until_error_source</phrase><phrase role="special">()</phrase></code></link>, | |
13167 | it might be more reasonable to make a <code><phrase role="identifier">wait_all_</phrase><phrase | |
13168 | role="special">...()</phrase></code> that collects <emphasis>all</emphasis> | |
13169 | errors instead of presenting only the first: | |
13170 | </para> | |
13171 | <para> | |
13172 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
13173 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="special">></phrase> | |
13174 | <phrase role="identifier">wait_all_collect_errors</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">function</phrase><phrase role="special">,</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13175 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">size_t</phrase> <phrase role="identifier">count</phrase><phrase role="special">(</phrase> <phrase role="number">1</phrase> <phrase role="special">+</phrase> <phrase role="keyword">sizeof</phrase> <phrase role="special">...</phrase> <phrase role="special">(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
13176 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">result_of</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase><phrase role="special">()</phrase> <phrase role="special">>::</phrase><phrase role="identifier">type</phrase> <phrase role="identifier">return_t</phrase><phrase role="special">;</phrase> | |
13177 | <phrase role="keyword">typedef</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">future</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">future_t</phrase><phrase role="special">;</phrase> | |
13178 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="identifier">return_t</phrase> <phrase role="special">></phrase> <phrase role="identifier">vector_t</phrase><phrase role="special">;</phrase> | |
13179 | <phrase role="identifier">vector_t</phrase> <phrase role="identifier">results</phrase><phrase role="special">;</phrase> | |
13180 | <phrase role="identifier">results</phrase><phrase role="special">.</phrase><phrase role="identifier">reserve</phrase><phrase role="special">(</phrase> <phrase role="identifier">count</phrase><phrase role="special">);</phrase> | |
13181 | <phrase role="identifier">exception_list</phrase> <phrase role="identifier">exceptions</phrase><phrase role="special">(</phrase><phrase role="string">"wait_all_collect_errors() exceptions"</phrase><phrase role="special">);</phrase> | |
13182 | ||
13183 | <phrase role="comment">// get channel</phrase> | |
13184 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">shared_ptr</phrase><phrase role="special"><</phrase> | |
13185 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">unbounded_channel</phrase><phrase role="special"><</phrase> <phrase role="identifier">future_t</phrase> <phrase role="special">></phrase> <phrase role="special">></phrase> <phrase role="identifier">channel</phrase><phrase role="special">(</phrase> | |
13186 | <phrase role="identifier">wait_all_until_error_source</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">function</phrase><phrase role="special">),</phrase> | |
13187 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
13188 | <phrase role="comment">// fill results and/or exceptions vectors</phrase> | |
13189 | <phrase role="identifier">future_t</phrase> <phrase role="identifier">future</phrase><phrase role="special">;</phrase> | |
13190 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">channel_op_status</phrase><phrase role="special">::</phrase><phrase role="identifier">success</phrase> <phrase role="special">==</phrase> <phrase role="identifier">channel</phrase><phrase role="special">-></phrase><phrase role="identifier">pop</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13191 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">exception_ptr</phrase> <phrase role="identifier">exp</phrase> <phrase role="special">=</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get_exception_ptr</phrase><phrase role="special">();</phrase> | |
13192 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">exp</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13193 | <phrase role="identifier">results</phrase><phrase role="special">.</phrase><phrase role="identifier">push_back</phrase><phrase role="special">(</phrase> <phrase role="identifier">future</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
13194 | <phrase role="special">}</phrase> <phrase role="keyword">else</phrase> <phrase role="special">{</phrase> | |
13195 | <phrase role="identifier">exceptions</phrase><phrase role="special">.</phrase><phrase role="identifier">add</phrase><phrase role="special">(</phrase> <phrase role="identifier">exp</phrase><phrase role="special">);</phrase> | |
13196 | <phrase role="special">}</phrase> | |
13197 | <phrase role="special">}</phrase> | |
13198 | <phrase role="comment">// if there were any exceptions, throw</phrase> | |
13199 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">exceptions</phrase><phrase role="special">.</phrase><phrase role="identifier">size</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13200 | <phrase role="keyword">throw</phrase> <phrase role="identifier">exceptions</phrase><phrase role="special">;</phrase> | |
13201 | <phrase role="special">}</phrase> | |
13202 | <phrase role="comment">// no exceptions: return vector to caller</phrase> | |
13203 | <phrase role="keyword">return</phrase> <phrase role="identifier">results</phrase><phrase role="special">;</phrase> | |
13204 | <phrase role="special">}</phrase> | |
13205 | </programlisting> | |
13206 | </para> | |
13207 | <para> | |
13208 | The implementation is a simple variation on <link linkend="wait_first_success"><code><phrase | |
13209 | role="identifier">wait_first_success</phrase><phrase role="special">()</phrase></code></link>, | |
13210 | using the same <link linkend="exception_list"><code><phrase role="identifier">exception_list</phrase></code></link> | |
13211 | exception class. | |
13212 | </para> | |
13213 | </section> | |
13214 | <section id="fiber.when_any.when_all_functionality.when_all__heterogeneous_types"> | |
13215 | <title><link linkend="fiber.when_any.when_all_functionality.when_all__heterogeneous_types">when_all, | |
13216 | heterogeneous types</link></title> | |
13217 | <para> | |
13218 | But what about the case when we must wait for all results of different | |
13219 | types? | |
13220 | </para> | |
13221 | <para> | |
13222 | We can present an API that is frankly quite cool. Consider a sample struct: | |
13223 | </para> | |
13224 | <para> | |
13225 | <programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">Data</phrase> <phrase role="special">{</phrase> | |
13226 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">str</phrase><phrase role="special">;</phrase> | |
13227 | <phrase role="keyword">double</phrase> <phrase role="identifier">inexact</phrase><phrase role="special">;</phrase> | |
13228 | <phrase role="keyword">int</phrase> <phrase role="identifier">exact</phrase><phrase role="special">;</phrase> | |
13229 | ||
13230 | <phrase role="keyword">friend</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ostream</phrase><phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special"><<(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ostream</phrase><phrase role="special">&</phrase> <phrase role="identifier">out</phrase><phrase role="special">,</phrase> <phrase role="identifier">Data</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">data</phrase><phrase role="special">);</phrase> | |
13231 | <phrase role="special">...</phrase> | |
13232 | <phrase role="special">};</phrase> | |
13233 | </programlisting> | |
13234 | </para> | |
13235 | <para> | |
13236 | Let's fill its members from task functions all running concurrently: | |
13237 | </para> | |
13238 | <para> | |
13239 | <programlisting><phrase role="identifier">Data</phrase> <phrase role="identifier">data</phrase> <phrase role="special">=</phrase> <phrase role="identifier">wait_all_members</phrase><phrase role="special"><</phrase> <phrase role="identifier">Data</phrase> <phrase role="special">>(</phrase> | |
13240 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wams_left"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13241 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="number">3.14</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13242 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="number">17</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
13243 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_all_members<Data>(success) => "</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">data</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
13244 | </programlisting> | |
13245 | </para> | |
13246 | <para> | |
13247 | Note that for this case, we abandon the notion of capturing the earliest | |
13248 | result first, and so on: we must fill exactly the passed struct in left-to-right | |
13249 | order. | |
13250 | </para> | |
13251 | <para> | |
13252 | That permits a beautifully simple implementation: | |
13253 | </para> | |
13254 | <para> | |
13255 | <programlisting><phrase role="comment">// Explicitly pass Result. This can be any type capable of being initialized</phrase> | |
13256 | <phrase role="comment">// from the results of the passed functions, such as a struct.</phrase> | |
13257 | <phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Result</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">></phrase> | |
13258 | <phrase role="identifier">Result</phrase> <phrase role="identifier">wait_all_members</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13259 | <phrase role="comment">// Run each of the passed functions on a separate fiber, passing all their</phrase> | |
13260 | <phrase role="comment">// futures to helper function for processing.</phrase> | |
13261 | <phrase role="keyword">return</phrase> <phrase role="identifier">wait_all_members_get</phrase><phrase role="special"><</phrase> <phrase role="identifier">Result</phrase> <phrase role="special">>(</phrase> | |
13262 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">async</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">forward</phrase><phrase role="special"><</phrase> <phrase role="identifier">Fns</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">functions</phrase><phrase role="special">)</phrase> <phrase role="special">)</phrase> <phrase role="special">...</phrase> <phrase role="special">);</phrase> | |
13263 | <phrase role="special">}</phrase> | |
13264 | </programlisting> | |
13265 | </para> | |
13266 | <para> | |
13267 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Result</phrase><phrase role="special">,</phrase> <phrase role="keyword">typename</phrase> <phrase role="special">...</phrase> <phrase role="identifier">Futures</phrase> <phrase role="special">></phrase> | |
13268 | <phrase role="identifier">Result</phrase> <phrase role="identifier">wait_all_members_get</phrase><phrase role="special">(</phrase> <phrase role="identifier">Futures</phrase> <phrase role="special">&&</phrase> <phrase role="special">...</phrase> <phrase role="identifier">futures</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13269 | <phrase role="comment">// Fetch the results from the passed futures into Result's initializer</phrase> | |
13270 | <phrase role="comment">// list. It's true that the get() calls here will block the implicit</phrase> | |
13271 | <phrase role="comment">// iteration over futures -- but that doesn't matter because we won't be</phrase> | |
13272 | <phrase role="comment">// done until the slowest of them finishes anyway. As results are</phrase> | |
13273 | <phrase role="comment">// processed in argument-list order rather than order of completion, the</phrase> | |
13274 | <phrase role="comment">// leftmost get() to throw an exception will cause that exception to</phrase> | |
13275 | <phrase role="comment">// propagate to the caller.</phrase> | |
13276 | <phrase role="keyword">return</phrase> <phrase role="identifier">Result</phrase><phrase role="special">{</phrase> <phrase role="identifier">futures</phrase><phrase role="special">.</phrase><phrase role="identifier">get</phrase><phrase role="special">()</phrase> <phrase role="special">...</phrase> <phrase role="special">};</phrase> | |
13277 | <phrase role="special">}</phrase> | |
13278 | </programlisting> | |
13279 | </para> | |
13280 | <para> | |
13281 | It is tempting to try to implement <code><phrase role="identifier">wait_all_members</phrase><phrase | |
13282 | role="special">()</phrase></code> as a one-liner like this: | |
13283 | </para> | |
13284 | <programlisting><phrase role="keyword">return</phrase> <phrase role="identifier">Result</phrase><phrase role="special">{</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">async</phrase><phrase role="special">(</phrase><phrase role="identifier">functions</phrase><phrase role="special">).</phrase><phrase role="identifier">get</phrase><phrase role="special">()...</phrase> <phrase role="special">};</phrase> | |
13285 | </programlisting> | |
13286 | <para> | |
13287 | The trouble with this tactic is that it would serialize all the task functions. | |
13288 | The runtime makes a single pass through <code><phrase role="identifier">functions</phrase></code>, | |
13289 | calling <link linkend="fibers_async"><code>fibers::async()</code></link> for each and then immediately calling | |
13290 | <link linkend="future_get"><code>future::get()</code></link> on its returned <code><phrase role="identifier">future</phrase><phrase | |
13291 | role="special"><></phrase></code>. That blocks the implicit loop. | |
13292 | The above is almost equivalent to writing: | |
13293 | </para> | |
13294 | <programlisting><phrase role="keyword">return</phrase> <phrase role="identifier">Result</phrase><phrase role="special">{</phrase> <phrase role="identifier">functions</phrase><phrase role="special">()...</phrase> <phrase role="special">};</phrase> | |
13295 | </programlisting> | |
13296 | <para> | |
13297 | in which, of course, there is no concurrency at all. | |
13298 | </para> | |
13299 | <para> | |
13300 | Passing the argument pack through a function-call boundary (<code><phrase | |
13301 | role="identifier">wait_all_members_get</phrase><phrase role="special">()</phrase></code>) | |
13302 | forces the runtime to make <emphasis>two</emphasis> passes: one in <code><phrase | |
13303 | role="identifier">wait_all_members</phrase><phrase role="special">()</phrase></code> | |
13304 | to collect the <code><phrase role="identifier">future</phrase><phrase role="special"><></phrase></code>s | |
13305 | from all the <code><phrase role="identifier">async</phrase><phrase role="special">()</phrase></code> | |
13306 | calls, the second in <code><phrase role="identifier">wait_all_members_get</phrase><phrase | |
13307 | role="special">()</phrase></code> to fetch each of the results. | |
13308 | </para> | |
13309 | <para> | |
13310 | As noted in comments, within the <code><phrase role="identifier">wait_all_members_get</phrase><phrase | |
13311 | role="special">()</phrase></code> parameter pack expansion pass, the blocking | |
13312 | behavior of <code><phrase role="identifier">get</phrase><phrase role="special">()</phrase></code> | |
13313 | becomes irrelevant. Along the way, we will hit the <code><phrase role="identifier">get</phrase><phrase | |
13314 | role="special">()</phrase></code> for the slowest task function; after | |
13315 | that every subsequent <code><phrase role="identifier">get</phrase><phrase | |
13316 | role="special">()</phrase></code> will complete in trivial time. | |
13317 | </para> | |
13318 | <para> | |
13319 | By the way, we could also use this same API to fill a vector or other collection: | |
13320 | </para> | |
13321 | <para> | |
13322 | <programlisting><phrase role="comment">// If we don't care about obtaining results as soon as they arrive, and we</phrase> | |
13323 | <phrase role="comment">// prefer a result vector in passed argument order rather than completion</phrase> | |
13324 | <phrase role="comment">// order, wait_all_members() is another possible implementation of</phrase> | |
13325 | <phrase role="comment">// wait_all_until_error().</phrase> | |
13326 | <phrase role="keyword">auto</phrase> <phrase role="identifier">strings</phrase> <phrase role="special">=</phrase> <phrase role="identifier">wait_all_members</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">vector</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="special">></phrase> <phrase role="special">>(</phrase> | |
13327 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wamv_left"</phrase><phrase role="special">,</phrase> <phrase role="number">150</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13328 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wamv_middle"</phrase><phrase role="special">,</phrase> <phrase role="number">100</phrase><phrase role="special">);</phrase> <phrase role="special">},</phrase> | |
13329 | <phrase role="special">[](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">sleeper</phrase><phrase role="special">(</phrase><phrase role="string">"wamv_right"</phrase><phrase role="special">,</phrase> <phrase role="number">50</phrase><phrase role="special">);</phrase> <phrase role="special">});</phrase> | |
13330 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"wait_all_members<vector>() =>"</phrase><phrase role="special">;</phrase> | |
13331 | <phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">str</phrase> <phrase role="special">:</phrase> <phrase role="identifier">strings</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13332 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">" '"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">str</phrase> <phrase role="special"><<</phrase> <phrase role="string">"'"</phrase><phrase role="special">;</phrase> | |
13333 | <phrase role="special">}</phrase> | |
13334 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase> | |
13335 | </programlisting> | |
13336 | </para> | |
13337 | </section> | |
13338 | </section> | |
13339 | </section> | |
13340 | <section id="fiber.integration"> | |
13341 | <title><anchor id="integration"/><link linkend="fiber.integration">Sharing a | |
13342 | Thread with Another Main Loop</link></title> | |
13343 | <section id="fiber.integration.overview"> | |
13344 | <title><link linkend="fiber.integration.overview">Overview</link></title> | |
13345 | <para> | |
13346 | As always with cooperative concurrency, it is important not to let any one | |
13347 | fiber monopolize the processor too long: that could <quote>starve</quote> | |
13348 | other ready fibers. This section discusses a couple of solutions. | |
13349 | </para> | |
13350 | </section> | |
13351 | <section id="fiber.integration.event_driven_program"> | |
13352 | <title><link linkend="fiber.integration.event_driven_program">Event-Driven | |
13353 | Program</link></title> | |
13354 | <para> | |
13355 | Consider a classic event-driven program, organized around a main loop that | |
13356 | fetches and dispatches incoming I/O events. You are introducing <emphasis | |
13357 | role="bold">Boost.Fiber</emphasis> because certain asynchronous I/O sequences | |
13358 | are logically sequential, and for those you want to write and maintain code | |
13359 | that looks and acts sequential. | |
13360 | </para> | |
13361 | <para> | |
13362 | You are launching fibers on the application’s main thread because certain | |
13363 | of their actions will affect its user interface, and the application’s UI | |
13364 | framework permits UI operations only on the main thread. Or perhaps those | |
13365 | fibers need access to main-thread data, and it would be too expensive in | |
13366 | runtime (or development time) to robustly defend every such data item with | |
13367 | thread synchronization primitives. | |
13368 | </para> | |
13369 | <para> | |
13370 | You must ensure that the application’s main loop <emphasis>itself</emphasis> | |
13371 | doesn’t monopolize the processor: that the fibers it launches will get the | |
13372 | CPU cycles they need. | |
13373 | </para> | |
13374 | <para> | |
13375 | The solution is the same as for any fiber that might claim the CPU for an | |
13376 | extended time: introduce calls to <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link>. The | |
13377 | most straightforward approach is to call <code><phrase role="identifier">yield</phrase><phrase | |
13378 | role="special">()</phrase></code> on every iteration of your existing main | |
13379 | loop. In effect, this unifies the application’s main loop with <emphasis role="bold">Boost.Fiber</emphasis>’s | |
13380 | internal main loop. <code><phrase role="identifier">yield</phrase><phrase | |
13381 | role="special">()</phrase></code> allows the fiber manager to run any fibers | |
13382 | that have become ready since the previous iteration of the application’s main | |
13383 | loop. When these fibers have had a turn, control passes to the thread’s main | |
13384 | fiber, which returns from <code><phrase role="identifier">yield</phrase><phrase | |
13385 | role="special">()</phrase></code> and resumes the application’s main loop. | |
13386 | </para> | |
13387 | </section> | |
13388 | <section id="fiber.integration.embedded_main_loop"> | |
13389 | <title><anchor id="embedded_main_loop"/><link linkend="fiber.integration.embedded_main_loop">Embedded | |
13390 | Main Loop</link></title> | |
13391 | <para> | |
13392 | More challenging is when the application’s main loop is embedded in some other | |
13393 | library or framework. Such an application will typically, after performing | |
13394 | all necessary setup, pass control to some form of <code><phrase role="identifier">run</phrase><phrase | |
13395 | role="special">()</phrase></code> function from which control does not return | |
13396 | until application shutdown. | |
13397 | </para> | |
13398 | <para> | |
13399 | A <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink> | |
13400 | program might call <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/run.html"><code><phrase | |
13401 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13402 | role="identifier">run</phrase><phrase role="special">()</phrase></code></ulink> | |
13403 | in this way. | |
13404 | </para> | |
13405 | <para> | |
13406 | In general, the trick is to arrange to pass control to <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link> frequently. | |
13407 | You could use an <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/high_resolution_timer.html">Asio | |
13408 | timer</ulink> for that purpose. You could instantiate the timer, arranging | |
13409 | to call a handler function when the timer expires. The handler function could | |
13410 | call <code><phrase role="identifier">yield</phrase><phrase role="special">()</phrase></code>, | |
13411 | then reset the timer and arrange to wake up again on its next expiration. | |
13412 | </para> | |
13413 | <para> | |
13414 | Since, in this thought experiment, we always pass control to the fiber manager | |
13415 | via <code><phrase role="identifier">yield</phrase><phrase role="special">()</phrase></code>, | |
13416 | the calling fiber is never blocked. Therefore there is always at least one | |
13417 | ready fiber. Therefore the fiber manager never calls <link linkend="algorithm_suspend_until"><code>algorithm::suspend_until()</code></link>. | |
13418 | </para> | |
13419 | <para> | |
13420 | Using <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/post.html"><code><phrase | |
13421 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13422 | role="identifier">post</phrase><phrase role="special">()</phrase></code></ulink> | |
13423 | instead of setting a timer for some nonzero interval would be unfriendly | |
13424 | to other threads. When all I/O is pending and all fibers are blocked, the | |
13425 | io_service and the fiber manager would simply spin the CPU, passing control | |
13426 | back and forth to each other. Using a timer allows tuning the responsiveness | |
13427 | of this thread relative to others. | |
13428 | </para> | |
13429 | </section> | |
13430 | <section id="fiber.integration.deeper_dive_into___boost_asio__"> | |
13431 | <title><link linkend="fiber.integration.deeper_dive_into___boost_asio__">Deeper | |
13432 | Dive into <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink></link></title> | |
13433 | <para> | |
13434 | By now the alert reader is thinking: but surely, with Asio in particular, | |
13435 | we ought to be able to do much better than periodic polling pings! | |
13436 | </para> | |
13437 | <para> | |
13438 | This turns out to be surprisingly tricky. We present a possible approach | |
13439 | in <ulink url="../../examples/asio/round_robin.hpp"><code><phrase role="identifier">examples</phrase><phrase | |
13440 | role="special">/</phrase><phrase role="identifier">asio</phrase><phrase role="special">/</phrase><phrase | |
13441 | role="identifier">round_robin</phrase><phrase role="special">.</phrase><phrase | |
13442 | role="identifier">hpp</phrase></code></ulink>. | |
13443 | </para> | |
13444 | <para> | |
13445 | One consequence of using <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink> | |
13446 | is that you must always let Asio suspend the running thread. Since Asio is | |
13447 | aware of pending I/O requests, it can arrange to suspend the thread in such | |
13448 | a way that the OS will wake it on I/O completion. No one else has sufficient | |
13449 | knowledge. | |
13450 | </para> | |
13451 | <para> | |
13452 | So the fiber scheduler must depend on Asio for suspension and resumption. | |
13453 | It requires Asio handler calls to wake it. | |
13454 | </para> | |
13455 | <para> | |
13456 | One dismaying implication is that we cannot support multiple threads calling | |
13457 | <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/run.html"><code><phrase | |
13458 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13459 | role="identifier">run</phrase><phrase role="special">()</phrase></code></ulink> | |
13460 | on the same <code><phrase role="identifier">io_service</phrase></code> instance. | |
13461 | The reason is that Asio provides no way to constrain a particular handler | |
13462 | to be called only on a specified thread. A fiber scheduler instance is locked | |
13463 | to a particular thread: that instance cannot manage any other thread’s fibers. | |
13464 | Yet if we allow multiple threads to call <code><phrase role="identifier">io_service</phrase><phrase | |
13465 | role="special">::</phrase><phrase role="identifier">run</phrase><phrase role="special">()</phrase></code> | |
13466 | on the same <code><phrase role="identifier">io_service</phrase></code> instance, | |
13467 | a fiber scheduler which needs to sleep can have no guarantee that it will | |
13468 | reawaken in a timely manner. It can set an Asio timer, as described above | |
13469 | — but that timer’s handler may well execute on a different thread! | |
13470 | </para> | |
13471 | <para> | |
13472 | Another implication is that since an Asio-aware fiber scheduler (not to mention | |
13473 | <link linkend="callbacks_asio"><code><phrase role="identifier">boost</phrase><phrase | |
13474 | role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase | |
13475 | role="special">::</phrase><phrase role="identifier">asio</phrase><phrase | |
13476 | role="special">::</phrase><phrase role="identifier">yield</phrase></code></link>) | |
13477 | depends on handler calls from the <code><phrase role="identifier">io_service</phrase></code>, | |
13478 | it is the application’s responsibility to ensure that <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/stop.html"><code><phrase | |
13479 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13480 | role="identifier">stop</phrase><phrase role="special">()</phrase></code></ulink> | |
13481 | is not called until every fiber has terminated. | |
13482 | </para> | |
13483 | <para> | |
13484 | It is easier to reason about the behavior of the presented <code><phrase | |
13485 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13486 | role="identifier">round_robin</phrase></code> scheduler if we require that | |
13487 | after initial setup, the thread’s main fiber is the fiber that calls <code><phrase | |
13488 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13489 | role="identifier">run</phrase><phrase role="special">()</phrase></code>, | |
13490 | so let’s impose that requirement. | |
13491 | </para> | |
13492 | <para> | |
13493 | Naturally, the first thing we must do on each thread using a custom fiber | |
13494 | scheduler is call <link linkend="use_scheduling_algorithm"><code>use_scheduling_algorithm()</code></link>. However, | |
13495 | since <code><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13496 | role="identifier">round_robin</phrase></code> requires an <code><phrase role="identifier">io_service</phrase></code> | |
13497 | instance, we must first declare that. | |
13498 | </para> | |
13499 | <para> | |
13500 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">;</phrase> | |
13501 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">round_robin</phrase> <phrase role="special">>(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">);</phrase> | |
13502 | </programlisting> | |
13503 | </para> | |
13504 | <para> | |
13505 | <code><phrase role="identifier">use_scheduling_algorithm</phrase><phrase | |
13506 | role="special">()</phrase></code> instantiates <code><phrase role="identifier">asio</phrase><phrase | |
13507 | role="special">::</phrase><phrase role="identifier">round_robin</phrase></code>, | |
13508 | which naturally calls its constructor: | |
13509 | </para> | |
13510 | <para> | |
13511 | <programlisting><phrase role="identifier">round_robin</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase> <phrase role="special">&</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
13512 | <phrase role="identifier">io_svc_</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">),</phrase> | |
13513 | <phrase role="identifier">suspend_timer_</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc_</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13514 | <phrase role="comment">// We use add_service() very deliberately. This will throw</phrase> | |
13515 | <phrase role="comment">// service_already_exists if you pass the same io_service instance to</phrase> | |
13516 | <phrase role="comment">// more than one round_robin instance.</phrase> | |
13517 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">add_service</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc_</phrase><phrase role="special">,</phrase> <phrase role="keyword">new</phrase> <phrase role="identifier">service</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc_</phrase><phrase role="special">));</phrase> | |
13518 | <phrase role="special">}</phrase> | |
13519 | </programlisting> | |
13520 | </para> | |
13521 | <para> | |
13522 | <code><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13523 | role="identifier">round_robin</phrase></code> binds the passed <code><phrase | |
13524 | role="identifier">io_service</phrase></code> reference and initializes a | |
13525 | <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/steady_timer.html"><code><phrase | |
13526 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
13527 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13528 | role="identifier">steady_timer</phrase></code></ulink>: | |
13529 | </para> | |
13530 | <para> | |
13531 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase> <phrase role="special">&</phrase> <phrase role="identifier">io_svc_</phrase><phrase role="special">;</phrase> | |
13532 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_timer</phrase> <phrase role="identifier">suspend_timer_</phrase><phrase role="special">;</phrase> | |
13533 | </programlisting> | |
13534 | </para> | |
13535 | <para> | |
13536 | Then it calls <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/add_service.html"><code><phrase | |
13537 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
13538 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13539 | role="identifier">add_service</phrase><phrase role="special">()</phrase></code></ulink> | |
13540 | with a nested <code><phrase role="identifier">service</phrase></code> struct: | |
13541 | </para> | |
13542 | <para> | |
13543 | <programlisting><phrase role="keyword">struct</phrase> <phrase role="identifier">service</phrase> <phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase role="identifier">service</phrase> <phrase role="special">{</phrase> | |
13544 | <phrase role="keyword">static</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase role="identifier">id</phrase> <phrase role="identifier">id</phrase><phrase role="special">;</phrase> | |
13545 | ||
13546 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_ptr</phrase><phrase role="special"><</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase role="identifier">work</phrase> <phrase role="special">></phrase> <phrase role="identifier">work_</phrase><phrase role="special">;</phrase> | |
13547 | ||
13548 | <phrase role="identifier">service</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase> <phrase role="special">&</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">)</phrase> <phrase role="special">:</phrase> | |
13549 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase role="identifier">service</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">),</phrase> | |
13550 | <phrase role="identifier">work_</phrase><phrase role="special">{</phrase> <phrase role="keyword">new</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase role="identifier">work</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">)</phrase> <phrase role="special">}</phrase> <phrase role="special">{</phrase> | |
13551 | <phrase role="identifier">io_svc</phrase><phrase role="special">.</phrase><phrase role="identifier">post</phrase><phrase role="special">([&</phrase><phrase role="identifier">io_svc</phrase><phrase role="special">](){</phrase> | |
13552 | </programlisting> | |
13553 | </para> | |
13554 | <para> | |
13555 | ... | |
13556 | </para> | |
13557 | <para> | |
13558 | <programlisting> <phrase role="special">});</phrase> | |
13559 | <phrase role="special">}</phrase> | |
13560 | ||
13561 | <phrase role="keyword">virtual</phrase> <phrase role="special">~</phrase><phrase role="identifier">service</phrase><phrase role="special">()</phrase> <phrase role="special">{}</phrase> | |
13562 | ||
13563 | <phrase role="identifier">service</phrase><phrase role="special">(</phrase> <phrase role="identifier">service</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
13564 | <phrase role="identifier">service</phrase> <phrase role="special">&</phrase> <phrase role="keyword">operator</phrase><phrase role="special">=(</phrase> <phrase role="identifier">service</phrase> <phrase role="keyword">const</phrase><phrase role="special">&)</phrase> <phrase role="special">=</phrase> <phrase role="keyword">delete</phrase><phrase role="special">;</phrase> | |
13565 | ||
13566 | <phrase role="keyword">void</phrase> <phrase role="identifier">shutdown_service</phrase><phrase role="special">()</phrase> <phrase role="identifier">override</phrase> <phrase role="identifier">final</phrase> <phrase role="special">{</phrase> | |
13567 | <phrase role="identifier">work_</phrase><phrase role="special">.</phrase><phrase role="identifier">reset</phrase><phrase role="special">();</phrase> | |
13568 | <phrase role="special">}</phrase> | |
13569 | <phrase role="special">};</phrase> | |
13570 | </programlisting> | |
13571 | </para> | |
13572 | <para> | |
13573 | The <code><phrase role="identifier">service</phrase></code> struct has a | |
13574 | couple of roles. | |
13575 | </para> | |
13576 | <para> | |
13577 | Its foremost role is to manage a <literal>std::unique_ptr<<ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service__work.html"><code><phrase | |
13578 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
13579 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13580 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13581 | role="identifier">work</phrase></code></ulink>></literal>. We want the | |
13582 | <code><phrase role="identifier">io_service</phrase></code> instance to continue | |
13583 | its main loop even when there is no pending Asio I/O. | |
13584 | </para> | |
13585 | <para> | |
13586 | But when <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service__service/shutdown_service.html"><code><phrase | |
13587 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
13588 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13589 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13590 | role="identifier">service</phrase><phrase role="special">::</phrase><phrase | |
13591 | role="identifier">shutdown_service</phrase><phrase role="special">()</phrase></code></ulink> | |
13592 | is called, we discard the <code><phrase role="identifier">io_service</phrase><phrase | |
13593 | role="special">::</phrase><phrase role="identifier">work</phrase></code> | |
13594 | instance so the <code><phrase role="identifier">io_service</phrase></code> | |
13595 | can shut down properly. | |
13596 | </para> | |
13597 | <para> | |
13598 | Its other purpose is to <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/post.html"><code><phrase | |
13599 | role="identifier">post</phrase><phrase role="special">()</phrase></code></ulink> | |
13600 | a lambda (not yet shown). Let’s walk further through the example program before | |
13601 | coming back to explain that lambda. | |
13602 | </para> | |
13603 | <para> | |
13604 | The <code><phrase role="identifier">service</phrase></code> constructor returns | |
13605 | to <code><phrase role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13606 | role="identifier">round_robin</phrase></code>’s constructor, which returns | |
13607 | to <code><phrase role="identifier">use_scheduling_algorithm</phrase><phrase | |
13608 | role="special">()</phrase></code>, which returns to the application code. | |
13609 | </para> | |
13610 | <para> | |
13611 | Once it has called <code><phrase role="identifier">use_scheduling_algorithm</phrase><phrase | |
13612 | role="special">()</phrase></code>, the application may now launch some number | |
13613 | of fibers: | |
13614 | </para> | |
13615 | <para> | |
13616 | <programlisting><phrase role="comment">// server</phrase> | |
13617 | <phrase role="identifier">tcp</phrase><phrase role="special">::</phrase><phrase role="identifier">acceptor</phrase> <phrase role="identifier">a</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">,</phrase> <phrase role="identifier">tcp</phrase><phrase role="special">::</phrase><phrase role="identifier">endpoint</phrase><phrase role="special">(</phrase> <phrase role="identifier">tcp</phrase><phrase role="special">::</phrase><phrase role="identifier">v4</phrase><phrase role="special">(),</phrase> <phrase role="number">9999</phrase><phrase role="special">)</phrase> <phrase role="special">);</phrase> | |
13618 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">server</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">),</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">a</phrase><phrase role="special">)</phrase> <phrase role="special">).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
13619 | <phrase role="comment">// client</phrase> | |
13620 | <phrase role="keyword">const</phrase> <phrase role="keyword">unsigned</phrase> <phrase role="identifier">iterations</phrase> <phrase role="special">=</phrase> <phrase role="number">2</phrase><phrase role="special">;</phrase> | |
13621 | <phrase role="keyword">const</phrase> <phrase role="keyword">unsigned</phrase> <phrase role="identifier">clients</phrase> <phrase role="special">=</phrase> <phrase role="number">3</phrase><phrase role="special">;</phrase> | |
13622 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">barrier</phrase> <phrase role="identifier">b</phrase><phrase role="special">(</phrase> <phrase role="identifier">clients</phrase><phrase role="special">);</phrase> | |
13623 | <phrase role="keyword">for</phrase> <phrase role="special">(</phrase> <phrase role="keyword">unsigned</phrase> <phrase role="identifier">i</phrase> <phrase role="special">=</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase> <phrase role="identifier">i</phrase> <phrase role="special"><</phrase> <phrase role="identifier">clients</phrase><phrase role="special">;</phrase> <phrase role="special">++</phrase><phrase role="identifier">i</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13624 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> | |
13625 | <phrase role="identifier">client</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">),</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">a</phrase><phrase role="special">),</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">ref</phrase><phrase role="special">(</phrase> <phrase role="identifier">b</phrase><phrase role="special">),</phrase> <phrase role="identifier">iterations</phrase><phrase role="special">).</phrase><phrase role="identifier">detach</phrase><phrase role="special">();</phrase> | |
13626 | <phrase role="special">}</phrase> | |
13627 | </programlisting> | |
13628 | </para> | |
13629 | <para> | |
13630 | Since we don’t specify a <link linkend="class_launch"><code>launch</code></link>, these fibers are ready to run, | |
13631 | but have not yet been entered. | |
13632 | </para> | |
13633 | <para> | |
13634 | Having set everything up, the application calls <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/run.html"><code><phrase | |
13635 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13636 | role="identifier">run</phrase><phrase role="special">()</phrase></code></ulink>: | |
13637 | </para> | |
13638 | <para> | |
13639 | <programlisting><phrase role="identifier">io_svc</phrase><phrase role="special">.</phrase><phrase role="identifier">run</phrase><phrase role="special">();</phrase> | |
13640 | </programlisting> | |
13641 | </para> | |
13642 | <para> | |
13643 | Now what? | |
13644 | </para> | |
13645 | <para> | |
13646 | Because this <code><phrase role="identifier">io_service</phrase></code> instance | |
13647 | owns an <code><phrase role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13648 | role="identifier">work</phrase></code> instance, <code><phrase role="identifier">run</phrase><phrase | |
13649 | role="special">()</phrase></code> does not immediately return. But — none of | |
13650 | the fibers that will perform actual work has even been entered yet! | |
13651 | </para> | |
13652 | <para> | |
13653 | Without that initial <code><phrase role="identifier">post</phrase><phrase | |
13654 | role="special">()</phrase></code> call in <code><phrase role="identifier">service</phrase></code>’s | |
13655 | constructor, <emphasis>nothing</emphasis> would happen. The application would | |
13656 | hang right here. | |
13657 | </para> | |
13658 | <para> | |
13659 | So, what should the <code><phrase role="identifier">post</phrase><phrase | |
13660 | role="special">()</phrase></code> handler execute? Simply <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link>? | |
13661 | </para> | |
13662 | <para> | |
13663 | That would be a promising start. But we have no guarantee that any of the | |
13664 | other fibers will initiate any Asio operations to keep the ball rolling. | |
13665 | For all we know, every other fiber could reach a similar <code><phrase role="identifier">this_fiber</phrase><phrase | |
13666 | role="special">::</phrase><phrase role="identifier">yield</phrase><phrase | |
13667 | role="special">()</phrase></code> call first. Control would return to the | |
13668 | <code><phrase role="identifier">post</phrase><phrase role="special">()</phrase></code> | |
13669 | handler, which would return to Asio, and... the application would hang. | |
13670 | </para> | |
13671 | <para> | |
13672 | The <code><phrase role="identifier">post</phrase><phrase role="special">()</phrase></code> | |
13673 | handler could <code><phrase role="identifier">post</phrase><phrase role="special">()</phrase></code> | |
13674 | itself again. But as discussed in <link linkend="embedded_main_loop">the | |
13675 | previous section</link>, once there are actual I/O operations in flight — once | |
13676 | we reach a state in which no fiber is ready — | |
13677 | that would cause the thread to | |
13678 | spin. | |
13679 | </para> | |
13680 | <para> | |
13681 | We could, of course, set an Asio timer — again as <link linkend="embedded_main_loop">previously | |
13682 | discussed</link>. But in this <quote>deeper dive,</quote> we’re trying to | |
13683 | do a little better. | |
13684 | </para> | |
13685 | <para> | |
13686 | The key to doing better is that since we’re in a fiber, we can run an actual | |
13687 | loop — not just a chain of callbacks. We can wait for <quote>something to happen</quote> | |
13688 | by calling <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/run_one.html"><code><phrase | |
13689 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13690 | role="identifier">run_one</phrase><phrase role="special">()</phrase></code></ulink> | |
13691 | — or we can execute already-queued Asio handlers by calling <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/poll.html"><code><phrase | |
13692 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13693 | role="identifier">poll</phrase><phrase role="special">()</phrase></code></ulink>. | |
13694 | </para> | |
13695 | <para> | |
13696 | Here’s the body of the lambda passed to the <code><phrase role="identifier">post</phrase><phrase | |
13697 | role="special">()</phrase></code> call. | |
13698 | </para> | |
13699 | <para> | |
13700 | <programlisting><phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">.</phrase><phrase role="identifier">stopped</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13701 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13702 | <phrase role="comment">// run all pending handlers in round_robin</phrase> | |
13703 | <phrase role="keyword">while</phrase> <phrase role="special">(</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">.</phrase><phrase role="identifier">poll</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
13704 | <phrase role="comment">// run pending (ready) fibers</phrase> | |
13705 | <phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">yield</phrase><phrase role="special">();</phrase> | |
13706 | <phrase role="special">}</phrase> <phrase role="keyword">else</phrase> <phrase role="special">{</phrase> | |
13707 | <phrase role="comment">// run one handler inside io_service</phrase> | |
13708 | <phrase role="comment">// if no handler available, block this thread</phrase> | |
13709 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">io_svc</phrase><phrase role="special">.</phrase><phrase role="identifier">run_one</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13710 | <phrase role="keyword">break</phrase><phrase role="special">;</phrase> | |
13711 | <phrase role="special">}</phrase> | |
13712 | <phrase role="special">}</phrase> | |
13713 | <phrase role="special">}</phrase> | |
13714 | </programlisting> | |
13715 | </para> | |
13716 | <para> | |
13717 | We want this loop to exit once the <code><phrase role="identifier">io_service</phrase></code> | |
13718 | instance has been <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service/stopped.html"><code><phrase | |
13719 | role="identifier">stopped</phrase><phrase role="special">()</phrase></code></ulink>. | |
13720 | </para> | |
13721 | <para> | |
13722 | As long as there are ready fibers, we interleave running ready Asio handlers | |
13723 | with running ready fibers. | |
13724 | </para> | |
13725 | <para> | |
13726 | If there are no ready fibers, we wait by calling <code><phrase role="identifier">run_one</phrase><phrase | |
13727 | role="special">()</phrase></code>. Once any Asio handler has been called | |
13728 | — no matter which — <code><phrase role="identifier">run_one</phrase><phrase role="special">()</phrase></code> | |
13729 | returns. That handler may have transitioned some fiber to ready state, so | |
13730 | we loop back to check again. | |
13731 | </para> | |
13732 | <para> | |
13733 | (We won’t describe <code><phrase role="identifier">awakened</phrase><phrase | |
13734 | role="special">()</phrase></code>, <code><phrase role="identifier">pick_next</phrase><phrase | |
13735 | role="special">()</phrase></code> or <code><phrase role="identifier">has_ready_fibers</phrase><phrase | |
13736 | role="special">()</phrase></code>, as these are just like <link linkend="round_robin_awakened"><code>round_robin::awakened()</code></link>, | |
13737 | <link linkend="round_robin_pick_next"><code>round_robin::pick_next()</code></link> and <link linkend="round_robin_has_ready_fibers"><code>round_robin::has_ready_fibers()</code></link>.) | |
13738 | </para> | |
13739 | <para> | |
13740 | That leaves <code><phrase role="identifier">suspend_until</phrase><phrase | |
13741 | role="special">()</phrase></code> and <code><phrase role="identifier">notify</phrase><phrase | |
13742 | role="special">()</phrase></code>. | |
13743 | </para> | |
13744 | <para> | |
13745 | Doubtless you have been asking yourself: why are we calling <code><phrase | |
13746 | role="identifier">io_service</phrase><phrase role="special">::</phrase><phrase | |
13747 | role="identifier">run_one</phrase><phrase role="special">()</phrase></code> | |
13748 | in the lambda loop? Why not call it in <code><phrase role="identifier">suspend_until</phrase><phrase | |
13749 | role="special">()</phrase></code>, whose very API was designed for just such | |
13750 | a purpose? | |
13751 | </para> | |
13752 | <para> | |
13753 | Under normal circumstances, when the fiber manager finds no ready fibers, | |
13754 | it calls <link linkend="algorithm_suspend_until"><code>algorithm::suspend_until()</code></link>. Why test <code><phrase | |
13755 | role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase></code> | |
13756 | in the lambda loop? Why not leverage the normal mechanism? | |
13757 | </para> | |
13758 | <para> | |
13759 | The answer is: it matters who’s asking. | |
13760 | </para> | |
13761 | <para> | |
13762 | Consider the lambda loop shown above. The only <emphasis role="bold">Boost.Fiber</emphasis> | |
13763 | APIs it engages are <code><phrase role="identifier">has_ready_fibers</phrase><phrase | |
13764 | role="special">()</phrase></code> and <link linkend="this_fiber_yield"><code>this_fiber::yield()</code></link>. | |
13765 | <code><phrase role="identifier">yield</phrase><phrase role="special">()</phrase></code> | |
13766 | does not <emphasis>block</emphasis> the calling fiber: the calling fiber | |
13767 | does not become unready. It is immediately passed back to <link linkend="algorithm_awakened"><code>algorithm::awakened()</code></link>, | |
13768 | to be resumed in its turn when all other ready fibers have had a chance to | |
13769 | run. In other words: during a <code><phrase role="identifier">yield</phrase><phrase | |
13770 | role="special">()</phrase></code> call, <emphasis>there is always at least | |
13771 | one ready fiber.</emphasis> | |
13772 | </para> | |
13773 | <para> | |
13774 | As long as this lambda loop is still running, the fiber manager does not | |
13775 | call <code><phrase role="identifier">suspend_until</phrase><phrase role="special">()</phrase></code> | |
13776 | because it always has a fiber ready to run. | |
13777 | </para> | |
13778 | <para> | |
13779 | However, the lambda loop <emphasis>itself</emphasis> can detect the case | |
13780 | when no <emphasis>other</emphasis> fibers are ready to run: the running fiber | |
13781 | is not <emphasis>ready</emphasis> but <emphasis>running.</emphasis> | |
13782 | </para> | |
13783 | <para> | |
13784 | That said, <code><phrase role="identifier">suspend_until</phrase><phrase | |
13785 | role="special">()</phrase></code> and <code><phrase role="identifier">notify</phrase><phrase | |
13786 | role="special">()</phrase></code> are in fact called during orderly shutdown | |
13787 | processing, so let’s try a plausible implementation. | |
13788 | </para> | |
13789 | <para> | |
13790 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
13791 | <phrase role="comment">// Set a timer so at least one handler will eventually fire, causing</phrase> | |
13792 | <phrase role="comment">// run_one() to eventually return. Set a timer even if abs_time ==</phrase> | |
13793 | <phrase role="comment">// time_point::max() so the timer can be canceled by our notify()</phrase> | |
13794 | <phrase role="comment">// method -- which calls the handler.</phrase> | |
13795 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">suspend_timer_</phrase><phrase role="special">.</phrase><phrase role="identifier">expires_at</phrase><phrase role="special">()</phrase> <phrase role="special">!=</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
13796 | <phrase role="comment">// Each expires_at(time_point) call cancels any previous pending</phrase> | |
13797 | <phrase role="comment">// call. We could inadvertently spin like this:</phrase> | |
13798 | <phrase role="comment">// dispatcher calls suspend_until() with earliest wake time</phrase> | |
13799 | <phrase role="comment">// suspend_until() sets suspend_timer_</phrase> | |
13800 | <phrase role="comment">// lambda loop calls run_one()</phrase> | |
13801 | <phrase role="comment">// some other asio handler runs before timer expires</phrase> | |
13802 | <phrase role="comment">// run_one() returns to lambda loop</phrase> | |
13803 | <phrase role="comment">// lambda loop yields to dispatcher</phrase> | |
13804 | <phrase role="comment">// dispatcher finds no ready fibers</phrase> | |
13805 | <phrase role="comment">// dispatcher calls suspend_until() with SAME wake time</phrase> | |
13806 | <phrase role="comment">// suspend_until() sets suspend_timer_ to same time, canceling</phrase> | |
13807 | <phrase role="comment">// previous async_wait()</phrase> | |
13808 | <phrase role="comment">// lambda loop calls run_one()</phrase> | |
13809 | <phrase role="comment">// asio calls suspend_timer_ handler with operation_aborted</phrase> | |
13810 | <phrase role="comment">// run_one() returns to lambda loop... etc. etc.</phrase> | |
13811 | <phrase role="comment">// So only actually set the timer when we're passed a DIFFERENT</phrase> | |
13812 | <phrase role="comment">// abs_time value.</phrase> | |
13813 | <phrase role="identifier">suspend_timer_</phrase><phrase role="special">.</phrase><phrase role="identifier">expires_at</phrase><phrase role="special">(</phrase> <phrase role="identifier">abs_time</phrase><phrase role="special">);</phrase> | |
13814 | <phrase role="comment">// It really doesn't matter what the suspend_timer_ handler does,</phrase> | |
13815 | <phrase role="comment">// or even whether it's called because the timer ran out or was</phrase> | |
13816 | <phrase role="comment">// canceled. The whole point is to cause the run_one() call to</phrase> | |
13817 | <phrase role="comment">// return. So just pass a no-op lambda with proper signature.</phrase> | |
13818 | <phrase role="identifier">suspend_timer_</phrase><phrase role="special">.</phrase><phrase role="identifier">async_wait</phrase><phrase role="special">([](</phrase><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">system</phrase><phrase role="special">::</phrase><phrase role="identifier">error_code</phrase> <phrase role="keyword">const</phrase><phrase role="special">&){});</phrase> | |
13819 | <phrase role="special">}</phrase> | |
13820 | <phrase role="special">}</phrase> | |
13821 | </programlisting> | |
13822 | </para> | |
13823 | <para> | |
13824 | As you might expect, <code><phrase role="identifier">suspend_until</phrase><phrase | |
13825 | role="special">()</phrase></code> sets an <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/steady_timer.html"><code><phrase | |
13826 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13827 | role="identifier">steady_timer</phrase></code></ulink> to <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/basic_waitable_timer/expires_at.html"><code><phrase | |
13828 | role="identifier">expires_at</phrase><phrase role="special">()</phrase></code></ulink> | |
13829 | the passed <ulink url="http://en.cppreference.com/w/cpp/chrono/steady_clock"><code><phrase | |
13830 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase | |
13831 | role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase | |
13832 | role="special">::</phrase><phrase role="identifier">time_point</phrase></code></ulink>. | |
13833 | Usually. | |
13834 | </para> | |
13835 | <para> | |
13836 | As indicated in comments, we avoid setting <code><phrase role="identifier">suspend_timer_</phrase></code> | |
13837 | multiple times to the <emphasis>same</emphasis> <code><phrase role="identifier">time_point</phrase></code> | |
13838 | value since every <code><phrase role="identifier">expires_at</phrase><phrase | |
13839 | role="special">()</phrase></code> call cancels any previous <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/basic_waitable_timer/async_wait.html"><code><phrase | |
13840 | role="identifier">async_wait</phrase><phrase role="special">()</phrase></code></ulink> | |
13841 | call. There is a chance that we could spin. Reaching <code><phrase role="identifier">suspend_until</phrase><phrase | |
13842 | role="special">()</phrase></code> means the fiber manager intends to yield | |
13843 | the processor to Asio. Cancelling the previous <code><phrase role="identifier">async_wait</phrase><phrase | |
13844 | role="special">()</phrase></code> call would fire its handler, causing <code><phrase | |
13845 | role="identifier">run_one</phrase><phrase role="special">()</phrase></code> | |
13846 | to return, potentially causing the fiber manager to call <code><phrase role="identifier">suspend_until</phrase><phrase | |
13847 | role="special">()</phrase></code> again with the same <code><phrase role="identifier">time_point</phrase></code> | |
13848 | value... | |
13849 | </para> | |
13850 | <para> | |
13851 | Given that we suspend the thread by calling <code><phrase role="identifier">io_service</phrase><phrase | |
13852 | role="special">::</phrase><phrase role="identifier">run_one</phrase><phrase | |
13853 | role="special">()</phrase></code>, what’s important is that our <code><phrase | |
13854 | role="identifier">async_wait</phrase><phrase role="special">()</phrase></code> | |
13855 | call will cause a handler to run, which will cause <code><phrase role="identifier">run_one</phrase><phrase | |
13856 | role="special">()</phrase></code> to return. It’s not so important specifically | |
13857 | what that handler does. | |
13858 | </para> | |
13859 | <para> | |
13860 | <programlisting><phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
13861 | <phrase role="comment">// Something has happened that should wake one or more fibers BEFORE</phrase> | |
13862 | <phrase role="comment">// suspend_timer_ expires. Reset the timer to cause it to fire</phrase> | |
13863 | <phrase role="comment">// immediately, causing the run_one() call to return. In theory we</phrase> | |
13864 | <phrase role="comment">// could use cancel() because we don't care whether suspend_timer_'s</phrase> | |
13865 | <phrase role="comment">// handler is called with operation_aborted or success. However --</phrase> | |
13866 | <phrase role="comment">// cancel() doesn't change the expiration time, and we use</phrase> | |
13867 | <phrase role="comment">// suspend_timer_'s expiration time to decide whether it's already</phrase> | |
13868 | <phrase role="comment">// set. If suspend_until() set some specific wake time, then notify()</phrase> | |
13869 | <phrase role="comment">// canceled it, then suspend_until() was called again with the same</phrase> | |
13870 | <phrase role="comment">// wake time, it would match suspend_timer_'s expiration time and we'd</phrase> | |
13871 | <phrase role="comment">// refrain from setting the timer. So instead of simply calling</phrase> | |
13872 | <phrase role="comment">// cancel(), reset the timer, which cancels the pending sleep AND sets</phrase> | |
13873 | <phrase role="comment">// a new expiration time. This will cause us to spin the loop twice --</phrase> | |
13874 | <phrase role="comment">// once for the operation_aborted handler, once for timer expiration</phrase> | |
13875 | <phrase role="comment">// -- but that shouldn't be a big problem.</phrase> | |
13876 | <phrase role="identifier">suspend_timer_</phrase><phrase role="special">.</phrase><phrase role="identifier">expires_at</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">now</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
13877 | <phrase role="special">}</phrase> | |
13878 | </programlisting> | |
13879 | </para> | |
13880 | <para> | |
13881 | Since an <code><phrase role="identifier">expires_at</phrase><phrase role="special">()</phrase></code> | |
13882 | call cancels any previous <code><phrase role="identifier">async_wait</phrase><phrase | |
13883 | role="special">()</phrase></code> call, we can make <code><phrase role="identifier">notify</phrase><phrase | |
13884 | role="special">()</phrase></code> simply call <code><phrase role="identifier">steady_timer</phrase><phrase | |
13885 | role="special">::</phrase><phrase role="identifier">expires_at</phrase><phrase | |
13886 | role="special">()</phrase></code>. That should cause the <code><phrase role="identifier">io_service</phrase></code> | |
13887 | to call the <code><phrase role="identifier">async_wait</phrase><phrase role="special">()</phrase></code> | |
13888 | handler with <code><phrase role="identifier">operation_aborted</phrase></code>. | |
13889 | </para> | |
13890 | <para> | |
13891 | The comments in <code><phrase role="identifier">notify</phrase><phrase role="special">()</phrase></code> | |
13892 | explain why we call <code><phrase role="identifier">expires_at</phrase><phrase | |
13893 | role="special">()</phrase></code> rather than <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/basic_waitable_timer/cancel.html"><code><phrase | |
13894 | role="identifier">cancel</phrase><phrase role="special">()</phrase></code></ulink>. | |
13895 | </para> | |
13896 | <para> | |
13897 | This <code><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase | |
13898 | role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase | |
13899 | role="identifier">asio</phrase><phrase role="special">::</phrase><phrase | |
13900 | role="identifier">round_robin</phrase></code> implementation is used in | |
13901 | <ulink url="../../examples/asio/autoecho.cpp"><code><phrase role="identifier">examples</phrase><phrase | |
13902 | role="special">/</phrase><phrase role="identifier">asio</phrase><phrase role="special">/</phrase><phrase | |
13903 | role="identifier">autoecho</phrase><phrase role="special">.</phrase><phrase | |
13904 | role="identifier">cpp</phrase></code></ulink>. | |
13905 | </para> | |
13906 | <para> | |
13907 | It seems possible that you could put together a more elegant Fiber / Asio | |
13908 | integration. But as noted at the outset: it’s tricky. | |
13909 | </para> | |
13910 | </section> | |
13911 | </section> | |
13912 | <section id="fiber.performance"> | |
13913 | <title><link linkend="fiber.performance">Performance</link></title> | |
13914 | <para> | |
13915 | Performance measurements were taken using <code><phrase role="identifier">std</phrase><phrase | |
13916 | role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase | |
13917 | role="special">::</phrase><phrase role="identifier">highresolution_clock</phrase></code>, | |
13918 | with overhead corrections. The code was compiled using the build options: variant | |
13919 | = release, optimization = speed <footnote id="fiber.performance.f0"> | |
13920 | <para> | |
13921 | Intel Core2 Q6700, x86_64, 3GHz | |
13922 | </para> | |
13923 | </footnote>. | |
13924 | </para> | |
13925 | <para> | |
13926 | The columns labeled <emphasis role="bold">fiber (atomics)</emphasis> were compiled | |
13927 | with default fiber synchronization, capable of synchronizing fibers running | |
13928 | on different threads. The columns labeled <emphasis role="bold">fiber (raw)</emphasis> | |
13929 | were compiled with <link linkend="cross_thread_sync"><code><phrase role="identifier">BOOST_FIBERS_NO_ATOMICS</phrase></code></link>. | |
13930 | </para> | |
13931 | <table frame="all" id="fiber.performance.overhead_of_join__contains_fiber_context_destruction__fiber_stack_deallocation_"> | |
13932 | <title>Overhead of join (contains fiber-context destruction, fiber-stack deallocation)</title> | |
13933 | <tgroup cols="5"> | |
13934 | <thead> | |
13935 | <row> | |
13936 | <entry> | |
13937 | <para> | |
13938 | thread | |
13939 | </para> | |
13940 | </entry> | |
13941 | <entry> | |
13942 | <para> | |
13943 | fiber (atomics) | |
13944 | </para> | |
13945 | </entry> | |
13946 | <entry> | |
13947 | <para> | |
13948 | fiber (raw) | |
13949 | </para> | |
13950 | </entry> | |
13951 | <entry> | |
13952 | <para> | |
13953 | tbb | |
13954 | </para> | |
13955 | </entry> | |
13956 | <entry> | |
13957 | <para> | |
13958 | qthread | |
13959 | </para> | |
13960 | </entry> | |
13961 | </row> | |
13962 | </thead> | |
13963 | <tbody> | |
13964 | <row> | |
13965 | <entry> | |
13966 | <para> | |
13967 | 18 µs | |
13968 | </para> | |
13969 | </entry> | |
13970 | <entry> | |
13971 | <para> | |
13972 | 950 ns | |
13973 | </para> | |
13974 | </entry> | |
13975 | <entry> | |
13976 | <para> | |
13977 | 900 ns | |
13978 | </para> | |
13979 | </entry> | |
13980 | <entry> | |
13981 | <para> | |
13982 | 570 ns | |
13983 | </para> | |
13984 | </entry> | |
13985 | <entry> | |
13986 | <para> | |
13987 | 620 ns | |
13988 | </para> | |
13989 | </entry> | |
13990 | </row> | |
13991 | </tbody> | |
13992 | </tgroup> | |
13993 | </table> | |
13994 | <para> | |
13995 | (from <ulink url="../../performance/fiber/overhead_join.cpp">overhead_join.cpp</ulink>) | |
13996 | </para> | |
13997 | <table frame="all" id="fiber.performance.overhead_of_detach"> | |
13998 | <title>Overhead of detach</title> | |
13999 | <tgroup cols="3"> | |
14000 | <thead> | |
14001 | <row> | |
14002 | <entry> | |
14003 | <para> | |
14004 | thread | |
14005 | </para> | |
14006 | </entry> | |
14007 | <entry> | |
14008 | <para> | |
14009 | fiber (atomics) | |
14010 | </para> | |
14011 | </entry> | |
14012 | <entry> | |
14013 | <para> | |
14014 | fiber (raw) | |
14015 | </para> | |
14016 | </entry> | |
14017 | </row> | |
14018 | </thead> | |
14019 | <tbody> | |
14020 | <row> | |
14021 | <entry> | |
14022 | <para> | |
14023 | 126 ns | |
14024 | </para> | |
14025 | </entry> | |
14026 | <entry> | |
14027 | <para> | |
14028 | 21 ns | |
14029 | </para> | |
14030 | </entry> | |
14031 | <entry> | |
14032 | <para> | |
14033 | 20 ns | |
14034 | </para> | |
14035 | </entry> | |
14036 | </row> | |
14037 | </tbody> | |
14038 | </tgroup> | |
14039 | </table> | |
14040 | <para> | |
14041 | (from <ulink url="../../performance/fiber/overhead_detach.cpp">overhead_detach.cpp</ulink>) | |
14042 | </para> | |
14043 | <table frame="all" id="fiber.performance.overhead_of_yield"> | |
14044 | <title>Overhead of yield</title> | |
14045 | <tgroup cols="3"> | |
14046 | <thead> | |
14047 | <row> | |
14048 | <entry> | |
14049 | <para> | |
14050 | thread | |
14051 | </para> | |
14052 | </entry> | |
14053 | <entry> | |
14054 | <para> | |
14055 | fiber (atomics) | |
14056 | </para> | |
14057 | </entry> | |
14058 | <entry> | |
14059 | <para> | |
14060 | fiber (raw) | |
14061 | </para> | |
14062 | </entry> | |
14063 | </row> | |
14064 | </thead> | |
14065 | <tbody> | |
14066 | <row> | |
14067 | <entry> | |
14068 | <para> | |
14069 | 1.5 µs | |
14070 | </para> | |
14071 | </entry> | |
14072 | <entry> | |
14073 | <para> | |
14074 | 310 ns | |
14075 | </para> | |
14076 | </entry> | |
14077 | <entry> | |
14078 | <para> | |
14079 | 330 ns | |
14080 | </para> | |
14081 | </entry> | |
14082 | </row> | |
14083 | </tbody> | |
14084 | </tgroup> | |
14085 | </table> | |
14086 | <para> | |
14087 | (from <ulink url="../../performance/fiber/overhead_yield.cpp">overhead_yield.cpp</ulink>) | |
14088 | </para> | |
14089 | <table frame="all" id="fiber.performance.overhead_of_waiting_on_a_future"> | |
14090 | <title>Overhead of waiting on a future</title> | |
14091 | <tgroup cols="3"> | |
14092 | <thead> | |
14093 | <row> | |
14094 | <entry> | |
14095 | <para> | |
14096 | thread | |
14097 | </para> | |
14098 | </entry> | |
14099 | <entry> | |
14100 | <para> | |
14101 | fiber (atomics) | |
14102 | </para> | |
14103 | </entry> | |
14104 | <entry> | |
14105 | <para> | |
14106 | fiber (raw) | |
14107 | </para> | |
14108 | </entry> | |
14109 | </row> | |
14110 | </thead> | |
14111 | <tbody> | |
14112 | <row> | |
14113 | <entry> | |
14114 | <para> | |
14115 | 16 µs | |
14116 | </para> | |
14117 | </entry> | |
14118 | <entry> | |
14119 | <para> | |
14120 | 1.40 µs | |
14121 | </para> | |
14122 | </entry> | |
14123 | <entry> | |
14124 | <para> | |
14125 | 1.38 µs | |
14126 | </para> | |
14127 | </entry> | |
14128 | </row> | |
14129 | </tbody> | |
14130 | </tgroup> | |
14131 | </table> | |
14132 | <para> | |
14133 | (from <ulink url="../../performance/fiber/overhead_future.cpp">overhead_future.cpp</ulink>) | |
14134 | </para> | |
14135 | <table frame="all" id="fiber.performance.overhead_of_fiber_creation__contains_fiber_stack_allocation_and_preparation__fiber_context_construction__scheduler_handling_"> | |
14136 | <title>Overhead of fiber creation (contains fiber-stack allocation and preparation, | |
14137 | fiber-context construction, scheduler handling)</title> | |
14138 | <tgroup cols="3"> | |
14139 | <thead> | |
14140 | <row> | |
14141 | <entry> | |
14142 | <para> | |
14143 | thread | |
14144 | </para> | |
14145 | </entry> | |
14146 | <entry> | |
14147 | <para> | |
14148 | fiber (atomics) | |
14149 | </para> | |
14150 | </entry> | |
14151 | <entry> | |
14152 | <para> | |
14153 | fiber (raw) | |
14154 | </para> | |
14155 | </entry> | |
14156 | </row> | |
14157 | </thead> | |
14158 | <tbody> | |
14159 | <row> | |
14160 | <entry> | |
14161 | <para> | |
14162 | 18 µs | |
14163 | </para> | |
14164 | </entry> | |
14165 | <entry> | |
14166 | <para> | |
14167 | 450 ns | |
14168 | </para> | |
14169 | </entry> | |
14170 | <entry> | |
14171 | <para> | |
14172 | 445 ns | |
14173 | </para> | |
14174 | </entry> | |
14175 | </row> | |
14176 | </tbody> | |
14177 | </tgroup> | |
14178 | </table> | |
14179 | <para> | |
14180 | (from <ulink url="../../performance/fiber/overhead_create.cpp">overhead_create.cpp</ulink>) | |
14181 | </para> | |
14182 | <table frame="all" id="fiber.performance.scaling_of_creating_and_joining"> | |
14183 | <title>Scaling of creating and joining</title> | |
14184 | <tgroup cols="4"> | |
14185 | <thead> | |
14186 | <row> | |
14187 | <entry> | |
14188 | <para> | |
14189 | average of | |
14190 | </para> | |
14191 | </entry> | |
14192 | <entry> | |
14193 | <para> | |
14194 | thread | |
14195 | </para> | |
14196 | </entry> | |
14197 | <entry> | |
14198 | <para> | |
14199 | fiber (atomics) | |
14200 | </para> | |
14201 | </entry> | |
14202 | <entry> | |
14203 | <para> | |
14204 | fiber (raw) | |
14205 | </para> | |
14206 | </entry> | |
14207 | </row> | |
14208 | </thead> | |
14209 | <tbody> | |
14210 | <row> | |
14211 | <entry> | |
14212 | <para> | |
14213 | 10 | |
14214 | </para> | |
14215 | </entry> | |
14216 | <entry> | |
14217 | <para> | |
14218 | 8.21 µs | |
14219 | </para> | |
14220 | </entry> | |
14221 | <entry> | |
14222 | <para> | |
14223 | 1.96 µs | |
14224 | </para> | |
14225 | </entry> | |
14226 | <entry> | |
14227 | <para> | |
14228 | 1.85 µs | |
14229 | </para> | |
14230 | </entry> | |
14231 | </row> | |
14232 | <row> | |
14233 | <entry> | |
14234 | <para> | |
14235 | 50 | |
14236 | </para> | |
14237 | </entry> | |
14238 | <entry> | |
14239 | <para> | |
14240 | 6.67 µs | |
14241 | </para> | |
14242 | </entry> | |
14243 | <entry> | |
14244 | <para> | |
14245 | 1.40 µs | |
14246 | </para> | |
14247 | </entry> | |
14248 | <entry> | |
14249 | <para> | |
14250 | 1.27 µs | |
14251 | </para> | |
14252 | </entry> | |
14253 | </row> | |
14254 | <row> | |
14255 | <entry> | |
14256 | <para> | |
14257 | 100 | |
14258 | </para> | |
14259 | </entry> | |
14260 | <entry> | |
14261 | <para> | |
14262 | 6.79 µs | |
14263 | </para> | |
14264 | </entry> | |
14265 | <entry> | |
14266 | <para> | |
14267 | 1.84 µs | |
14268 | </para> | |
14269 | </entry> | |
14270 | <entry> | |
14271 | <para> | |
14272 | 1.81 µs | |
14273 | </para> | |
14274 | </entry> | |
14275 | </row> | |
14276 | <row> | |
14277 | <entry> | |
14278 | <para> | |
14279 | 500 | |
14280 | </para> | |
14281 | </entry> | |
14282 | <entry> | |
14283 | <para> | |
14284 | 8.25 µs | |
14285 | </para> | |
14286 | </entry> | |
14287 | <entry> | |
14288 | <para> | |
14289 | 1.13 µs | |
14290 | </para> | |
14291 | </entry> | |
14292 | <entry> | |
14293 | <para> | |
14294 | 1.10 µs | |
14295 | </para> | |
14296 | </entry> | |
14297 | </row> | |
14298 | <row> | |
14299 | <entry> | |
14300 | <para> | |
14301 | 1000 | |
14302 | </para> | |
14303 | </entry> | |
14304 | <entry> | |
14305 | <para> | |
14306 | 7.71 µs | |
14307 | </para> | |
14308 | </entry> | |
14309 | <entry> | |
14310 | <para> | |
14311 | 1.46 µs | |
14312 | </para> | |
14313 | </entry> | |
14314 | <entry> | |
14315 | <para> | |
14316 | 1.26 µs | |
14317 | </para> | |
14318 | </entry> | |
14319 | </row> | |
14320 | <row> | |
14321 | <entry> | |
14322 | <para> | |
14323 | 5000 | |
14324 | </para> | |
14325 | </entry> | |
14326 | <entry> | |
14327 | <para> | |
14328 | 5.67 µs | |
14329 | </para> | |
14330 | </entry> | |
14331 | <entry> | |
14332 | <para> | |
14333 | 2.11 µs | |
14334 | </para> | |
14335 | </entry> | |
14336 | <entry> | |
14337 | <para> | |
14338 | 1.90 µs | |
14339 | </para> | |
14340 | </entry> | |
14341 | </row> | |
14342 | <row> | |
14343 | <entry> | |
14344 | <para> | |
14345 | 10000 | |
14346 | </para> | |
14347 | </entry> | |
14348 | <entry> | |
14349 | <para> | |
14350 | 5.25 µs | |
14351 | </para> | |
14352 | </entry> | |
14353 | <entry> | |
14354 | <para> | |
14355 | 2.36 µs | |
14356 | </para> | |
14357 | </entry> | |
14358 | <entry> | |
14359 | <para> | |
14360 | 1.89 µs | |
14361 | </para> | |
14362 | </entry> | |
14363 | </row> | |
14364 | </tbody> | |
14365 | </tgroup> | |
14366 | </table> | |
14367 | <para> | |
14368 | (from <ulink url="../../performance/fiber/scale_join.cpp">scale_join.cpp</ulink>) | |
14369 | </para> | |
14370 | <para> | |
14371 | Numbers of the <ulink url="https://github.com/atemerev/skynet">microbenchmark | |
14372 | <emphasis>syknet</emphasis></ulink> from Alexander Temerev <footnote id="fiber.performance.f1"> | |
14373 | <para> | |
14374 | Intel Core2 Q6700, x86_64, 3GHz | |
14375 | </para> | |
14376 | </footnote>: | |
14377 | </para> | |
14378 | <table frame="all" id="fiber.performance.performance_of_n_100000_actors_goroutines_fibers"> | |
14379 | <title>performance of N=100000 actors/goroutines/fibers</title> | |
14380 | <tgroup cols="5"> | |
14381 | <thead> | |
14382 | <row> | |
14383 | <entry> | |
14384 | <para> | |
14385 | Haskell | stack-1.0.4 | |
14386 | </para> | |
14387 | </entry> | |
14388 | <entry> | |
14389 | <para> | |
14390 | fiber (single threaded/raw) | gcc-5.2.1 | |
14391 | </para> | |
14392 | </entry> | |
14393 | <entry> | |
14394 | <para> | |
14395 | fiber (single threaded/atomics) | gcc-5.2.1 | |
14396 | </para> | |
14397 | </entry> | |
14398 | <entry> | |
14399 | <para> | |
14400 | Erlang | erts-7.0 | |
14401 | </para> | |
14402 | </entry> | |
14403 | <entry> | |
14404 | <para> | |
14405 | Go | go1.4.2 | |
14406 | </para> | |
14407 | </entry> | |
14408 | </row> | |
14409 | </thead> | |
14410 | <tbody> | |
14411 | <row> | |
14412 | <entry> | |
14413 | <para> | |
14414 | 58ms - 108ms | |
14415 | </para> | |
14416 | </entry> | |
14417 | <entry> | |
14418 | <para> | |
14419 | 205ms - 263ms | |
14420 | </para> | |
14421 | </entry> | |
14422 | <entry> | |
14423 | <para> | |
14424 | 221ms - 278ms | |
14425 | </para> | |
14426 | </entry> | |
14427 | <entry> | |
14428 | <para> | |
14429 | 237ms- 470ms | |
14430 | </para> | |
14431 | </entry> | |
14432 | <entry> | |
14433 | <para> | |
14434 | 614ms - 883ms | |
14435 | </para> | |
14436 | </entry> | |
14437 | </row> | |
14438 | </tbody> | |
14439 | </tgroup> | |
14440 | </table> | |
14441 | </section> | |
14442 | <section id="fiber.custom"> | |
14443 | <title><anchor id="custom"/><link linkend="fiber.custom">Customization</link></title> | |
14444 | <bridgehead renderas="sect3" id="fiber.custom.h0"> | |
14445 | <phrase id="fiber.custom.overview"/><link linkend="fiber.custom.overview">Overview</link> | |
14446 | </bridgehead> | |
14447 | <para> | |
14448 | As noted in the <link linkend="scheduling">Scheduling</link> section, by default | |
14449 | <emphasis role="bold">Boost.Fiber</emphasis> uses its own <link linkend="class_round_robin"><code>round_robin</code></link> scheduler | |
14450 | for each thread. To control the way <emphasis role="bold">Boost.Fiber</emphasis> | |
14451 | schedules ready fibers on a particular thread, in general you must follow several | |
14452 | steps. This section discusses those steps, whereas <link linkend="scheduling">Scheduling</link> | |
14453 | serves as a reference for the classes involved. | |
14454 | </para> | |
14455 | <para> | |
14456 | The library's fiber manager keeps track of suspended (blocked) fibers. Only | |
14457 | when a fiber becomes ready to run is it passed to the scheduler. Of course, | |
14458 | if there are fewer than two ready fibers, the scheduler's job is trivial. Only | |
14459 | when there are two or more ready fibers does the particular scheduler implementation | |
14460 | start to influence the overall sequence of fiber execution. | |
14461 | </para> | |
14462 | <para> | |
14463 | In this section we illustrate a simple custom scheduler that honors an integer | |
14464 | fiber priority. We will implement it such that a fiber with higher priority | |
14465 | is preferred over a fiber with lower priority. Any fibers with equal priority | |
14466 | values are serviced on a round-robin basis. | |
14467 | </para> | |
14468 | <para> | |
14469 | The full source code for the examples below is found in <ulink url="../../examples/priority.cpp">priority.cpp</ulink>. | |
14470 | </para> | |
14471 | <bridgehead renderas="sect3" id="fiber.custom.h1"> | |
14472 | <phrase id="fiber.custom.custom_property_class"/><link linkend="fiber.custom.custom_property_class">Custom | |
14473 | Property Class</link> | |
14474 | </bridgehead> | |
14475 | <para> | |
14476 | The first essential point is that we must associate an integer priority with | |
14477 | each fiber.<footnote id="fiber.custom.f0"> | |
14478 | <para> | |
14479 | A previous version of the Fiber library implicitly tracked an int priority | |
14480 | for each fiber, even though the default scheduler ignored it. This has been | |
14481 | dropped, since the library now supports arbitrary scheduler-specific fiber | |
14482 | properties. | |
14483 | </para> | |
14484 | </footnote> | |
14485 | </para> | |
14486 | <para> | |
14487 | One might suggest deriving a custom <link linkend="class_fiber"><code>fiber</code></link> subclass to store such | |
14488 | properties. There are a couple of reasons for the present mechanism. | |
14489 | </para> | |
14490 | <orderedlist> | |
14491 | <listitem> | |
14492 | <simpara> | |
14493 | <emphasis role="bold">Boost.Fiber</emphasis> provides a number of different | |
14494 | ways to launch a fiber. (Consider <link linkend="fibers_async"><code>fibers::async()</code></link>.) Higher-level | |
14495 | libraries might introduce additional such wrapper functions. A custom scheduler | |
14496 | must associate its custom properties with <emphasis>every</emphasis> fiber | |
14497 | in the thread, not only the ones explicitly launched by instantiating a | |
14498 | custom <code><phrase role="identifier">fiber</phrase></code> subclass. | |
14499 | </simpara> | |
14500 | </listitem> | |
14501 | <listitem> | |
14502 | <simpara> | |
14503 | Consider a large existing program that launches fibers in many different | |
14504 | places in the code. We discover a need to introduce a custom scheduler | |
14505 | for a particular thread. If supporting that scheduler's custom properties | |
14506 | required a particular <code><phrase role="identifier">fiber</phrase></code> | |
14507 | subclass, we would have to hunt down and modify every place that launches | |
14508 | a fiber on that thread. | |
14509 | </simpara> | |
14510 | </listitem> | |
14511 | <listitem> | |
14512 | <simpara> | |
14513 | The <link linkend="class_fiber"><code>fiber</code></link> class is actually just a handle to internal <link linkend="class_context"><code>context</code></link> data. | |
14514 | A subclass of <code><phrase role="identifier">fiber</phrase></code> would | |
14515 | not add data to <code><phrase role="identifier">context</phrase></code>. | |
14516 | </simpara> | |
14517 | </listitem> | |
14518 | </orderedlist> | |
14519 | <para> | |
14520 | The present mechanism allows you to <quote>drop in</quote> a custom scheduler | |
14521 | with its attendant custom properties <emphasis>without</emphasis> altering | |
14522 | the rest of your application. | |
14523 | </para> | |
14524 | <para> | |
14525 | Instead of deriving a custom scheduler fiber properties subclass from <link linkend="class_fiber"><code>fiber</code></link>, | |
14526 | you must instead derive it from <link linkend="class_fiber_properties"><code>fiber_properties</code></link>. | |
14527 | </para> | |
14528 | <para> | |
14529 | <programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">priority_props</phrase> <phrase role="special">:</phrase> <phrase role="keyword">public</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber_properties</phrase> <phrase role="special">{</phrase> | |
14530 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
14531 | <phrase role="identifier">priority_props</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">):</phrase> | |
14532 | <phrase role="identifier">fiber_properties</phrase><phrase role="special">(</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">),</phrase> <co id="fiber.custom.c0" linkends="fiber.custom.c1" /> | |
14533 | <phrase role="identifier">priority_</phrase><phrase role="special">(</phrase> <phrase role="number">0</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
14534 | <phrase role="special">}</phrase> | |
14535 | ||
14536 | <phrase role="keyword">int</phrase> <phrase role="identifier">get_priority</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="special">{</phrase> | |
14537 | <phrase role="keyword">return</phrase> <phrase role="identifier">priority_</phrase><phrase role="special">;</phrase> <co id="fiber.custom.c2" linkends="fiber.custom.c3" /> | |
14538 | <phrase role="special">}</phrase> | |
14539 | ||
14540 | <phrase role="comment">// Call this method to alter priority, because we must notify</phrase> | |
14541 | <phrase role="comment">// priority_scheduler of any change.</phrase> | |
14542 | <phrase role="keyword">void</phrase> <phrase role="identifier">set_priority</phrase><phrase role="special">(</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">p</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> <co id="fiber.custom.c4" linkends="fiber.custom.c5" /> | |
14543 | <phrase role="comment">// Of course, it's only worth reshuffling the queue and all if we're</phrase> | |
14544 | <phrase role="comment">// actually changing the priority.</phrase> | |
14545 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">p</phrase> <phrase role="special">!=</phrase> <phrase role="identifier">priority_</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
14546 | <phrase role="identifier">priority_</phrase> <phrase role="special">=</phrase> <phrase role="identifier">p</phrase><phrase role="special">;</phrase> | |
14547 | <phrase role="identifier">notify</phrase><phrase role="special">();</phrase> | |
14548 | <phrase role="special">}</phrase> | |
14549 | <phrase role="special">}</phrase> | |
14550 | ||
14551 | <phrase role="comment">// The fiber name of course is solely for purposes of this example</phrase> | |
14552 | <phrase role="comment">// program; it has nothing to do with implementing scheduler priority.</phrase> | |
14553 | <phrase role="comment">// This is a public data member -- not requiring set/get access methods --</phrase> | |
14554 | <phrase role="comment">// because we need not inform the scheduler of any change.</phrase> | |
14555 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="identifier">name</phrase><phrase role="special">;</phrase> <co id="fiber.custom.c6" linkends="fiber.custom.c7" /> | |
14556 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
14557 | <phrase role="keyword">int</phrase> <phrase role="identifier">priority_</phrase><phrase role="special">;</phrase> | |
14558 | <phrase role="special">};</phrase> | |
14559 | </programlisting> | |
14560 | </para> | |
14561 | <calloutlist> | |
14562 | <callout arearefs="fiber.custom.c0" id="fiber.custom.c1"> | |
14563 | <para> | |
14564 | Your subclass constructor must accept a <literal><link linkend="class_context"><code>context</code></link>*</literal> | |
14565 | and pass it to the <code><phrase role="identifier">fiber_properties</phrase></code> | |
14566 | constructor. | |
14567 | </para> | |
14568 | </callout> | |
14569 | <callout arearefs="fiber.custom.c2" id="fiber.custom.c3"> | |
14570 | <para> | |
14571 | Provide read access methods at your own discretion. | |
14572 | </para> | |
14573 | </callout> | |
14574 | <callout arearefs="fiber.custom.c4" id="fiber.custom.c5"> | |
14575 | <para> | |
14576 | It's important to call <code><phrase role="identifier">notify</phrase><phrase | |
14577 | role="special">()</phrase></code> on any change in a property that can | |
14578 | affect the scheduler's behavior. Therefore, such modifications should only | |
14579 | be performed through an access method. | |
14580 | </para> | |
14581 | </callout> | |
14582 | <callout arearefs="fiber.custom.c6" id="fiber.custom.c7"> | |
14583 | <para> | |
14584 | A property that does not affect the scheduler does not need access methods. | |
14585 | </para> | |
14586 | </callout> | |
14587 | </calloutlist> | |
14588 | <bridgehead renderas="sect3" id="fiber.custom.h2"> | |
14589 | <phrase id="fiber.custom.custom_scheduler_class"/><link linkend="fiber.custom.custom_scheduler_class">Custom | |
14590 | Scheduler Class</link> | |
14591 | </bridgehead> | |
14592 | <para> | |
14593 | Now we can derive a custom scheduler from <link linkend="class_algorithm_with_properties"><code>algorithm_with_properties<></code></link>, | |
14594 | specifying our custom property class <code><phrase role="identifier">priority_props</phrase></code> | |
14595 | as the template parameter. | |
14596 | </para> | |
14597 | <para> | |
14598 | <programlisting><phrase role="keyword">class</phrase> <phrase role="identifier">priority_scheduler</phrase> <phrase role="special">:</phrase> | |
14599 | <phrase role="keyword">public</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">algo</phrase><phrase role="special">::</phrase><phrase role="identifier">algorithm_with_properties</phrase><phrase role="special"><</phrase> <phrase role="identifier">priority_props</phrase> <phrase role="special">></phrase> <phrase role="special">{</phrase> | |
14600 | <phrase role="keyword">private</phrase><phrase role="special">:</phrase> | |
14601 | <phrase role="keyword">typedef</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">scheduler</phrase><phrase role="special">::</phrase><phrase role="identifier">ready_queue_t</phrase><co id="fiber.custom.c8" linkends="fiber.custom.c9" /> <phrase role="identifier">rqueue_t</phrase><phrase role="special">;</phrase> | |
14602 | ||
14603 | <phrase role="identifier">rqueue_t</phrase> <phrase role="identifier">rqueue_</phrase><phrase role="special">;</phrase> | |
14604 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="identifier">mtx_</phrase><phrase role="special">{};</phrase> | |
14605 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">condition_variable</phrase> <phrase role="identifier">cnd_</phrase><phrase role="special">{};</phrase> | |
14606 | <phrase role="keyword">bool</phrase> <phrase role="identifier">flag_</phrase><phrase role="special">{</phrase> <phrase role="keyword">false</phrase> <phrase role="special">};</phrase> | |
14607 | ||
14608 | <phrase role="keyword">public</phrase><phrase role="special">:</phrase> | |
14609 | <phrase role="identifier">priority_scheduler</phrase><phrase role="special">()</phrase> <phrase role="special">:</phrase> | |
14610 | <phrase role="identifier">rqueue_</phrase><phrase role="special">()</phrase> <phrase role="special">{</phrase> | |
14611 | <phrase role="special">}</phrase> | |
14612 | ||
14613 | <phrase role="comment">// For a subclass of algorithm_with_properties<>, it's important to</phrase> | |
14614 | <phrase role="comment">// override the correct awakened() overload.</phrase> | |
14615 | <co id="fiber.custom.c10" linkends="fiber.custom.c11" /><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">,</phrase> <phrase role="identifier">priority_props</phrase> <phrase role="special">&</phrase> <phrase role="identifier">props</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
14616 | <phrase role="keyword">int</phrase> <phrase role="identifier">ctx_priority</phrase> <phrase role="special">=</phrase> <phrase role="identifier">props</phrase><phrase role="special">.</phrase><phrase role="identifier">get_priority</phrase><phrase role="special">();</phrase> <co id="fiber.custom.c12" linkends="fiber.custom.c13" /> | |
14617 | <phrase role="comment">// With this scheduler, fibers with higher priority values are</phrase> | |
14618 | <phrase role="comment">// preferred over fibers with lower priority values. But fibers with</phrase> | |
14619 | <phrase role="comment">// equal priority values are processed in round-robin fashion. So when</phrase> | |
14620 | <phrase role="comment">// we're handed a new context*, put it at the end of the fibers</phrase> | |
14621 | <phrase role="comment">// with that same priority. In other words: search for the first fiber</phrase> | |
14622 | <phrase role="comment">// in the queue with LOWER priority, and insert before that one.</phrase> | |
14623 | <phrase role="identifier">rqueue_t</phrase><phrase role="special">::</phrase><phrase role="identifier">iterator</phrase> <phrase role="identifier">i</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">find_if</phrase><phrase role="special">(</phrase> <phrase role="identifier">rqueue_</phrase><phrase role="special">.</phrase><phrase role="identifier">begin</phrase><phrase role="special">(),</phrase> <phrase role="identifier">rqueue_</phrase><phrase role="special">.</phrase><phrase role="identifier">end</phrase><phrase role="special">(),</phrase> | |
14624 | <phrase role="special">[</phrase><phrase role="identifier">ctx_priority</phrase><phrase role="special">,</phrase><phrase role="keyword">this</phrase><phrase role="special">](</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase> <phrase role="special">&</phrase> <phrase role="identifier">c</phrase><phrase role="special">)</phrase> | |
14625 | <phrase role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">properties</phrase><phrase role="special">(</phrase> <phrase role="special">&</phrase><phrase role="identifier">c</phrase> <phrase role="special">).</phrase><phrase role="identifier">get_priority</phrase><phrase role="special">()</phrase> <phrase role="special"><</phrase> <phrase role="identifier">ctx_priority</phrase><phrase role="special">;</phrase> <phrase role="special">}));</phrase> | |
14626 | <phrase role="comment">// Now, whether or not we found a fiber with lower priority,</phrase> | |
14627 | <phrase role="comment">// insert this new fiber here.</phrase> | |
14628 | <phrase role="identifier">rqueue_</phrase><phrase role="special">.</phrase><phrase role="identifier">insert</phrase><phrase role="special">(</phrase> <phrase role="identifier">i</phrase><phrase role="special">,</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">);</phrase> | |
14629 | <phrase role="special">}</phrase> | |
14630 | ||
14631 | <co id="fiber.custom.c14" linkends="fiber.custom.c15" /><phrase role="keyword">virtual</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">pick_next</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
14632 | <phrase role="comment">// if ready queue is empty, just tell caller</phrase> | |
14633 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="identifier">rqueue_</phrase><phrase role="special">.</phrase><phrase role="identifier">empty</phrase><phrase role="special">()</phrase> <phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
14634 | <phrase role="keyword">return</phrase> <phrase role="keyword">nullptr</phrase><phrase role="special">;</phrase> | |
14635 | <phrase role="special">}</phrase> | |
14636 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">(</phrase> <phrase role="special">&</phrase> <phrase role="identifier">rqueue_</phrase><phrase role="special">.</phrase><phrase role="identifier">front</phrase><phrase role="special">()</phrase> <phrase role="special">);</phrase> | |
14637 | <phrase role="identifier">rqueue_</phrase><phrase role="special">.</phrase><phrase role="identifier">pop_front</phrase><phrase role="special">();</phrase> | |
14638 | <phrase role="keyword">return</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">;</phrase> | |
14639 | <phrase role="special">}</phrase> | |
14640 | ||
14641 | <co id="fiber.custom.c16" linkends="fiber.custom.c17" /><phrase role="keyword">virtual</phrase> <phrase role="keyword">bool</phrase> <phrase role="identifier">has_ready_fibers</phrase><phrase role="special">()</phrase> <phrase role="keyword">const</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
14642 | <phrase role="keyword">return</phrase> <phrase role="special">!</phrase> <phrase role="identifier">rqueue_</phrase><phrase role="special">.</phrase><phrase role="identifier">empty</phrase><phrase role="special">();</phrase> | |
14643 | <phrase role="special">}</phrase> | |
14644 | ||
14645 | <co id="fiber.custom.c18" linkends="fiber.custom.c19" /><phrase role="keyword">virtual</phrase> <phrase role="keyword">void</phrase> <phrase role="identifier">property_change</phrase><phrase role="special">(</phrase> <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">context</phrase> <phrase role="special">*</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">,</phrase> <phrase role="identifier">priority_props</phrase> <phrase role="special">&</phrase> <phrase role="identifier">props</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
14646 | <phrase role="comment">// Although our priority_props class defines multiple properties, only</phrase> | |
14647 | <phrase role="comment">// one of them (priority) actually calls notify() when changed. The</phrase> | |
14648 | <phrase role="comment">// point of a property_change() override is to reshuffle the ready</phrase> | |
14649 | <phrase role="comment">// queue according to the updated priority value.</phrase> | |
14650 | ||
14651 | <phrase role="comment">// 'ctx' might not be in our queue at all, if caller is changing the</phrase> | |
14652 | <phrase role="comment">// priority of (say) the running fiber. If it's not there, no need to</phrase> | |
14653 | <phrase role="comment">// move it: we'll handle it next time it hits awakened().</phrase> | |
14654 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">!</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">-></phrase><phrase role="identifier">ready_is_linked</phrase><phrase role="special">())</phrase> <phrase role="special">{</phrase> <co id="fiber.custom.c20" linkends="fiber.custom.c21" /> | |
14655 | <phrase role="keyword">return</phrase><phrase role="special">;</phrase> | |
14656 | <phrase role="special">}</phrase> | |
14657 | ||
14658 | <phrase role="comment">// Found ctx: unlink it</phrase> | |
14659 | <phrase role="identifier">ctx</phrase><phrase role="special">-></phrase><phrase role="identifier">ready_unlink</phrase><phrase role="special">();</phrase> | |
14660 | ||
14661 | <phrase role="comment">// Here we know that ctx was in our ready queue, but we've unlinked</phrase> | |
14662 | <phrase role="comment">// it. We happen to have a method that will (re-)add a context* to the</phrase> | |
14663 | <phrase role="comment">// right place in the ready queue.</phrase> | |
14664 | <phrase role="identifier">awakened</phrase><phrase role="special">(</phrase> <phrase role="identifier">ctx</phrase><phrase role="special">,</phrase> <phrase role="identifier">props</phrase><phrase role="special">);</phrase> | |
14665 | <phrase role="special">}</phrase> | |
14666 | ||
14667 | <phrase role="keyword">void</phrase> <phrase role="identifier">suspend_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">time_point</phrase><phrase role="special">)</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
14668 | <phrase role="keyword">if</phrase> <phrase role="special">(</phrase> <phrase role="special">(</phrase><phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">chrono</phrase><phrase role="special">::</phrase><phrase role="identifier">steady_clock</phrase><phrase role="special">::</phrase><phrase role="identifier">time_point</phrase><phrase role="special">::</phrase><phrase role="identifier">max</phrase><phrase role="special">)()</phrase> <phrase role="special">==</phrase> <phrase role="identifier">time_point</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
14669 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx_</phrase><phrase role="special">);</phrase> | |
14670 | <phrase role="identifier">cnd_</phrase><phrase role="special">.</phrase><phrase role="identifier">wait</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="special">[</phrase><phrase role="keyword">this</phrase><phrase role="special">](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">flag_</phrase><phrase role="special">;</phrase> <phrase role="special">});</phrase> | |
14671 | <phrase role="identifier">flag_</phrase> <phrase role="special">=</phrase> <phrase role="keyword">false</phrase><phrase role="special">;</phrase> | |
14672 | <phrase role="special">}</phrase> <phrase role="keyword">else</phrase> <phrase role="special">{</phrase> | |
14673 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx_</phrase><phrase role="special">);</phrase> | |
14674 | <phrase role="identifier">cnd_</phrase><phrase role="special">.</phrase><phrase role="identifier">wait_until</phrase><phrase role="special">(</phrase> <phrase role="identifier">lk</phrase><phrase role="special">,</phrase> <phrase role="identifier">time_point</phrase><phrase role="special">,</phrase> <phrase role="special">[</phrase><phrase role="keyword">this</phrase><phrase role="special">](){</phrase> <phrase role="keyword">return</phrase> <phrase role="identifier">flag_</phrase><phrase role="special">;</phrase> <phrase role="special">});</phrase> | |
14675 | <phrase role="identifier">flag_</phrase> <phrase role="special">=</phrase> <phrase role="keyword">false</phrase><phrase role="special">;</phrase> | |
14676 | <phrase role="special">}</phrase> | |
14677 | <phrase role="special">}</phrase> | |
14678 | ||
14679 | <phrase role="keyword">void</phrase> <phrase role="identifier">notify</phrase><phrase role="special">()</phrase> <phrase role="keyword">noexcept</phrase> <phrase role="special">{</phrase> | |
14680 | <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">unique_lock</phrase><phrase role="special"><</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">mutex</phrase> <phrase role="special">></phrase> <phrase role="identifier">lk</phrase><phrase role="special">(</phrase> <phrase role="identifier">mtx_</phrase><phrase role="special">);</phrase> | |
14681 | <phrase role="identifier">flag_</phrase> <phrase role="special">=</phrase> <phrase role="keyword">true</phrase><phrase role="special">;</phrase> | |
14682 | <phrase role="identifier">lk</phrase><phrase role="special">.</phrase><phrase role="identifier">unlock</phrase><phrase role="special">();</phrase> | |
14683 | <phrase role="identifier">cnd_</phrase><phrase role="special">.</phrase><phrase role="identifier">notify_all</phrase><phrase role="special">();</phrase> | |
14684 | <phrase role="special">}</phrase> | |
14685 | <phrase role="special">};</phrase> | |
14686 | </programlisting> | |
14687 | </para> | |
14688 | <calloutlist> | |
14689 | <callout arearefs="fiber.custom.c8" id="fiber.custom.c9"> | |
14690 | <para> | |
14691 | See <link linkend="ready_queue_t">ready_queue_t</link>. | |
14692 | </para> | |
14693 | </callout> | |
14694 | <callout arearefs="fiber.custom.c10" id="fiber.custom.c11"> | |
14695 | <para> | |
14696 | You must override the <link linkend="algorithm_with_properties_awakened"><code>algorithm_with_properties::awakened()</code></link> | |
14697 | method. | |
14698 | This is how your scheduler receives notification of a fiber that has become | |
14699 | ready to run. | |
14700 | </para> | |
14701 | </callout> | |
14702 | <callout arearefs="fiber.custom.c12" id="fiber.custom.c13"> | |
14703 | <para> | |
14704 | <code><phrase role="identifier">props</phrase></code> is the instance of | |
14705 | priority_props associated with the passed fiber <code><phrase role="identifier">ctx</phrase></code>. | |
14706 | </para> | |
14707 | </callout> | |
14708 | <callout arearefs="fiber.custom.c14" id="fiber.custom.c15"> | |
14709 | <para> | |
14710 | You must override the <link linkend="algorithm_with_properties_pick_next"><code>algorithm_with_properties::pick_next()</code></link> | |
14711 | method. | |
14712 | This is how your scheduler actually advises the fiber manager of the next | |
14713 | fiber to run. | |
14714 | </para> | |
14715 | </callout> | |
14716 | <callout arearefs="fiber.custom.c16" id="fiber.custom.c17"> | |
14717 | <para> | |
14718 | You must override <link linkend="algorithm_with_properties_has_ready_fibers"><code>algorithm_with_properties::has_ready_fibers()</code></link> | |
14719 | to | |
14720 | inform the fiber manager of the state of your ready queue. | |
14721 | </para> | |
14722 | </callout> | |
14723 | <callout arearefs="fiber.custom.c18" id="fiber.custom.c19"> | |
14724 | <para> | |
14725 | Overriding <link linkend="algorithm_with_properties_property_change"><code>algorithm_with_properties::property_change()</code></link> | |
14726 | is | |
14727 | optional. This override handles the case in which the running fiber changes | |
14728 | the priority of another ready fiber: a fiber already in our queue. In that | |
14729 | case, move the updated fiber within the queue. | |
14730 | </para> | |
14731 | </callout> | |
14732 | <callout arearefs="fiber.custom.c20" id="fiber.custom.c21"> | |
14733 | <para> | |
14734 | Your <code><phrase role="identifier">property_change</phrase><phrase role="special">()</phrase></code> | |
14735 | override must be able to handle the case in which the passed <code><phrase | |
14736 | role="identifier">ctx</phrase></code> is not in your ready queue. It might | |
14737 | be running, or it might be blocked. | |
14738 | </para> | |
14739 | </callout> | |
14740 | </calloutlist> | |
14741 | <para> | |
14742 | Our example <code><phrase role="identifier">priority_scheduler</phrase></code> | |
14743 | doesn't override <link linkend="algorithm_with_properties_new_properties"><code>algorithm_with_properties::new_properties()</code></link>: | |
14744 | we're content with allocating <code><phrase role="identifier">priority_props</phrase></code> | |
14745 | instances on the heap. | |
14746 | </para> | |
14747 | <bridgehead renderas="sect3" id="fiber.custom.h3"> | |
14748 | <phrase id="fiber.custom.replace_default_scheduler"/><link linkend="fiber.custom.replace_default_scheduler">Replace | |
14749 | Default Scheduler</link> | |
14750 | </bridgehead> | |
14751 | <para> | |
14752 | You must call <link linkend="use_scheduling_algorithm"><code>use_scheduling_algorithm()</code></link> at the start | |
14753 | of each thread on which you want <emphasis role="bold">Boost.Fiber</emphasis> | |
14754 | to use your custom scheduler rather than its own default <link linkend="class_round_robin"><code>round_robin</code></link>. | |
14755 | Specifically, you must call <code><phrase role="identifier">use_scheduling_algorithm</phrase><phrase | |
14756 | role="special">()</phrase></code> before performing any other <emphasis role="bold">Boost.Fiber</emphasis> | |
14757 | operations on that thread. | |
14758 | </para> | |
14759 | <para> | |
14760 | <programlisting><phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">(</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">argc</phrase><phrase role="special">,</phrase> <phrase role="keyword">char</phrase> <phrase role="special">*</phrase><phrase role="identifier">argv</phrase><phrase role="special">[])</phrase> <phrase role="special">{</phrase> | |
14761 | <phrase role="comment">// make sure we use our priority_scheduler rather than default round_robin</phrase> | |
14762 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">use_scheduling_algorithm</phrase><phrase role="special"><</phrase> <phrase role="identifier">priority_scheduler</phrase> <phrase role="special">>();</phrase> | |
14763 | <phrase role="special">...</phrase> | |
14764 | <phrase role="special">}</phrase> | |
14765 | </programlisting> | |
14766 | </para> | |
14767 | <bridgehead renderas="sect3" id="fiber.custom.h4"> | |
14768 | <phrase id="fiber.custom.use_properties"/><link linkend="fiber.custom.use_properties">Use | |
14769 | Properties</link> | |
14770 | </bridgehead> | |
14771 | <para> | |
14772 | The running fiber can access its own <link linkend="class_fiber_properties"><code>fiber_properties</code></link> subclass | |
14773 | instance by calling <link linkend="this_fiber_properties"><code>this_fiber::properties()</code></link>. Although | |
14774 | <code><phrase role="identifier">properties</phrase><phrase role="special"><>()</phrase></code> | |
14775 | is a nullary function, you must pass, as a template parameter, the <code><phrase | |
14776 | role="identifier">fiber_properties</phrase></code> subclass. | |
14777 | </para> | |
14778 | <para> | |
14779 | <programlisting><phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">this_fiber</phrase><phrase role="special">::</phrase><phrase role="identifier">properties</phrase><phrase role="special"><</phrase> <phrase role="identifier">priority_props</phrase> <phrase role="special">>().</phrase><phrase role="identifier">name</phrase> <phrase role="special">=</phrase> <phrase role="string">"main"</phrase><phrase role="special">;</phrase> | |
14780 | </programlisting> | |
14781 | </para> | |
14782 | <para> | |
14783 | Given a <link linkend="class_fiber"><code>fiber</code></link> instance still connected with a running fiber (that | |
14784 | is, not <link linkend="fiber_detach"><code>fiber::detach()</code></link>ed), you may access that fiber's properties | |
14785 | using <link linkend="fiber_properties"><code>fiber::properties()</code></link>. As with <code><phrase role="identifier">this_fiber</phrase><phrase | |
14786 | role="special">::</phrase><phrase role="identifier">properties</phrase><phrase | |
14787 | role="special"><>()</phrase></code>, you must pass your <code><phrase | |
14788 | role="identifier">fiber_properties</phrase></code> subclass as the template | |
14789 | parameter. | |
14790 | </para> | |
14791 | <para> | |
14792 | <programlisting><phrase role="keyword">template</phrase><phrase role="special"><</phrase> <phrase role="keyword">typename</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">></phrase> | |
14793 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">launch</phrase><phrase role="special">(</phrase> <phrase role="identifier">Fn</phrase> <phrase role="special">&&</phrase> <phrase role="identifier">func</phrase><phrase role="special">,</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">string</phrase> <phrase role="keyword">const</phrase><phrase role="special">&</phrase> <phrase role="identifier">name</phrase><phrase role="special">,</phrase> <phrase role="keyword">int</phrase> <phrase role="identifier">priority</phrase><phrase role="special">)</phrase> <phrase role="special">{</phrase> | |
14794 | <phrase role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">fibers</phrase><phrase role="special">::</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">(</phrase> <phrase role="identifier">func</phrase><phrase role="special">);</phrase> | |
14795 | <phrase role="identifier">priority_props</phrase> <phrase role="special">&</phrase> <phrase role="identifier">props</phrase><phrase role="special">(</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">.</phrase><phrase role="identifier">properties</phrase><phrase role="special"><</phrase> <phrase role="identifier">priority_props</phrase> <phrase role="special">>()</phrase> <phrase role="special">);</phrase> | |
14796 | <phrase role="identifier">props</phrase><phrase role="special">.</phrase><phrase role="identifier">name</phrase> <phrase role="special">=</phrase> <phrase role="identifier">name</phrase><phrase role="special">;</phrase> | |
14797 | <phrase role="identifier">props</phrase><phrase role="special">.</phrase><phrase role="identifier">set_priority</phrase><phrase role="special">(</phrase> <phrase role="identifier">priority</phrase><phrase role="special">);</phrase> | |
14798 | <phrase role="keyword">return</phrase> <phrase role="identifier">fiber</phrase><phrase role="special">;</phrase> | |
14799 | <phrase role="special">}</phrase> | |
14800 | </programlisting> | |
14801 | </para> | |
14802 | <para> | |
14803 | Launching a new fiber schedules that fiber as ready, but does <emphasis>not</emphasis> | |
14804 | immediately enter its <emphasis>fiber-function</emphasis>. The current fiber | |
14805 | retains control until it blocks (or yields, or terminates) for some other reason. | |
14806 | As shown in the <code><phrase role="identifier">launch</phrase><phrase role="special">()</phrase></code> | |
14807 | function above, it is reasonable to launch a fiber and immediately set relevant | |
14808 | properties -- such as, for instance, its priority. Your custom scheduler can | |
14809 | then make use of this information next time the fiber manager calls <link linkend="algorithm_with_properties_pick_next"><code>algorithm_with_properties::pick_next()</code></link>. | |
14810 | </para> | |
14811 | </section> | |
14812 | <section id="fiber.rationale"> | |
14813 | <title><link linkend="fiber.rationale">Rationale</link></title> | |
14814 | <bridgehead renderas="sect3" id="fiber.rationale.h0"> | |
14815 | <phrase id="fiber.rationale.distinction_between_coroutines_and_fibers"/><link | |
14816 | linkend="fiber.rationale.distinction_between_coroutines_and_fibers">distinction | |
14817 | between coroutines and fibers</link> | |
14818 | </bridgehead> | |
14819 | <para> | |
14820 | The fiber library extends the coroutine library by adding a scheduler and synchronization | |
14821 | mechanisms. | |
14822 | </para> | |
14823 | <itemizedlist> | |
14824 | <listitem> | |
14825 | <simpara> | |
14826 | a coroutine yields | |
14827 | </simpara> | |
14828 | </listitem> | |
14829 | <listitem> | |
14830 | <simpara> | |
14831 | a fiber blocks | |
14832 | </simpara> | |
14833 | </listitem> | |
14834 | </itemizedlist> | |
14835 | <para> | |
14836 | When a coroutine yields, it passes control directly to its caller (or, in the | |
14837 | case of symmetric coroutines, a designated other coroutine). When a fiber blocks, | |
14838 | it implicitly passes control to the fiber scheduler. Coroutines have no scheduler | |
14839 | because they need no scheduler.<footnote id="fiber.rationale.f0"> | |
14840 | <para> | |
14841 | <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4024.pdf">'N4024: | |
14842 | Distinguishing coroutines and fibers'</ulink> | |
14843 | </para> | |
14844 | </footnote>. | |
14845 | </para> | |
14846 | <bridgehead renderas="sect3" id="fiber.rationale.h1"> | |
14847 | <phrase id="fiber.rationale.what_about_transactional_memory"/><link linkend="fiber.rationale.what_about_transactional_memory">what | |
14848 | about transactional memory</link> | |
14849 | </bridgehead> | |
14850 | <para> | |
14851 | GCC supports transactional memory since version 4.7. Unfortunately tests show | |
14852 | that transactional memory is slower (ca. 4x) than spinlocks using atomics. | |
14853 | Once transactional memory is improved (supporting hybrid tm), spinlocks will | |
14854 | be replaced by __transaction_atomic{} statements surrounding the critical sections. | |
14855 | </para> | |
14856 | <bridgehead renderas="sect3" id="fiber.rationale.h2"> | |
14857 | <phrase id="fiber.rationale.synchronization_between_fibers_running_in_different_threads"/><link | |
14858 | linkend="fiber.rationale.synchronization_between_fibers_running_in_different_threads">synchronization | |
14859 | between fibers running in different threads</link> | |
14860 | </bridgehead> | |
14861 | <para> | |
14862 | Synchronization classes from <ulink url="http://www.boost.org/doc/libs/release/libs/thread/index.html">Boost.Thread</ulink> | |
14863 | block the entire thread. In contrast, the synchronization classes from <emphasis | |
14864 | role="bold">Boost.Fiber</emphasis> block only specific fibers, so that the | |
14865 | scheduler can still keep the thread busy running other fibers in the meantime. | |
14866 | The synchronization classes from <emphasis role="bold">Boost.Fiber</emphasis> | |
14867 | are designed to be thread-safe, i.e. it is possible to synchronize fibers running | |
14868 | in different threads as well as fibers running in the same thread. (However, | |
14869 | there is a build option to disable cross-thread fiber synchronization support; | |
14870 | see <link linkend="cross_thread_sync">this description</link>.) | |
14871 | </para> | |
14872 | <anchor id="spurious_wakeup"/> | |
14873 | <bridgehead renderas="sect3" id="fiber.rationale.h3"> | |
14874 | <phrase id="fiber.rationale.spurious_wakeup"/><link linkend="fiber.rationale.spurious_wakeup">spurious | |
14875 | wakeup</link> | |
14876 | </bridgehead> | |
14877 | <para> | |
14878 | Spurious wakeup can happen when using <ulink url="http://en.cppreference.com/w/cpp/thread/condition_variable"><code><phrase | |
14879 | role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">condition_variable</phrase></code></ulink>: | |
14880 | the condition variable appears to be have been signaled while the awaited condition | |
14881 | may still be false. Spurious wakeup can happen repeatedly and is caused on | |
14882 | some multiprocessor systems where making <code><phrase role="identifier">std</phrase><phrase | |
14883 | role="special">::</phrase><phrase role="identifier">condition_variable</phrase></code> | |
14884 | wakeup completely predictable would slow down all <code><phrase role="identifier">std</phrase><phrase | |
14885 | role="special">::</phrase><phrase role="identifier">condition_variable</phrase></code> | |
14886 | operations.<footnote id="fiber.rationale.f1"> | |
14887 | <para> | |
14888 | David R. Butenhof <quote>Programming with POSIX Threads</quote> | |
14889 | </para> | |
14890 | </footnote> | |
14891 | </para> | |
14892 | <para> | |
14893 | <link linkend="class_condition_variable"><code>condition_variable</code></link> is not subject to spurious wakeup. | |
14894 | Nonetheless it is prudent to test the business-logic condition in a <code><phrase | |
14895 | role="identifier">wait</phrase><phrase role="special">()</phrase></code> loop | |
14896 | — or, equivalently, use one of the <code><phrase role="identifier">wait</phrase><phrase | |
14897 | role="special">(</phrase> <phrase role="identifier">lock</phrase><phrase role="special">,</phrase> | |
14898 | <phrase role="identifier">predicate</phrase> <phrase role="special">)</phrase></code> | |
14899 | overloads. | |
14900 | </para> | |
14901 | <para> | |
14902 | See also <link linkend="condition_variable_spurious_wakeups">No Spurious Wakeups</link>. | |
14903 | </para> | |
14904 | <bridgehead renderas="sect3" id="fiber.rationale.h4"> | |
14905 | <phrase id="fiber.rationale.migrating_fibers_between_threads"/><link linkend="fiber.rationale.migrating_fibers_between_threads">migrating | |
14906 | fibers between threads</link> | |
14907 | </bridgehead> | |
14908 | <para> | |
14909 | Support for migrating fibers between threads has been integrated. The user-defined | |
14910 | scheduler must call <link linkend="context_detach"><code>context::detach()</code></link> on a fiber-context on the | |
14911 | source thread and <link linkend="context_attach"><code>context::attach()</code></link> on the destination thread, | |
14912 | passing the fiber-context to migrate. (For more information about custom schedulers, | |
14913 | see <link linkend="custom">Customization</link>.) Examples <code><phrase role="identifier">work_sharing</phrase></code> | |
14914 | and <code><phrase role="identifier">work_stealing</phrase></code> in directory | |
14915 | <code><phrase role="identifier">examples</phrase></code> might be used as a | |
14916 | blueprint. | |
14917 | </para> | |
14918 | <para> | |
14919 | See also <link linkend="migration">Migrating fibers between threads</link>. | |
14920 | </para> | |
14921 | <bridgehead renderas="sect3" id="fiber.rationale.h5"> | |
14922 | <phrase id="fiber.rationale.support_for_boost_asio"/><link linkend="fiber.rationale.support_for_boost_asio">support | |
14923 | for Boost.Asio</link> | |
14924 | </bridgehead> | |
14925 | <para> | |
14926 | Support for <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink>’s | |
14927 | <emphasis>async-result</emphasis> is not part of the official API. However, | |
14928 | to integrate with a <ulink url="http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_service.html"><code><phrase | |
14929 | role="identifier">boost</phrase><phrase role="special">::</phrase><phrase role="identifier">asio</phrase><phrase | |
14930 | role="special">::</phrase><phrase role="identifier">io_service</phrase></code></ulink>, | |
14931 | see <link linkend="integration">Sharing a Thread with Another Main Loop</link>. | |
14932 | To interface smoothly with an arbitrary Asio async I/O operation, see <link | |
14933 | linkend="callbacks_asio">Then There’s <ulink url="http://www.boost.org/doc/libs/release/libs/asio/index.html">Boost.Asio</ulink></link>. | |
14934 | </para> | |
14935 | <bridgehead renderas="sect3" id="fiber.rationale.h6"> | |
14936 | <phrase id="fiber.rationale.tested_compilers"/><link linkend="fiber.rationale.tested_compilers">tested | |
14937 | compilers</link> | |
14938 | </bridgehead> | |
14939 | <para> | |
14940 | The library was tested with GCC-5.1.1, Clang-3.6.0 and MSVC-14.0 in c++11-mode. | |
14941 | </para> | |
14942 | <bridgehead renderas="sect3" id="fiber.rationale.h7"> | |
14943 | <phrase id="fiber.rationale.supported_architectures"/><link linkend="fiber.rationale.supported_architectures">supported | |
14944 | architectures</link> | |
14945 | </bridgehead> | |
14946 | <para> | |
14947 | <emphasis role="bold">Boost.Fiber</emphasis> depends on <ulink url="http://www.boost.org/doc/libs/release/libs/context/index.html">Boost.Context</ulink> | |
14948 | - the list of supported architectures can be found <ulink url="http://www.boost.org/doc/libs/release/libs/context/doc/html/context/architectures.html">here</ulink>. | |
14949 | </para> | |
14950 | </section> | |
14951 | <section id="fiber.acknowledgements"> | |
14952 | <title><link linkend="fiber.acknowledgements">Acknowledgments</link></title> | |
14953 | <para> | |
14954 | I'd like to thank Agustín Bergé, Eugene Yakubovich, Giovanni Piero Deretta | |
14955 | and especially Nat Goodspeed. | |
14956 | </para> | |
14957 | </section> | |
14958 | <section id="fiber.installing"> | |
14959 | <title><link linkend="fiber.installing">Appendix: Installing and Running Tests</link></title> | |
14960 | <bridgehead renderas="sect3" id="fiber.installing.h0"> | |
14961 | <phrase id="fiber.installing.installing_the_fiber_library"/><link linkend="fiber.installing.installing_the_fiber_library">Installing | |
14962 | the Fiber library</link> | |
14963 | </bridgehead> | |
14964 | <para> | |
14965 | As Fiber is not yet officially part of Boost, it is necessary to embed it in | |
14966 | an existing <ulink url="http://www.boost.org/users/download/">Boost source | |
14967 | tree</ulink>. | |
14968 | </para> | |
14969 | <para> | |
14970 | The <ulink url="https://github.com/olk/boost-fiber/archive/master.zip">downloaded | |
14971 | Fiber library</ulink> can be placed into an existing Boost source tree by moving | |
14972 | the top-level Fiber directory to <code><phrase role="identifier">libs</phrase><phrase | |
14973 | role="special">/</phrase><phrase role="identifier">fiber</phrase></code> under | |
14974 | the top-level Boost directory, then further moving <code><phrase role="identifier">libs</phrase><phrase | |
14975 | role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase | |
14976 | role="identifier">include</phrase><phrase role="special">/</phrase><phrase | |
14977 | role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase></code> | |
14978 | (in other words, the Fiber library's <code><phrase role="identifier">include</phrase><phrase | |
14979 | role="special">/</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase | |
14980 | role="identifier">fiber</phrase></code> directory) to <code><phrase role="identifier">boost</phrase><phrase | |
14981 | role="special">/</phrase><phrase role="identifier">fiber</phrase></code> under | |
14982 | the top-level Boost directory. | |
14983 | </para> | |
14984 | <para> | |
14985 | On a Posix system such as Linux or OS X, you may use symlinks instead. | |
14986 | </para> | |
14987 | <para> | |
14988 | Create a symlink from the Boost directory's <code><phrase role="identifier">libs</phrase><phrase | |
14989 | role="special">/</phrase><phrase role="identifier">fiber</phrase></code> to | |
14990 | the top-level Fiber directory, e.g.: | |
14991 | </para> | |
14992 | <programlisting><phrase role="identifier">cd</phrase> <phrase role="special">~/</phrase><phrase role="identifier">boost_1_61_0</phrase> | |
14993 | <phrase role="identifier">ln</phrase> <phrase role="special">-</phrase><phrase role="identifier">s</phrase> <phrase role="special">~/</phrase><phrase role="identifier">boost</phrase><phrase role="special">-</phrase><phrase role="identifier">fiber</phrase><phrase role="special">-</phrase><phrase role="identifier">master</phrase> <phrase role="identifier">libs</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase> | |
14994 | </programlisting> | |
14995 | <para> | |
14996 | Then create a symlink from the Boost directory's <code><phrase role="identifier">boost</phrase><phrase | |
14997 | role="special">/</phrase><phrase role="identifier">fiber</phrase></code> to | |
14998 | the Fiber library's <code><phrase role="identifier">include</phrase><phrase | |
14999 | role="special">/</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase | |
15000 | role="identifier">fiber</phrase></code> directory: | |
15001 | </para> | |
15002 | <programlisting><phrase role="identifier">cd</phrase> <phrase role="identifier">boost</phrase> | |
15003 | <phrase role="identifier">ln</phrase> <phrase role="special">-</phrase><phrase role="identifier">s</phrase> <phrase role="special">../</phrase><phrase role="identifier">libs</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">include</phrase><phrase role="special">/</phrase><phrase role="identifier">boost</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase> <phrase role="identifier">fiber</phrase> | |
15004 | </programlisting> | |
15005 | <para> | |
15006 | For some versions of the Boost.Build system, it was important to use a relative | |
15007 | symlink of that form for <code><phrase role="identifier">boost</phrase><phrase | |
15008 | role="special">/</phrase><phrase role="identifier">fiber</phrase></code>. | |
15009 | </para> | |
15010 | <anchor id="tests"/> | |
15011 | <bridgehead renderas="sect3" id="fiber.installing.h1"> | |
15012 | <phrase id="fiber.installing.running_tests"/><link linkend="fiber.installing.running_tests">Running | |
15013 | Tests</link> | |
15014 | </bridgehead> | |
15015 | <para> | |
15016 | Once the Fiber library has been overlaid (or symlinked) into the Boost source | |
15017 | tree this way, the Boost.Build system can build it like any other Boost library. | |
15018 | In particular: | |
15019 | </para> | |
15020 | <programlisting><phrase role="identifier">cd</phrase> <phrase role="special">~/</phrase><phrase role="identifier">boost_1_61_0</phrase> | |
15021 | <phrase role="special">./</phrase><phrase role="identifier">bootstrap</phrase><phrase role="special">.</phrase><phrase role="identifier">sh</phrase> | |
15022 | <phrase role="special">./</phrase><phrase role="identifier">b2</phrase> <phrase role="identifier">libs</phrase><phrase role="special">/</phrase><phrase role="identifier">fiber</phrase><phrase role="special">/</phrase><phrase role="identifier">test</phrase> | |
15023 | </programlisting> | |
15024 | <para> | |
15025 | On Windows, the commands would look more like: | |
15026 | </para> | |
15027 | <programlisting><phrase role="identifier">cd</phrase> <phrase role="special">/</phrase><phrase role="identifier">D</phrase> <phrase role="special">%</phrase><phrase role="identifier">HOMEDRIVE</phrase><phrase role="special">%%</phrase><phrase role="identifier">HOMEPATH</phrase><phrase role="special">%\</phrase><phrase role="identifier">boost_1_61_0</phrase> | |
15028 | <phrase role="identifier">bootstrap</phrase> | |
15029 | <phrase role="identifier">b2</phrase> <phrase role="identifier">libs</phrase><phrase role="special">\</phrase><phrase role="identifier">fiber</phrase><phrase role="special">\</phrase><phrase role="identifier">test</phrase> | |
15030 | </programlisting> | |
15031 | </section> | |
15032 | </library> |