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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Template promise&lt;&gt;</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="../futures.html" title="Futures">
   9 <link rel="prev" href="future.html" title="Future">
  10 <link rel="next" href="packaged_task.html" title="Template packaged_task&lt;&gt;">
  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="future.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../futures.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="packaged_task.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="fiber.synchronization.futures.promise"></a><a name="class_promise"></a><a class="link" href="promise.html" title="Template promise&lt;&gt;">Template
  28         <code class="computeroutput"><span class="identifier">promise</span><span class="special">&lt;&gt;</span></code></a>
  29 </h4></div></div></div>
  30 <p>
  31           A <a class="link" href="promise.html#class_promise"><code class="computeroutput">promise&lt;&gt;</code></a> provides a mechanism to store a value (or
  32           exception) that can later be retrieved from the corresponding <a class="link" href="future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> object.
  33           <code class="computeroutput"><span class="identifier">promise</span><span class="special">&lt;&gt;</span></code>
  34           and <code class="computeroutput"><span class="identifier">future</span><span class="special">&lt;&gt;</span></code>
  35           communicate via their underlying <a class="link" href="future.html#shared_state">shared state</a>.
  36         </p>
  37 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fiber</span><span class="special">/</span><span class="identifier">future</span><span class="special">/</span><span class="identifier">promise</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  38
  39 <span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
  40 <span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span>
  41
  42 <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">R</span> <span class="special">&gt;</span>
  43 <span class="keyword">class</span> <span class="identifier">promise</span> <span class="special">{</span>
  44 <span class="keyword">public</span><span class="special">:</span>
  45     <span class="identifier">promise</span><span class="special">();</span>
  46
  47     <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <a href="http://en.cppreference.com/w/cpp/concept/Allocator" target="_top"><code class="computeroutput"><span class="identifier">Allocator</span></code></a> <span class="special">&gt;</span>
  48     <span class="identifier">promise</span><span class="special">(</span> <a href="http://en.cppreference.com/w/cpp/memory/allocator_arg_t" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator_arg_t</span></code></a><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">);</span>
  49
  50     <span class="identifier">promise</span><span class="special">(</span> <span class="identifier">promise</span> <span class="special">&amp;&amp;)</span> <span class="keyword">noexcept</span><span class="special">;</span>
  51
  52     <span class="identifier">promise</span> <span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">=(</span> <span class="identifier">promise</span> <span class="special">&amp;&amp;)</span> <span class="keyword">noexcept</span><span class="special">;</span>
  53
  54     <span class="identifier">promise</span><span class="special">(</span> <span class="identifier">promise</span> <span class="keyword">const</span><span class="special">&amp;)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span>
  55
  56     <span class="identifier">promise</span> <span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">=(</span> <span class="identifier">promise</span> <span class="keyword">const</span><span class="special">&amp;)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span>
  57
  58     <span class="special">~</span><span class="identifier">promise</span><span class="special">();</span>
  59
  60     <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">promise</span> <span class="special">&amp;)</span> <span class="keyword">noexcept</span><span class="special">;</span>
  61
  62     <span class="identifier">future</span><span class="special">&lt;</span> <span class="identifier">R</span> <span class="special">&gt;</span> <span class="identifier">get_future</span><span class="special">();</span>
  63
  64     <span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">(</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&amp;);</span>  <span class="comment">// member only of generic promise template</span>
  65     <span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">(</span> <span class="identifier">R</span> <span class="special">&amp;&amp;);</span>      <span class="comment">// member only of generic promise template</span>
  66     <span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">(</span> <span class="identifier">R</span> <span class="special">&amp;);</span>       <span class="comment">// member only of promise&lt; R &amp; &gt; template</span>
  67     <span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">();</span>           <span class="comment">// member only of promise&lt; void &gt; template</span>
  68
  69     <span class="keyword">void</span> <span class="identifier">set_exception</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception_ptr</span> <span class="identifier">p</span><span class="special">);</span>
  70 <span class="special">};</span>
  71
  72 <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">R</span> <span class="special">&gt;</span>
  73 <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">promise</span><span class="special">&lt;</span> <span class="identifier">R</span> <span class="special">&gt;</span> <span class="special">&amp;,</span> <span class="identifier">promise</span><span class="special">&lt;</span> <span class="identifier">R</span> <span class="special">&gt;</span> <span class="special">&amp;)</span> <span class="keyword">noexcept</span><span class="special">;</span>
  74
  75 <span class="special">}</span>
  76 </pre>
  77 <h6>
  78 <a name="fiber.synchronization.futures.promise.h0"></a>
  79           <span><a name="fiber.synchronization.futures.promise.default_constructor"></a></span><a class="link" href="promise.html#fiber.synchronization.futures.promise.default_constructor">Default
  80           constructor</a>
  81         </h6>
  82 <pre class="programlisting"><span class="identifier">promise</span><span class="special">();</span>
  83 </pre>
  84 <div class="variablelist">
  85 <p class="title"><b></b></p>
  86 <dl>
  87 <dt><span class="term">Effects:</span></dt>
  88 <dd><p>
  89                 Creates a promise with an empty <a class="link" href="future.html#shared_state">shared
  90                 state</a>.
  91               </p></dd>
  92 <dt><span class="term">Throws:</span></dt>
  93 <dd><p>
  94                 Exceptions caused by memory allocation.
  95               </p></dd>
  96 </dl>
  97 </div>
  98 <h6>
  99 <a name="fiber.synchronization.futures.promise.h1"></a>
 100           <span><a name="fiber.synchronization.futures.promise.constructor"></a></span><a class="link" href="promise.html#fiber.synchronization.futures.promise.constructor">Constructor</a>
 101         </h6>
 102 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <a href="http://en.cppreference.com/w/cpp/concept/Allocator" target="_top"><code class="computeroutput"><span class="identifier">Allocator</span></code></a> <span class="special">&gt;</span>
 103 <span class="identifier">promise</span><span class="special">(</span> <a href="http://en.cppreference.com/w/cpp/memory/allocator_arg_t" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator_arg_t</span></code></a><span class="special">,</span> <span class="identifier">Allocator</span> <span class="identifier">alloc</span><span class="special">);</span>
 104 </pre>
 105 <div class="variablelist">
 106 <p class="title"><b></b></p>
 107 <dl>
 108 <dt><span class="term">Effects:</span></dt>
 109 <dd><p>
 110                 Creates a promise with an empty <a class="link" href="future.html#shared_state">shared
 111                 state</a> by using <code class="computeroutput"><span class="identifier">alloc</span></code>.
 112               </p></dd>
 113 <dt><span class="term">Throws:</span></dt>
 114 <dd><p>
 115                 Exceptions caused by memory allocation.
 116               </p></dd>
 117 <dt><span class="term">See also:</span></dt>
 118 <dd><p>
 119                 <a href="http://en.cppreference.com/w/cpp/memory/allocator_arg_t" target="_top"><code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator_arg_t</span></code></a>
 120               </p></dd>
 121 </dl>
 122 </div>
 123 <h6>
 124 <a name="fiber.synchronization.futures.promise.h2"></a>
 125           <span><a name="fiber.synchronization.futures.promise.move_constructor"></a></span><a class="link" href="promise.html#fiber.synchronization.futures.promise.move_constructor">Move constructor</a>
 126         </h6>
 127 <pre class="programlisting"><span class="identifier">promise</span><span class="special">(</span> <span class="identifier">promise</span> <span class="special">&amp;&amp;</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
 128 </pre>
 129 <div class="variablelist">
 130 <p class="title"><b></b></p>
 131 <dl>
 132 <dt><span class="term">Effects:</span></dt>
 133 <dd><p>
 134                 Creates a promise by moving the <a class="link" href="future.html#shared_state">shared
 135                 state</a> from <code class="computeroutput"><span class="identifier">other</span></code>.
 136               </p></dd>
 137 <dt><span class="term">Postcondition:</span></dt>
 138 <dd><p>
 139                 <code class="computeroutput"><span class="identifier">other</span></code> contains no
 140                 valid shared state.
 141               </p></dd>
 142 <dt><span class="term">Throws:</span></dt>
 143 <dd><p>
 144                 Nothing.
 145               </p></dd>
 146 </dl>
 147 </div>
 148 <h6>
 149 <a name="fiber.synchronization.futures.promise.h3"></a>
 150           <span><a name="fiber.synchronization.futures.promise.destructor"></a></span><a class="link" href="promise.html#fiber.synchronization.futures.promise.destructor">Destructor</a>
 151         </h6>
 152 <pre class="programlisting"><span class="special">~</span><span class="identifier">promise</span><span class="special">();</span>
 153 </pre>
 154 <div class="variablelist">
 155 <p class="title"><b></b></p>
 156 <dl>
 157 <dt><span class="term">Effects:</span></dt>
 158 <dd><p>
 159                 Destroys <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
 160                 and abandons the <a class="link" href="future.html#shared_state">shared state</a>
 161                 if shared state is ready; otherwise stores <code class="computeroutput"><span class="identifier">future_error</span></code>
 162                 with error condition <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">broken_promise</span></code>
 163                 as if by <a class="link" href="promise.html#promise_set_exception"><code class="computeroutput">promise::set_exception()</code></a>: the shared
 164                 state is set ready.
 165               </p></dd>
 166 </dl>
 167 </div>
 168 <p>
 169           </p>
 170 <h5>
 171 <a name="promise_operator_assign_bridgehead"></a>
 172   <span><a name="promise_operator_assign"></a></span>
 173   <a class="link" href="promise.html#promise_operator_assign">Member
 174           function <code class="computeroutput">operator=</code>()</a>
 175 </h5>
 176 <p>
 177         </p>
 178 <pre class="programlisting"><span class="identifier">promise</span> <span class="special">&amp;</span> <span class="keyword">operator</span><span class="special">=(</span> <span class="identifier">promise</span> <span class="special">&amp;&amp;</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
 179 </pre>
 180 <div class="variablelist">
 181 <p class="title"><b></b></p>
 182 <dl>
 183 <dt><span class="term">Effects:</span></dt>
 184 <dd><p>
 185                 Transfers the ownership of <a class="link" href="future.html#shared_state">shared state</a>
 186                 to <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>.
 187               </p></dd>
 188 <dt><span class="term">Postcondition:</span></dt>
 189 <dd><p>
 190                 <code class="computeroutput"><span class="identifier">other</span></code> contains no
 191                 valid shared state.
 192               </p></dd>
 193 <dt><span class="term">Throws:</span></dt>
 194 <dd><p>
 195                 Nothing.
 196               </p></dd>
 197 </dl>
 198 </div>
 199 <p>
 200           </p>
 201 <h5>
 202 <a name="promise_swap_bridgehead"></a>
 203   <span><a name="promise_swap"></a></span>
 204   <a class="link" href="promise.html#promise_swap">Member function <code class="computeroutput">swap</code>()</a>
 205 </h5>
 206 <p>
 207         </p>
 208 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">promise</span> <span class="special">&amp;</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
 209 </pre>
 210 <div class="variablelist">
 211 <p class="title"><b></b></p>
 212 <dl>
 213 <dt><span class="term">Effects:</span></dt>
 214 <dd><p>
 215                 Swaps the <a class="link" href="future.html#shared_state">shared state</a> between
 216                 other and <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>.
 217               </p></dd>
 218 <dt><span class="term">Throws:</span></dt>
 219 <dd><p>
 220                 Nothing.
 221               </p></dd>
 222 </dl>
 223 </div>
 224 <p>
 225           </p>
 226 <h5>
 227 <a name="promise_get_future_bridgehead"></a>
 228   <span><a name="promise_get_future"></a></span>
 229   <a class="link" href="promise.html#promise_get_future">Member
 230           function <code class="computeroutput">get_future</code>()</a>
 231 </h5>
 232 <p>
 233         </p>
 234 <pre class="programlisting"><span class="identifier">future</span><span class="special">&lt;</span> <span class="identifier">R</span> <span class="special">&gt;</span> <span class="identifier">get_future</span><span class="special">();</span>
 235 </pre>
 236 <div class="variablelist">
 237 <p class="title"><b></b></p>
 238 <dl>
 239 <dt><span class="term">Returns:</span></dt>
 240 <dd><p>
 241                 A <a class="link" href="future.html#class_future"><code class="computeroutput">future&lt;&gt;</code></a> with the same <a class="link" href="future.html#shared_state">shared
 242                 state</a>.
 243               </p></dd>
 244 <dt><span class="term">Throws:</span></dt>
 245 <dd><p>
 246                 <code class="computeroutput"><span class="identifier">future_error</span></code> with
 247                 <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">future_already_retrieved</span></code> or <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">no_state</span></code>.
 248               </p></dd>
 249 </dl>
 250 </div>
 251 <p>
 252           </p>
 253 <h5>
 254 <a name="promise_set_value_bridgehead"></a>
 255   <span><a name="promise_set_value"></a></span>
 256   <a class="link" href="promise.html#promise_set_value">Member function
 257           <code class="computeroutput">set_value</code>()</a>
 258 </h5>
 259 <p>
 260         </p>
 261 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">(</span> <span class="identifier">R</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">value</span><span class="special">);</span>  <span class="comment">// member only of generic promise template</span>
 262 <span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">(</span> <span class="identifier">R</span> <span class="special">&amp;&amp;</span> <span class="identifier">value</span><span class="special">);</span>      <span class="comment">// member only of generic promise template</span>
 263 <span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">(</span> <span class="identifier">R</span> <span class="special">&amp;</span> <span class="identifier">value</span><span class="special">);</span>       <span class="comment">// member only of promise&lt; R &amp; &gt; template</span>
 264 <span class="keyword">void</span> <span class="identifier">set_value</span><span class="special">();</span>                 <span class="comment">// member only of promise&lt; void &gt; template</span>
 265 </pre>
 266 <div class="variablelist">
 267 <p class="title"><b></b></p>
 268 <dl>
 269 <dt><span class="term">Effects:</span></dt>
 270 <dd><p>
 271                 Store the result in the <a class="link" href="future.html#shared_state">shared state</a>
 272                 and marks the state as ready.
 273               </p></dd>
 274 <dt><span class="term">Throws:</span></dt>
 275 <dd><p>
 276                 <code class="computeroutput"><span class="identifier">future_error</span></code> with
 277                 <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">future_already_satisfied</span></code> or <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">no_state</span></code>.
 278               </p></dd>
 279 </dl>
 280 </div>
 281 <p>
 282           </p>
 283 <h5>
 284 <a name="promise_set_exception_bridgehead"></a>
 285   <span><a name="promise_set_exception"></a></span>
 286   <a class="link" href="promise.html#promise_set_exception">Member
 287           function <code class="computeroutput">set_exception</code>()</a>
 288 </h5>
 289 <p>
 290         </p>
 291 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">set_exception</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception_ptr</span><span class="special">);</span>
 292 </pre>
 293 <div class="variablelist">
 294 <p class="title"><b></b></p>
 295 <dl>
 296 <dt><span class="term">Effects:</span></dt>
 297 <dd><p>
 298                 Store an exception pointer in the <a class="link" href="future.html#shared_state">shared
 299                 state</a> and marks the state as ready.
 300               </p></dd>
 301 <dt><span class="term">Throws:</span></dt>
 302 <dd><p>
 303                 <code class="computeroutput"><span class="identifier">future_error</span></code> with
 304                 <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">future_already_satisfied</span></code> or <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">no_state</span></code>.
 305               </p></dd>
 306 </dl>
 307 </div>
 308 <p>
 309           </p>
 310 <h5>
 311 <a name="swap_for_promise_bridgehead"></a>
 312   <span><a name="swap_for_promise"></a></span>
 313   <a class="link" href="promise.html#swap_for_promise">Non-member function
 314           <code class="computeroutput">swap()</code></a>
 315 </h5>
 316 <p>
 317         </p>
 318 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">typename</span> <span class="identifier">R</span> <span class="special">&gt;</span>
 319 <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">promise</span><span class="special">&lt;</span> <span class="identifier">R</span> <span class="special">&gt;</span> <span class="special">&amp;</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">promise</span><span class="special">&lt;</span> <span class="identifier">R</span> <span class="special">&gt;</span> <span class="special">&amp;</span> <span class="identifier">r</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
 320 </pre>
 321 <div class="variablelist">
 322 <p class="title"><b></b></p>
 323 <dl>
 324 <dt><span class="term">Effects:</span></dt>
 325 <dd><p>
 326                 Same as <code class="computeroutput"><span class="identifier">l</span><span class="special">.</span><span class="identifier">swap</span><span class="special">(</span>
 327                 <span class="identifier">r</span><span class="special">)</span></code>.
 328               </p></dd>
 329 </dl>
 330 </div>
 331 </div>
 332 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 333 <td align="left"></td>
 334 <td align="right"><div class="copyright-footer">Copyright &#169; 2013 Oliver Kowalke<p>
 335         Distributed under the Boost Software License, Version 1.0. (See accompanying
 336         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>)
 337       </p>
 338 </div></td>
 339 </tr></table>
 340 <hr>
 341 <div class="spirit-nav">
 342 <a accesskey="p" href="future.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../futures.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="packaged_task.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 343 </div>
 344 </body>
 345 </html>