]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <html> |
2 | <head> | |
3 | <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> | |
4 | <title>when_any / when_all functionality</title> | |
5 | <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> | |
6 | <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> | |
7 | <link rel="home" href="../index.html" title="Chapter 1. Fiber"> | |
8 | <link rel="up" href="../index.html" title="Chapter 1. Fiber"> | |
9 | <link rel="prev" href="nonblocking.html" title="Integrating Fibers with Nonblocking I/O"> | |
10 | <link rel="next" href="when_any/when_any.html" title="when_any"> | |
11 | </head> | |
12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> | |
13 | <table cellpadding="2" width="100%"><tr> | |
14 | <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> | |
15 | <td align="center"><a href="../../../../../index.html">Home</a></td> | |
16 | <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> | |
17 | <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> | |
18 | <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> | |
19 | <td align="center"><a href="../../../../../more/index.htm">More</a></td> | |
20 | </tr></table> | |
21 | <hr> | |
22 | <div class="spirit-nav"> | |
23 | <a accesskey="p" href="nonblocking.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="when_any/when_any.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> | |
24 | </div> | |
25 | <div class="section"> | |
26 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | |
27 | <a name="fiber.when_any"></a><a name="when_any"></a><a class="link" href="when_any.html" title="when_any / when_all functionality">when_any / when_all | |
28 | functionality</a> | |
29 | </h2></div></div></div> | |
30 | <div class="toc"><dl> | |
31 | <dt><span class="section"><a href="when_any/when_any.html">when_any</a></span></dt> | |
32 | <dd><dl> | |
33 | <dt><span class="section"><a href="when_any/when_any/when_any__simple_completion.html">when_any, | |
34 | simple completion</a></span></dt> | |
35 | <dt><span class="section"><a href="when_any/when_any/when_any__return_value.html">when_any, | |
36 | return value</a></span></dt> | |
37 | <dt><span class="section"><a href="when_any/when_any/when_any__produce_first_outcome__whether_result_or_exception.html">when_any, | |
38 | produce first outcome, whether result or exception</a></span></dt> | |
39 | <dt><span class="section"><a href="when_any/when_any/when_any__produce_first_success.html">when_any, | |
40 | produce first success</a></span></dt> | |
41 | <dt><span class="section"><a href="when_any/when_any/when_any__heterogeneous_types.html">when_any, | |
42 | heterogeneous types</a></span></dt> | |
43 | <dt><span class="section"><a href="when_any/when_any/when_any__a_dubious_alternative.html">when_any, | |
44 | a dubious alternative</a></span></dt> | |
45 | </dl></dd> | |
46 | <dt><span class="section"><a href="when_any/when_all_functionality.html">when_all functionality</a></span></dt> | |
47 | <dd><dl> | |
48 | <dt><span class="section"><a href="when_any/when_all_functionality/when_all__simple_completion.html">when_all, | |
49 | simple completion</a></span></dt> | |
50 | <dt><span class="section"><a href="when_any/when_all_functionality/when_all__return_values.html">when_all, | |
51 | return values</a></span></dt> | |
52 | <dt><span class="section"><a href="when_any/when_all_functionality/when_all_until_first_exception.html">when_all | |
53 | until first exception</a></span></dt> | |
54 | <dt><span class="section"><a href="when_any/when_all_functionality/wait_all__collecting_all_exceptions.html">wait_all, | |
55 | collecting all exceptions</a></span></dt> | |
56 | <dt><span class="section"><a href="when_any/when_all_functionality/when_all__heterogeneous_types.html">when_all, | |
57 | heterogeneous types</a></span></dt> | |
58 | </dl></dd> | |
59 | </dl></div> | |
60 | <h4> | |
61 | <a name="fiber.when_any.h0"></a> | |
62 | <span><a name="fiber.when_any.overview"></a></span><a class="link" href="when_any.html#fiber.when_any.overview">Overview</a> | |
63 | </h4> | |
64 | <p> | |
65 | A bit of wisdom from the early days of computing still holds true today: prefer | |
66 | to model program state using the instruction pointer rather than with Boolean | |
67 | flags. In other words, if the program must <span class="quote">“<span class="quote">do something</span>”</span> and | |
68 | then do something almost the same, but with minor changes... perhaps parts | |
69 | of that something should be broken out as smaller separate functions, rather | |
70 | than introducing flags to alter the internal behavior of a monolithic function. | |
71 | </p> | |
72 | <p> | |
73 | To that we would add: prefer to describe control flow using C++ native constructs | |
74 | such as function calls, <code class="computeroutput"><span class="keyword">if</span></code>, <code class="computeroutput"><span class="keyword">while</span></code>, <code class="computeroutput"><span class="keyword">for</span></code>, | |
75 | <code class="computeroutput"><span class="keyword">do</span></code> et al. rather than as chains | |
76 | of callbacks. | |
77 | </p> | |
78 | <p> | |
79 | One of the great strengths of <span class="bold"><strong>Boost.Fiber</strong></span> | |
80 | is the flexibility it confers on the coder to restructure an application from | |
81 | chains of callbacks to straightforward C++ statement sequence, even when code | |
82 | in that fiber is in fact interleaved with code running in other fibers. | |
83 | </p> | |
84 | <p> | |
85 | There has been much recent discussion about the benefits of when_any and when_all | |
86 | functionality. When dealing with asynchronous and possibly unreliable services, | |
87 | these are valuable idioms. But of course when_any and when_all are closely | |
88 | tied to the use of chains of callbacks. | |
89 | </p> | |
90 | <p> | |
91 | This section presents recipes for achieving the same ends, in the context of | |
92 | a fiber that wants to <span class="quote">“<span class="quote">do something</span>”</span> when one or more other independent | |
93 | activities have completed. Accordingly, these are <code class="computeroutput"><span class="identifier">wait_something</span><span class="special">()</span></code> functions rather than <code class="computeroutput"><span class="identifier">when_something</span><span class="special">()</span></code> functions. The expectation is that the calling | |
94 | fiber asks to launch those independent activities, then waits for them, then | |
95 | sequentially proceeds with whatever processing depends on those results. | |
96 | </p> | |
97 | <p> | |
98 | The function names shown (e.g. <a class="link" href="when_any/when_any/when_any__simple_completion.html#wait_first_simple"><code class="computeroutput"><span class="identifier">wait_first_simple</span><span class="special">()</span></code></a>) | |
99 | are for illustrative purposes only, because all these functions have been bundled | |
100 | into a single source file. Presumably, if (say) <a class="link" href="when_any/when_any/when_any__produce_first_success.html#wait_first_success"><code class="computeroutput"><span class="identifier">wait_first_success</span><span class="special">()</span></code></a> | |
101 | best suits your application needs, you could introduce that variant with the | |
102 | name <code class="computeroutput"><span class="identifier">wait_any</span><span class="special">()</span></code>. | |
103 | </p> | |
104 | <div class="note"><table border="0" summary="Note"> | |
105 | <tr> | |
106 | <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> | |
107 | <th align="left">Note</th> | |
108 | </tr> | |
109 | <tr><td align="left" valign="top"><p> | |
110 | The functions presented in this section accept variadic argument lists of | |
111 | task functions. Corresponding <code class="computeroutput"><span class="identifier">wait_something</span><span class="special">()</span></code> functions accepting a container of task | |
112 | functions are left as an exercise for the interested reader. Those should | |
113 | actually be simpler. Most of the complexity would arise from overloading | |
114 | the same name for both purposes. | |
115 | </p></td></tr> | |
116 | </table></div> | |
117 | <p> | |
118 | All the source code for this section is found in <a href="../../../examples/wait_stuff.cpp" target="_top">wait_stuff.cpp</a>. | |
119 | </p> | |
120 | <h4> | |
121 | <a name="fiber.when_any.h1"></a> | |
122 | <span><a name="fiber.when_any.example_task_function"></a></span><a class="link" href="when_any.html#fiber.when_any.example_task_function">Example | |
123 | Task Function</a> | |
124 | </h4> | |
125 | <p> | |
126 | <a name="wait_sleeper"></a>We found it convenient to model an asynchronous | |
127 | task using this function: | |
128 | </p> | |
129 | <p> | |
130 | </p> | |
131 | <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">></span> | |
132 | <span class="identifier">T</span> <span class="identifier">sleeper_impl</span><span class="special">(</span> <span class="identifier">T</span> <span class="identifier">item</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">ms</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">thrw</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">)</span> <span class="special">{</span> | |
133 | <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">descb</span><span class="special">,</span> <span class="identifier">funcb</span><span class="special">;</span> | |
134 | <span class="identifier">descb</span> <span class="special"><<</span> <span class="identifier">item</span><span class="special">;</span> | |
135 | <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">desc</span><span class="special">(</span> <span class="identifier">descb</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">);</span> | |
136 | <span class="identifier">funcb</span> <span class="special"><<</span> <span class="string">" sleeper("</span> <span class="special"><<</span> <span class="identifier">item</span> <span class="special"><<</span> <span class="string">")"</span><span class="special">;</span> | |
137 | <span class="identifier">Verbose</span> <span class="identifier">v</span><span class="special">(</span> <span class="identifier">funcb</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">);</span> | |
138 | ||
139 | <span class="identifier">boost</span><span class="special">::</span><span class="identifier">this_fiber</span><span class="special">::</span><span class="identifier">sleep_for</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">milliseconds</span><span class="special">(</span> <span class="identifier">ms</span><span class="special">)</span> <span class="special">);</span> | |
140 | <span class="keyword">if</span> <span class="special">(</span> <span class="identifier">thrw</span><span class="special">)</span> <span class="special">{</span> | |
141 | <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">(</span> <span class="identifier">desc</span><span class="special">);</span> | |
142 | <span class="special">}</span> | |
143 | <span class="keyword">return</span> <span class="identifier">item</span><span class="special">;</span> | |
144 | <span class="special">}</span> | |
145 | </pre> | |
146 | <p> | |
147 | </p> | |
148 | <p> | |
149 | with type-specific <code class="computeroutput"><span class="identifier">sleeper</span><span class="special">()</span></code> <span class="quote">“<span class="quote">front ends</span>”</span> for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>, | |
150 | <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">int</span></code>. | |
151 | </p> | |
152 | <p> | |
153 | <code class="computeroutput"><span class="identifier">Verbose</span></code> simply prints a message | |
154 | to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code> on construction and destruction. | |
155 | </p> | |
156 | <p> | |
157 | Basically: | |
158 | </p> | |
159 | <div class="orderedlist"><ol class="orderedlist" type="1"> | |
160 | <li class="listitem"> | |
161 | <code class="computeroutput"><span class="identifier">sleeper</span><span class="special">()</span></code> | |
162 | prints a start message; | |
163 | </li> | |
164 | <li class="listitem"> | |
165 | sleeps for the specified number of milliseconds; | |
166 | </li> | |
167 | <li class="listitem"> | |
168 | if <code class="computeroutput"><span class="identifier">thrw</span></code> is passed as <code class="computeroutput"><span class="keyword">true</span></code>, throws a string description of the | |
169 | passed <code class="computeroutput"><span class="identifier">item</span></code>; | |
170 | </li> | |
171 | <li class="listitem"> | |
172 | else returns the passed <code class="computeroutput"><span class="identifier">item</span></code>. | |
173 | </li> | |
174 | <li class="listitem"> | |
175 | On the way out, <code class="computeroutput"><span class="identifier">sleeper</span><span class="special">()</span></code> produces a stop message. | |
176 | </li> | |
177 | </ol></div> | |
178 | <p> | |
179 | This function will feature in the example calls to the various functions presented | |
180 | below. | |
181 | </p> | |
182 | </div> | |
183 | <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> | |
184 | <td align="left"></td> | |
185 | <td align="right"><div class="copyright-footer">Copyright © 2013 Oliver Kowalke<p> | |
186 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
187 | file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) | |
188 | </p> | |
189 | </div></td> | |
190 | </tr></table> | |
191 | <hr> | |
192 | <div class="spirit-nav"> | |
193 | <a accesskey="p" href="nonblocking.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="when_any/when_any.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> | |
194 | </div> | |
195 | </body> | |
196 | </html> |