1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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.79.1"> 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 class="toc"> 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 class="phrase"><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 class="phrase"><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> 197
