1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Overview</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="../callbacks.html" title="Integrating Fibers with Asynchronous Callbacks"> 9<link rel="prev" href="../callbacks.html" title="Integrating Fibers with Asynchronous Callbacks"> 10<link rel="next" href="return_errorcode.html" title="Return Errorcode"> 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.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../callbacks.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="return_errorcode.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="fiber.callbacks.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a> 28</h3></div></div></div> 29<p> 30 One of the primary benefits of <span class="bold"><strong>Boost.Fiber</strong></span> 31 is the ability to use asynchronous operations for efficiency, while at the 32 same time structuring the calling code <span class="emphasis"><em>as if</em></span> the operations 33 were synchronous. Asynchronous operations provide completion notification 34 in a variety of ways, but most involve a callback function of some kind. 35 This section discusses tactics for interfacing <span class="bold"><strong>Boost.Fiber</strong></span> 36 with an arbitrary async operation. 37 </p> 38<p> 39 For purposes of illustration, consider the following hypothetical API: 40 </p> 41<p> 42</p> 43<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">AsyncAPI</span> <span class="special">{</span> 44<span class="keyword">public</span><span class="special">:</span> 45 <span class="comment">// constructor acquires some resource that can be read and written</span> 46 <span class="identifier">AsyncAPI</span><span class="special">();</span> 47 48 <span class="comment">// callbacks accept an int error code; 0 == success</span> 49 <span class="keyword">typedef</span> <span class="keyword">int</span> <span class="identifier">errorcode</span><span class="special">;</span> 50 51 <span class="comment">// write callback only needs to indicate success or failure</span> 52 <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Fn</span> <span class="special">></span> 53 <span class="keyword">void</span> <span class="identifier">init_write</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">&</span> <span class="identifier">data</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">callback</span><span class="special">);</span> 54 55 <span class="comment">// read callback needs to accept both errorcode and data</span> 56 <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Fn</span> <span class="special">></span> 57 <span class="keyword">void</span> <span class="identifier">init_read</span><span class="special">(</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">callback</span><span class="special">);</span> 58 59 <span class="comment">// ... other operations ...</span> 60<span class="special">};</span> 61</pre> 62<p> 63 </p> 64<p> 65 The significant points about each of <code class="computeroutput"><span class="identifier">init_write</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">init_read</span><span class="special">()</span></code> are: 66 </p> 67<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 68<li class="listitem"> 69 The <code class="computeroutput"><span class="identifier">AsyncAPI</span></code> method only 70 initiates the operation. It returns immediately, while the requested 71 operation is still pending. 72 </li> 73<li class="listitem"> 74 The method accepts a callback. When the operation completes, the callback 75 is called with relevant parameters (error code, data if applicable). 76 </li> 77</ul></div> 78<p> 79 We would like to wrap these asynchronous methods in functions that appear 80 synchronous by blocking the calling fiber until the operation completes. 81 This lets us use the wrapper function’s return value to deliver relevant data. 82 </p> 83<div class="tip"><table border="0" summary="Tip"> 84<tr> 85<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> 86<th align="left">Tip</th> 87</tr> 88<tr><td align="left" valign="top"><p> 89 <a class="link" href="../synchronization/futures/promise.html#class_promise"><code class="computeroutput">promise<></code></a> and <a class="link" href="../synchronization/futures/future.html#class_future"><code class="computeroutput">future<></code></a> are your friends 90 here. 91 </p></td></tr> 92</table></div> 93</div> 94<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 95<td align="left"></td> 96<td align="right"><div class="copyright-footer">Copyright © 2013 Oliver Kowalke<p> 97 Distributed under the Boost Software License, Version 1.0. (See accompanying 98 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>) 99 </p> 100</div></td> 101</tr></table> 102<hr> 103<div class="spirit-nav"> 104<a accesskey="p" href="../callbacks.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../callbacks.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="return_errorcode.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 105</div> 106</body> 107</html> 108
