ceph/src/boost/libs/fiber/doc/html/fiber/when_any.html

   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&#160;1.&#160;Fiber">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;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">&#8220;<span class="quote">do something</span>&#8221;</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">&#8220;<span class="quote">do something</span>&#8221;</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">&lt;</span> <span class="keyword">typename</span> <span class="identifier">T</span> <span class="special">&gt;</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">&lt;&lt;</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">&lt;&lt;</span> <span class="string">"  sleeper("</span> <span class="special">&lt;&lt;</span> <span class="identifier">item</span> <span class="special">&lt;&lt;</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">&#8220;<span class="quote">front ends</span>&#8221;</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 &#169; 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>