3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Template packaged_task<></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="../futures.html" title="Futures">
9 <link rel="prev" href="promise.html" title="Template promise<>">
10 <link rel="next" href="../../fls.html" title="Fiber local storage">
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>
22 <div class="spirit-nav">
23 <a accesskey="p" href="promise.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="../../fls.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h4 class="title">
27 <a name="fiber.synchronization.futures.packaged_task"></a><a name="class_packaged_task"></a><a class="link" href="packaged_task.html" title="Template packaged_task<>">Template
28 <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special"><></span></code></a>
29 </h4></div></div></div>
31 A <a class="link" href="packaged_task.html#class_packaged_task"><code class="computeroutput">packaged_task<></code></a> wraps a callable target that
32 returns a value so that the return value can be computed asynchronously.
35 Conventional usage of <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special"><></span></code> is like this:
37 <div class="orderedlist"><ol class="orderedlist" type="1">
39 Instantiate <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special"><></span></code> with template arguments matching
40 the signature of the callable. Pass the callable to the <a class="link" href="packaged_task.html#packaged_task_packaged_task">constructor</a>.
43 Call <a class="link" href="packaged_task.html#packaged_task_get_future"><code class="computeroutput">packaged_task::get_future()</code></a> and capture
44 the returned <a class="link" href="future.html#class_future"><code class="computeroutput">future<></code></a> instance.
47 Launch a <a class="link" href="../../fiber_mgmt/fiber.html#class_fiber"><code class="computeroutput">fiber</code></a> to run the new <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special"><></span></code>, passing any arguments required
48 by the original callable.
51 Call <a class="link" href="../../fiber_mgmt/fiber.html#fiber_detach"><code class="computeroutput">fiber::detach()</code></a> on the newly-launched <code class="computeroutput"><span class="identifier">fiber</span></code>.
54 At some later point, retrieve the result from the <code class="computeroutput"><span class="identifier">future</span><span class="special"><></span></code>.
58 This is, in fact, pretty much what <a class="link" href="future.html#fibers_async"><code class="computeroutput">fibers::async()</code></a>
61 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">packaged_task</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
63 <span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
64 <span class="keyword">namespace</span> <span class="identifier">fibers</span> <span class="special">{</span>
66 <span class="keyword">template</span><span class="special"><</span> <span class="keyword">class</span> <span class="identifier">R</span><span class="special">,</span> <span class="keyword">typename</span> <span class="special">...</span> <span class="identifier">Args</span> <span class="special">></span>
67 <span class="keyword">class</span> <span class="identifier">packaged_task</span><span class="special"><</span> <span class="identifier">R</span><span class="special">(</span> <span class="identifier">Args</span> <span class="special">...</span> <span class="special">)</span> <span class="special">></span> <span class="special">{</span>
68 <span class="keyword">public</span><span class="special">:</span>
69 <span class="identifier">packaged_task</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span>
71 <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Fn</span> <span class="special">></span>
72 <span class="keyword">explicit</span> <span class="identifier">packaged_task</span><span class="special">(</span> <span class="identifier">Fn</span> <span class="special">&&);</span>
74 <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Fn</span><span class="special">,</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">></span>
75 <span class="identifier">packaged_task</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="keyword">const</span><span class="special">&,</span> <span class="identifier">Fn</span> <span class="special">&&);</span>
77 <span class="identifier">packaged_task</span><span class="special">(</span> <span class="identifier">packaged_task</span> <span class="special">&&)</span> <span class="keyword">noexcept</span><span class="special">;</span>
79 <span class="identifier">packaged_task</span> <span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span> <span class="identifier">packaged_task</span> <span class="special">&&)</span> <span class="keyword">noexcept</span><span class="special">;</span>
81 <span class="identifier">packaged_task</span><span class="special">(</span> <span class="identifier">packaged_task</span> <span class="keyword">const</span><span class="special">&)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span>
83 <span class="identifier">packaged_task</span> <span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span> <span class="identifier">packaged_task</span> <span class="keyword">const</span><span class="special">&)</span> <span class="special">=</span> <span class="keyword">delete</span><span class="special">;</span>
85 <span class="special">~</span><span class="identifier">packaged_task</span><span class="special">();</span>
87 <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">packaged_task</span> <span class="special">&)</span> <span class="keyword">noexcept</span><span class="special">;</span>
89 <span class="keyword">bool</span> <span class="identifier">valid</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span>
91 <span class="identifier">future</span><span class="special"><</span> <span class="identifier">R</span> <span class="special">></span> <span class="identifier">get_future</span><span class="special">();</span>
93 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span> <span class="identifier">Args</span> <span class="special">...);</span>
95 <span class="keyword">void</span> <span class="identifier">reset</span><span class="special">();</span>
96 <span class="special">};</span>
98 <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Signature</span> <span class="special">></span>
99 <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">packaged_task</span><span class="special"><</span> <span class="identifier">Signature</span> <span class="special">></span> <span class="special">&,</span> <span class="identifier">packaged_task</span><span class="special"><</span> <span class="identifier">Signature</span> <span class="special">></span> <span class="special">&)</span> <span class="keyword">noexcept</span><span class="special">;</span>
101 <span class="special">}}</span>
104 <a name="fiber.synchronization.futures.packaged_task.h0"></a>
105 <span class="phrase"><a name="fiber.synchronization.futures.packaged_task.default_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="packaged_task.html#fiber.synchronization.futures.packaged_task.default_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_">Default
106 constructor <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special">()</span></code></a>
108 <pre class="programlisting"><span class="identifier">packaged_task</span><span class="special">()</span> <span class="keyword">noexcept</span><span class="special">;</span>
110 <div class="variablelist">
111 <p class="title"><b></b></p>
112 <dl class="variablelist">
113 <dt><span class="term">Effects:</span></dt>
115 Constructs an object of class <code class="computeroutput"><span class="identifier">packaged_task</span></code>
116 with no <a class="link" href="future.html#shared_state">shared state</a>.
118 <dt><span class="term">Throws:</span></dt>
124 <a name="packaged_task_packaged_task"></a><h6>
125 <a name="fiber.synchronization.futures.packaged_task.h1"></a>
126 <span class="phrase"><a name="fiber.synchronization.futures.packaged_task.templated_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_"></a></span><a class="link" href="packaged_task.html#fiber.synchronization.futures.packaged_task.templated_constructor__code__phrase_role__identifier__packaged_task__phrase__phrase_role__special______phrase___code_">Templated
127 constructor <code class="computeroutput"><span class="identifier">packaged_task</span><span class="special">()</span></code></a>
129 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Fn</span> <span class="special">></span>
130 <span class="keyword">explicit</span> <span class="identifier">packaged_task</span><span class="special">(</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">);</span>
132 <span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Fn</span><span class="special">,</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">></span>
133 <span class="identifier">packaged_task</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="keyword">const</span><span class="special">&</span> <span class="identifier">alloc</span><span class="special">,</span> <span class="identifier">Fn</span> <span class="special">&&</span> <span class="identifier">fn</span><span class="special">);</span>
135 <div class="variablelist">
136 <p class="title"><b></b></p>
137 <dl class="variablelist">
138 <dt><span class="term">Effects:</span></dt>
140 Constructs an object of class <code class="computeroutput"><span class="identifier">packaged_task</span></code>
141 with a <a class="link" href="future.html#shared_state">shared state</a> and copies
142 or moves the callable target <code class="computeroutput"><span class="identifier">fn</span></code>
145 <dt><span class="term">Throws:</span></dt>
147 Exceptions caused by memory allocation.
149 <dt><span class="term">Note:</span></dt>
151 The signature of <code class="computeroutput"><span class="identifier">Fn</span></code>
152 should have a return type convertible to <code class="computeroutput"><span class="identifier">R</span></code>.
154 <dt><span class="term">See also:</span></dt>
156 <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>
161 <a name="fiber.synchronization.futures.packaged_task.h2"></a>
162 <span class="phrase"><a name="fiber.synchronization.futures.packaged_task.move_constructor"></a></span><a class="link" href="packaged_task.html#fiber.synchronization.futures.packaged_task.move_constructor">Move
165 <pre class="programlisting"><span class="identifier">packaged_task</span><span class="special">(</span> <span class="identifier">packaged_task</span> <span class="special">&&</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
167 <div class="variablelist">
168 <p class="title"><b></b></p>
169 <dl class="variablelist">
170 <dt><span class="term">Effects:</span></dt>
172 Creates a packaged_task by moving the <a class="link" href="future.html#shared_state">shared
173 state</a> from <code class="computeroutput"><span class="identifier">other</span></code>.
175 <dt><span class="term">Postcondition:</span></dt>
177 <code class="computeroutput"><span class="identifier">other</span></code> contains no
180 <dt><span class="term">Throws:</span></dt>
187 <a name="fiber.synchronization.futures.packaged_task.h3"></a>
188 <span class="phrase"><a name="fiber.synchronization.futures.packaged_task.destructor"></a></span><a class="link" href="packaged_task.html#fiber.synchronization.futures.packaged_task.destructor">Destructor</a>
190 <pre class="programlisting"><span class="special">~</span><span class="identifier">packaged_task</span><span class="special">();</span>
192 <div class="variablelist">
193 <p class="title"><b></b></p>
194 <dl class="variablelist">
195 <dt><span class="term">Effects:</span></dt>
197 Destroys <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
198 and abandons the <a class="link" href="future.html#shared_state">shared state</a>
199 if shared state is ready; otherwise stores <code class="computeroutput"><span class="identifier">future_error</span></code>
200 with error condition <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">broken_promise</span></code>
201 as if by <a class="link" href="promise.html#promise_set_exception"><code class="computeroutput">promise::set_exception()</code></a>: the shared
209 <a name="packaged_task_operator_assign_bridgehead"></a>
210 <span class="phrase"><a name="packaged_task_operator_assign"></a></span>
211 <a class="link" href="packaged_task.html#packaged_task_operator_assign">Member
212 function <code class="computeroutput">operator=</code>()</a>
216 <pre class="programlisting"><span class="identifier">packaged_task</span> <span class="special">&</span> <span class="keyword">operator</span><span class="special">=(</span> <span class="identifier">packaged_task</span> <span class="special">&&</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
218 <div class="variablelist">
219 <p class="title"><b></b></p>
220 <dl class="variablelist">
221 <dt><span class="term">Effects:</span></dt>
223 Transfers the ownership of <a class="link" href="future.html#shared_state">shared state</a>
224 to <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>.
226 <dt><span class="term">Postcondition:</span></dt>
228 <code class="computeroutput"><span class="identifier">other</span></code> contains no
231 <dt><span class="term">Throws:</span></dt>
240 <a name="packaged_task_swap_bridgehead"></a>
241 <span class="phrase"><a name="packaged_task_swap"></a></span>
242 <a class="link" href="packaged_task.html#packaged_task_swap">Member
243 function <code class="computeroutput">swap</code>()</a>
247 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">packaged_task</span> <span class="special">&</span> <span class="identifier">other</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
249 <div class="variablelist">
250 <p class="title"><b></b></p>
251 <dl class="variablelist">
252 <dt><span class="term">Effects:</span></dt>
254 Swaps the <a class="link" href="future.html#shared_state">shared state</a> between
255 other and <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>.
257 <dt><span class="term">Throws:</span></dt>
266 <a name="packaged_task_valid_bridgehead"></a>
267 <span class="phrase"><a name="packaged_task_valid"></a></span>
268 <a class="link" href="packaged_task.html#packaged_task_valid">Member
269 function <code class="computeroutput">valid</code>()</a>
273 <pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">valid</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span><span class="special">;</span>
275 <div class="variablelist">
276 <p class="title"><b></b></p>
277 <dl class="variablelist">
278 <dt><span class="term">Effects:</span></dt>
280 Returns <code class="computeroutput"><span class="keyword">true</span></code> if <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
281 contains a <a class="link" href="future.html#shared_state">shared state</a>.
283 <dt><span class="term">Throws:</span></dt>
292 <a name="packaged_task_get_future_bridgehead"></a>
293 <span class="phrase"><a name="packaged_task_get_future"></a></span>
294 <a class="link" href="packaged_task.html#packaged_task_get_future">Member
295 function <code class="computeroutput">get_future</code>()</a>
299 <pre class="programlisting"><span class="identifier">future</span><span class="special"><</span> <span class="identifier">R</span> <span class="special">></span> <span class="identifier">get_future</span><span class="special">();</span>
301 <div class="variablelist">
302 <p class="title"><b></b></p>
303 <dl class="variablelist">
304 <dt><span class="term">Returns:</span></dt>
306 A <a class="link" href="future.html#class_future"><code class="computeroutput">future<></code></a> with the same <a class="link" href="future.html#shared_state">shared
309 <dt><span class="term">Throws:</span></dt>
311 <code class="computeroutput"><span class="identifier">future_error</span></code> with
312 <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>.
319 <a name="packaged_task_operator_apply_bridgehead"></a>
320 <span class="phrase"><a name="packaged_task_operator_apply"></a></span>
321 <a class="link" href="packaged_task.html#packaged_task_operator_apply">Member
322 function <code class="computeroutput">operator()</code>()</a>
326 <pre class="programlisting"><span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span> <span class="identifier">Args</span> <span class="special">&&</span> <span class="special">...</span> <span class="identifier">args</span><span class="special">);</span>
328 <div class="variablelist">
329 <p class="title"><b></b></p>
330 <dl class="variablelist">
331 <dt><span class="term">Effects:</span></dt>
333 Invokes the stored callable target. Any exception thrown by the callable
334 target <code class="computeroutput"><span class="identifier">fn</span></code> is stored
335 in the <a class="link" href="future.html#shared_state">shared state</a> as if by
336 <a class="link" href="promise.html#promise_set_exception"><code class="computeroutput">promise::set_exception()</code></a>. Otherwise, the value
337 returned by <code class="computeroutput"><span class="identifier">fn</span></code> is
338 stored in the shared state as if by <a class="link" href="promise.html#promise_set_value"><code class="computeroutput">promise::set_value()</code></a>.
340 <dt><span class="term">Throws:</span></dt>
342 <code class="computeroutput"><span class="identifier">future_error</span></code> with
343 <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">no_state</span></code>.
350 <a name="packaged_task_reset_bridgehead"></a>
351 <span class="phrase"><a name="packaged_task_reset"></a></span>
352 <a class="link" href="packaged_task.html#packaged_task_reset">Member
353 function <code class="computeroutput">reset</code>()</a>
357 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">reset</span><span class="special">();</span>
359 <div class="variablelist">
360 <p class="title"><b></b></p>
361 <dl class="variablelist">
362 <dt><span class="term">Effects:</span></dt>
364 Resets the <a class="link" href="future.html#shared_state">shared state</a> and abandons
365 the result of previous executions. A new shared state is constructed.
367 <dt><span class="term">Throws:</span></dt>
369 <code class="computeroutput"><span class="identifier">future_error</span></code> with
370 <code class="computeroutput"><span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">no_state</span></code>.
377 <a name="swap_for_packaged_task_bridgehead"></a>
378 <span class="phrase"><a name="swap_for_packaged_task"></a></span>
379 <a class="link" href="packaged_task.html#swap_for_packaged_task">Non-member
380 function <code class="computeroutput">swap()</code></a>
384 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span> <span class="keyword">typename</span> <span class="identifier">Signature</span> <span class="special">></span>
385 <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">packaged_task</span><span class="special"><</span> <span class="identifier">Signature</span> <span class="special">></span> <span class="special">&</span> <span class="identifier">l</span><span class="special">,</span> <span class="identifier">packaged_task</span><span class="special"><</span> <span class="identifier">Signature</span> <span class="special">></span> <span class="special">&</span> <span class="identifier">r</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span>
387 <div class="variablelist">
388 <p class="title"><b></b></p>
389 <dl class="variablelist">
390 <dt><span class="term">Effects:</span></dt>
392 Same as <code class="computeroutput"><span class="identifier">l</span><span class="special">.</span><span class="identifier">swap</span><span class="special">(</span>
393 <span class="identifier">r</span><span class="special">)</span></code>.
398 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
399 <td align="left"></td>
400 <td align="right"><div class="copyright-footer">Copyright © 2013 Oliver Kowalke<p>
401 Distributed under the Boost Software License, Version 1.0. (See accompanying
402 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>)
407 <div class="spirit-nav">
408 <a accesskey="p" href="promise.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="../../fls.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>