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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Integrating Fibers with Nonblocking I/O</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="callbacks/then_there_s____boost_asio__.html" title="Then There&#8217;s Boost.Asio">
  10 <link rel="next" href="when_any.html" title="when_any / when_all functionality">
  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="callbacks/then_there_s____boost_asio__.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.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.nonblocking"></a><a name="nonblocking"></a><a class="link" href="nonblocking.html" title="Integrating Fibers with Nonblocking I/O">Integrating
  28     Fibers with Nonblocking I/O</a>
  29 </h2></div></div></div>
  30 <h4>
  31 <a name="fiber.nonblocking.h0"></a>
  32       <span><a name="fiber.nonblocking.overview"></a></span><a class="link" href="nonblocking.html#fiber.nonblocking.overview">Overview</a>
  33     </h4>
  34 <p>
  35       <span class="emphasis"><em>Nonblocking</em></span> I/O is distinct from <span class="emphasis"><em>asynchronous</em></span>
  36       I/O. A true async I/O operation promises to initiate the operation and notify
  37       the caller on completion, usually via some sort of callback (as described in
  38       <a class="link" href="callbacks.html#callbacks">Integrating Fibers with Asynchronous Callbacks</a>).
  39     </p>
  40 <p>
  41       In contrast, a nonblocking I/O operation refuses to start at all if it would
  42       be necessary to block, returning an error code such as <a href="http://man7.org/linux/man-pages/man3/errno.3.html" target="_top"><code class="computeroutput"><span class="identifier">EWOULDBLOCK</span></code></a>. The operation is performed
  43       only when it can complete immediately. In effect, the caller must repeatedly
  44       retry the operation until it stops returning <code class="computeroutput"><span class="identifier">EWOULDBLOCK</span></code>.
  45     </p>
  46 <p>
  47       In a classic event-driven program, it can be something of a headache to use
  48       nonblocking I/O. At the point where the nonblocking I/O is attempted, a return
  49       value of <code class="computeroutput"><span class="identifier">EWOULDBLOCK</span></code> requires
  50       the caller to pass control back to the main event loop, arranging to retry
  51       again on the next iteration.
  52     </p>
  53 <p>
  54       Worse, a nonblocking I/O operation might <span class="emphasis"><em>partially</em></span> succeed.
  55       That means that the relevant business logic must continue receiving control
  56       on every main loop iteration until all required data have been processed: a
  57       doubly-nested loop, implemented as a callback-driven state machine.
  58     </p>
  59 <p>
  60       <span class="bold"><strong>Boost.Fiber</strong></span> can simplify this problem immensely.
  61       Once you have integrated with the application's main loop as described in
  62       <a class="link" href="integration.html#integration">Sharing a Thread with Another Main Loop</a>,
  63       waiting for the next main-loop iteration is as simple as calling <a class="link" href="fiber_mgmt/this_fiber.html#this_fiber_yield"><code class="computeroutput">this_fiber::yield()</code></a>.
  64     </p>
  65 <h4>
  66 <a name="fiber.nonblocking.h1"></a>
  67       <span><a name="fiber.nonblocking.example_nonblocking_api"></a></span><a class="link" href="nonblocking.html#fiber.nonblocking.example_nonblocking_api">Example
  68       Nonblocking API</a>
  69     </h4>
  70 <p>
  71       For purposes of illustration, consider this API:
  72     </p>
  73 <p>
  74 </p>
  75 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">NonblockingAPI</span> <span class="special">{</span>
  76 <span class="keyword">public</span><span class="special">:</span>
  77     <span class="identifier">NonblockingAPI</span><span class="special">();</span>
  78
  79     <span class="comment">// nonblocking operation: may return EWOULDBLOCK</span>
  80     <span class="keyword">int</span> <span class="identifier">read</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&amp;</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">desired</span><span class="special">);</span>
  81
  82     <span class="special">...</span>
  83 <span class="special">};</span>
  84 </pre>
  85 <p>
  86     </p>
  87 <h4>
  88 <a name="fiber.nonblocking.h2"></a>
  89       <span><a name="fiber.nonblocking.polling_for_completion"></a></span><a class="link" href="nonblocking.html#fiber.nonblocking.polling_for_completion">Polling
  90       for Completion</a>
  91     </h4>
  92 <p>
  93       We can build a low-level wrapper around <code class="computeroutput"><span class="identifier">NonblockingAPI</span><span class="special">::</span><span class="identifier">read</span><span class="special">()</span></code>
  94       that shields its caller from ever having to deal with <code class="computeroutput"><span class="identifier">EWOULDBLOCK</span></code>:
  95     </p>
  96 <p>
  97 </p>
  98 <pre class="programlisting"><span class="comment">// guaranteed not to return EWOULDBLOCK</span>
  99 <span class="keyword">int</span> <span class="identifier">read_chunk</span><span class="special">(</span> <span class="identifier">NonblockingAPI</span> <span class="special">&amp;</span> <span class="identifier">api</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&amp;</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">desired</span><span class="special">)</span> <span class="special">{</span>
 100     <span class="keyword">int</span> <span class="identifier">error</span><span class="special">;</span>
 101     <span class="keyword">while</span> <span class="special">(</span> <span class="identifier">EWOULDBLOCK</span> <span class="special">==</span> <span class="special">(</span> <span class="identifier">error</span> <span class="special">=</span> <span class="identifier">api</span><span class="special">.</span><span class="identifier">read</span><span class="special">(</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">desired</span><span class="special">)</span> <span class="special">)</span> <span class="special">)</span> <span class="special">{</span>
 102         <span class="comment">// not ready yet -- try again on the next iteration of the</span>
 103         <span class="comment">// application's main loop</span>
 104         <span class="identifier">boost</span><span class="special">::</span><span class="identifier">this_fiber</span><span class="special">::</span><span class="identifier">yield</span><span class="special">();</span>
 105     <span class="special">}</span>
 106     <span class="keyword">return</span> <span class="identifier">error</span><span class="special">;</span>
 107 <span class="special">}</span>
 108 </pre>
 109 <p>
 110     </p>
 111 <h4>
 112 <a name="fiber.nonblocking.h3"></a>
 113       <span><a name="fiber.nonblocking.filling_all_desired_data"></a></span><a class="link" href="nonblocking.html#fiber.nonblocking.filling_all_desired_data">Filling
 114       All Desired Data</a>
 115     </h4>
 116 <p>
 117       Given <code class="computeroutput"><span class="identifier">read_chunk</span><span class="special">()</span></code>,
 118       we can straightforwardly iterate until we have all desired data:
 119     </p>
 120 <p>
 121 </p>
 122 <pre class="programlisting"><span class="comment">// keep reading until desired length, EOF or error</span>
 123 <span class="comment">// may return both partial data and nonzero error</span>
 124 <span class="keyword">int</span> <span class="identifier">read_desired</span><span class="special">(</span> <span class="identifier">NonblockingAPI</span> <span class="special">&amp;</span> <span class="identifier">api</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&amp;</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">desired</span><span class="special">)</span> <span class="special">{</span>
 125     <span class="comment">// we're going to accumulate results into 'data'</span>
 126     <span class="identifier">data</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span>
 127     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">chunk</span><span class="special">;</span>
 128     <span class="keyword">int</span> <span class="identifier">error</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 129     <span class="keyword">while</span> <span class="special">(</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">length</span><span class="special">()</span> <span class="special">&lt;</span> <span class="identifier">desired</span> <span class="special">&amp;&amp;</span>
 130            <span class="special">(</span> <span class="identifier">error</span> <span class="special">=</span> <span class="identifier">read_chunk</span><span class="special">(</span> <span class="identifier">api</span><span class="special">,</span> <span class="identifier">chunk</span><span class="special">,</span> <span class="identifier">desired</span> <span class="special">-</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">length</span><span class="special">()</span> <span class="special">)</span> <span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span> <span class="special">{</span>
 131         <span class="identifier">data</span><span class="special">.</span><span class="identifier">append</span><span class="special">(</span> <span class="identifier">chunk</span><span class="special">);</span>
 132     <span class="special">}</span>
 133     <span class="keyword">return</span> <span class="identifier">error</span><span class="special">;</span>
 134 <span class="special">}</span>
 135 </pre>
 136 <p>
 137     </p>
 138 <p>
 139       (Of <span class="emphasis"><em>course</em></span> there are more efficient ways to accumulate
 140       string data. That's not the point of this example.)
 141     </p>
 142 <h4>
 143 <a name="fiber.nonblocking.h4"></a>
 144       <span><a name="fiber.nonblocking.wrapping_it_up"></a></span><a class="link" href="nonblocking.html#fiber.nonblocking.wrapping_it_up">Wrapping
 145       it Up</a>
 146     </h4>
 147 <p>
 148       Finally, we can define a relevant exception:
 149     </p>
 150 <p>
 151 </p>
 152 <pre class="programlisting"><span class="comment">// exception class augmented with both partially-read data and errorcode</span>
 153 <span class="keyword">class</span> <span class="identifier">IncompleteRead</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span> <span class="special">{</span>
 154 <span class="keyword">public</span><span class="special">:</span>
 155     <span class="identifier">IncompleteRead</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">what</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">partial</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">ec</span><span class="special">)</span> <span class="special">:</span>
 156         <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">(</span> <span class="identifier">what</span><span class="special">),</span>
 157         <span class="identifier">partial_</span><span class="special">(</span> <span class="identifier">partial</span><span class="special">),</span>
 158         <span class="identifier">ec_</span><span class="special">(</span> <span class="identifier">ec</span><span class="special">)</span> <span class="special">{</span>
 159     <span class="special">}</span>
 160
 161     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">get_partial</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span>
 162         <span class="keyword">return</span> <span class="identifier">partial_</span><span class="special">;</span>
 163     <span class="special">}</span>
 164
 165     <span class="keyword">int</span> <span class="identifier">get_errorcode</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span>
 166         <span class="keyword">return</span> <span class="identifier">ec_</span><span class="special">;</span>
 167     <span class="special">}</span>
 168
 169 <span class="keyword">private</span><span class="special">:</span>
 170     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">partial_</span><span class="special">;</span>
 171     <span class="keyword">int</span>         <span class="identifier">ec_</span><span class="special">;</span>
 172 <span class="special">};</span>
 173 </pre>
 174 <p>
 175     </p>
 176 <p>
 177       and write a simple <code class="computeroutput"><span class="identifier">read</span><span class="special">()</span></code>
 178       function that either returns all desired data or throws <code class="computeroutput"><span class="identifier">IncompleteRead</span></code>:
 179     </p>
 180 <p>
 181 </p>
 182 <pre class="programlisting"><span class="comment">// read all desired data or throw IncompleteRead</span>
 183 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">read</span><span class="special">(</span> <span class="identifier">NonblockingAPI</span> <span class="special">&amp;</span> <span class="identifier">api</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">desired</span><span class="special">)</span> <span class="special">{</span>
 184     <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">data</span><span class="special">;</span>
 185     <span class="keyword">int</span> <span class="identifier">ec</span><span class="special">(</span> <span class="identifier">read_desired</span><span class="special">(</span> <span class="identifier">api</span><span class="special">,</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">desired</span><span class="special">)</span> <span class="special">);</span>
 186
 187     <span class="comment">// for present purposes, EOF isn't a failure</span>
 188     <span class="keyword">if</span> <span class="special">(</span> <span class="number">0</span> <span class="special">==</span> <span class="identifier">ec</span> <span class="special">||</span> <span class="identifier">EOF</span> <span class="special">==</span> <span class="identifier">ec</span><span class="special">)</span> <span class="special">{</span>
 189         <span class="keyword">return</span> <span class="identifier">data</span><span class="special">;</span>
 190     <span class="special">}</span>
 191
 192     <span class="comment">// oh oh, partial read</span>
 193     <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostringstream</span> <span class="identifier">msg</span><span class="special">;</span>
 194     <span class="identifier">msg</span> <span class="special">&lt;&lt;</span> <span class="string">"NonblockingAPI::read() error "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ec</span> <span class="special">&lt;&lt;</span> <span class="string">" after "</span>
 195         <span class="special">&lt;&lt;</span> <span class="identifier">data</span><span class="special">.</span><span class="identifier">length</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="string">" of "</span> <span class="special">&lt;&lt;</span> <span class="identifier">desired</span> <span class="special">&lt;&lt;</span> <span class="string">" characters"</span><span class="special">;</span>
 196     <span class="keyword">throw</span> <span class="identifier">IncompleteRead</span><span class="special">(</span> <span class="identifier">msg</span><span class="special">.</span><span class="identifier">str</span><span class="special">(),</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span>
 197 <span class="special">}</span>
 198 </pre>
 199 <p>
 200     </p>
 201 <p>
 202       Once we can transparently wait for the next main-loop iteration using <a class="link" href="fiber_mgmt/this_fiber.html#this_fiber_yield"><code class="computeroutput">this_fiber::yield()</code></a>,
 203       ordinary encapsulation Just Works.
 204     </p>
 205 <p>
 206       The source code above is found in <a href="../../../examples/adapt_nonblocking.cpp" target="_top">adapt_nonblocking.cpp</a>.
 207     </p>
 208 </div>
 209 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 210 <td align="left"></td>
 211 <td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
 212         Distributed under the Boost Software License, Version 1.0. (See accompanying
 213         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>)
 214       </p>
 215 </div></td>
 216 </tr></table>
 217 <hr>
 218 <div class="spirit-nav">
 219 <a accesskey="p" href="callbacks/then_there_s____boost_asio__.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.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 220 </div>
 221 </body>
 222 </html>