ceph/src/boost/libs/fiber/doc/html/fiber/synchronization/futures.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Futures</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="../synchronization.html" title="Synchronization">
   9 <link rel="prev" href="channels.html" title="Channels">
  10 <link rel="next" href="futures/future.html" title="Future">
  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="channels.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../synchronization.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="futures/future.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.synchronization.futures"></a><a class="link" href="futures.html" title="Futures">Futures</a>
  28 </h3></div></div></div>
  29 <div class="toc"><dl>
  30 <dt><span class="section"><a href="futures/future.html">Future</a></span></dt>
  31 <dt><span class="section"><a href="futures/promise.html">Template
  32         <code class="computeroutput"><span class="identifier">promise</span><span class="special">&lt;&gt;</span></code></a></span></dt>
  33 <dt><span class="section"><a href="futures/packaged_task.html">Template
  34         <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special">&lt;&gt;</span></code></a></span></dt>
  35 </dl></div>
  36 <h5>
  37 <a name="fiber.synchronization.futures.h0"></a>
  38         <span><a name="fiber.synchronization.futures.overview"></a></span><a class="link" href="futures.html#fiber.synchronization.futures.overview">Overview</a>
  39       </h5>
  40 <p>
  41         The futures library provides a means of handling asynchronous future values,
  42         whether those values are generated by another fiber, or on a single fiber
  43         in response to external stimuli, or on-demand.
  44       </p>
  45 <p>
  46         This is done through the provision of four class templates: <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> and
  47         <a class="link" href="futures/future.html#class_shared_future"><code class="computeroutput">shared_future&lt;&gt;</code></a> which are used to retrieve the asynchronous
  48         results, and <a class="link" href="futures/promise.html#class_promise"><code class="computeroutput">promise&lt;&gt;</code></a> and <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> which
  49         are used to generate the asynchronous results.
  50       </p>
  51 <p>
  52         An instance of <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> holds the one and only reference
  53         to a result. Ownership can be transferred between instances using the move
  54         constructor or move-assignment operator, but at most one instance holds a
  55         reference to a given asynchronous result. When the result is ready, it is
  56         returned from <a class="link" href="futures/future.html#future_get"><code class="computeroutput">future::get()</code></a> by rvalue-reference to allow the result
  57         to be moved or copied as appropriate for the type.
  58       </p>
  59 <p>
  60         On the other hand, many instances of <a class="link" href="futures/future.html#class_shared_future"><code class="computeroutput">shared_future&lt;&gt;</code></a> may
  61         reference the same result. Instances can be freely copied and assigned, and
  62         <a class="link" href="futures/future.html#shared_future_get"><code class="computeroutput">shared_future::get()</code></a>
  63 returns a <code class="computeroutput"><span class="keyword">const</span></code>
  64         reference so that multiple calls to <a class="link" href="futures/future.html#shared_future_get"><code class="computeroutput">shared_future::get()</code></a>
  65 are
  66         safe. You can move an instance of <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> into an instance
  67         of <a class="link" href="futures/future.html#class_shared_future"><code class="computeroutput">shared_future&lt;&gt;</code></a>, thus transferring ownership
  68         of the associated asynchronous result, but not vice-versa.
  69       </p>
  70 <p>
  71         <a class="link" href="futures/future.html#fibers_async"><code class="computeroutput">fibers::async()</code></a> is a simple way of running asynchronous tasks.
  72         A call to <code class="computeroutput"><span class="identifier">async</span><span class="special">()</span></code>
  73         spawns a fiber and returns a <a class="link" href="futures/future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> that will deliver
  74         the result of the fiber function.
  75       </p>
  76 <h5>
  77 <a name="fiber.synchronization.futures.h1"></a>
  78         <span><a name="fiber.synchronization.futures.creating_asynchronous_values"></a></span><a class="link" href="futures.html#fiber.synchronization.futures.creating_asynchronous_values">Creating
  79         asynchronous values</a>
  80       </h5>
  81 <p>
  82         You can set the value in a future with either a <a class="link" href="futures/promise.html#class_promise"><code class="computeroutput">promise&lt;&gt;</code></a> or
  83         a <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a>. A <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> is
  84         a callable object with <code class="computeroutput"><span class="keyword">void</span></code>
  85         return that wraps a function or callable object returning the specified type.
  86         When the <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> is invoked, it invokes the
  87         contained function in turn, and populates a future with the contained function's
  88         return value. This is an answer to the perennial question: <span class="quote">&#8220;<span class="quote">How do
  89         I return a value from a fiber?</span>&#8221;</span> Package the function you wish to run
  90         as a <a class="link" href="futures/packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task&lt;&gt;</code></a> and pass the packaged task to
  91         the fiber constructor. The future retrieved from the packaged task can then
  92         be used to obtain the return value. If the function throws an exception,
  93         that is stored in the future in place of the return value.
  94       </p>
  95 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">calculate_the_answer_to_life_the_universe_and_everything</span><span class="special">()</span> <span class="special">{</span>
  96     <span class="keyword">return</span> <span class="number">42</span><span class="special">;</span>
  97 <span class="special">}</span>
  98
  99 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">packaged_task</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">()&gt;</span> <span class="identifier">pt</span><span class="special">(</span><span class="identifier">calculate_the_answer_to_life_the_universe_and_everything</span><span class="special">);</span>
 100 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">future</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">fi</span><span class="special">=</span><span class="identifier">pt</span><span class="special">.</span><span class="identifier">get_future</span><span class="special">();</span>
 101 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">fiber</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">pt</span><span class="special">)).</span><span class="identifier">detach</span><span class="special">();</span> <span class="comment">// launch task on a fiber</span>
 102
 103 <span class="identifier">fi</span><span class="special">.</span><span class="identifier">wait</span><span class="special">();</span> <span class="comment">// wait for it to finish</span>
 104
 105 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">is_ready</span><span class="special">());</span>
 106 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_value</span><span class="special">());</span>
 107 <span class="identifier">assert</span><span class="special">(!</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_exception</span><span class="special">());</span>
 108 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">get</span><span class="special">()==</span><span class="number">42</span><span class="special">);</span>
 109 </pre>
 110 <p>
 111         A <a class="link" href="futures/promise.html#class_promise"><code class="computeroutput">promise&lt;&gt;</code></a> is a bit more low level: it just provides explicit
 112         functions to store a value or an exception in the associated future. A promise
 113         can therefore be used where the value might come from more than one possible
 114         source.
 115       </p>
 116 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">promise</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">pi</span><span class="special">;</span>
 117 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">fibers</span><span class="special">::</span><span class="identifier">future</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">fi</span><span class="special">;</span>
 118 <span class="identifier">fi</span><span class="special">=</span><span class="identifier">pi</span><span class="special">.</span><span class="identifier">get_future</span><span class="special">();</span>
 119
 120 <span class="identifier">pi</span><span class="special">.</span><span class="identifier">set_value</span><span class="special">(</span><span class="number">42</span><span class="special">);</span>
 121
 122 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">is_ready</span><span class="special">());</span>
 123 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_value</span><span class="special">());</span>
 124 <span class="identifier">assert</span><span class="special">(!</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">has_exception</span><span class="special">());</span>
 125 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">fi</span><span class="special">.</span><span class="identifier">get</span><span class="special">()==</span><span class="number">42</span><span class="special">);</span>
 126 </pre>
 127 </div>
 128 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 129 <td align="left"></td>
 130 <td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
 131         Distributed under the Boost Software License, Version 1.0. (See accompanying
 132         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>)
 133       </p>
 134 </div></td>
 135 </tr></table>
 136 <hr>
 137 <div class="spirit-nav">
 138 <a accesskey="p" href="channels.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../synchronization.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="futures/future.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 139 </div>
 140 </body>
 141 </html>