2 Copyright Oliver Kowalke 2013.
3 Distributed under the Boost Software License, Version 1.0.
4 (See accompanying file LICENSE_1_0.txt or copy at
5 http://www.boost.org/LICENSE_1_0.txt
9 [section:packaged_task Template `packaged_task<>`]
11 A __packaged_task__ wraps a callable target that returns a value so that the
12 return value can be computed asynchronously.
14 Conventional usage of `packaged_task<>` is like this:
16 # Instantiate `packaged_task<>` with template arguments matching the signature
17 of the callable. Pass the callable to the [link packaged_task_packaged_task
19 # Call [member_link packaged_task..get_future] and capture the returned
20 [template_link future] instance.
21 # Launch a [class_link fiber] to run the new `packaged_task<>`, passing any
22 arguments required by the original callable.
23 # Call [member_link fiber..detach] on the newly-launched `fiber`.
24 # At some later point, retrieve the result from the `future<>`.
26 This is, in fact, pretty much what [ns_function_link fibers..async]
29 #include <boost/fiber/future/packaged_task.hpp>
34 template< class R, typename ... Args >
35 class packaged_task< R( Args ... ) > {
37 packaged_task() noexcept;
39 template< typename Fn >
40 explicit packaged_task( Fn &&);
42 template< typename Fn, typename __Allocator__ >
43 packaged_task( __allocator_arg_t__, Allocator const&, Fn &&);
45 packaged_task( packaged_task &&) noexcept;
47 packaged_task & operator=( packaged_task &&) noexcept;
49 packaged_task( packaged_task const&) = delete;
51 packaged_task & operator=( packaged_task const&) = delete;
55 void swap( packaged_task &) noexcept;
57 bool valid() const noexcept;
59 future< R > get_future();
61 void operator()( Args ...);
66 template< typename Signature >
67 void swap( packaged_task< Signature > &, packaged_task< Signature > &) noexcept;
71 [heading Default constructor `packaged_task()`]
73 packaged_task() noexcept;
76 [[Effects:] [Constructs an object of class `packaged_task` with no [link
77 shared_state shared state].]]
78 [[Throws:] [Nothing.]]
81 [#packaged_task_packaged_task]
82 [heading Templated constructor `packaged_task()`]
84 template< typename Fn >
85 explicit packaged_task( Fn && fn);
87 template< typename Fn, typename __Allocator__ >
88 packaged_task( __allocator_arg_t__, Allocator const& alloc, Fn && fn);
91 [[Effects:] [Constructs an object of class `packaged_task` with a [link
92 shared_state shared state] and copies or moves the callable target `fn` to
94 [[Throws:] [Exceptions caused by memory allocation.]]
95 [[Note:] [The signature of `Fn` should have a return type convertible to `R`.]]
96 [[See also:] [__allocator_arg_t__]]
99 [heading Move constructor]
101 packaged_task( packaged_task && other) noexcept;
104 [[Effects:] [Creates a packaged_task by moving the [link shared_state shared
105 state] from `other`.]]
106 [[Postcondition:] [`other` contains no valid shared state.]]
107 [[Throws:] [Nothing.]]
115 [[Effects:] [Destroys `*this` and abandons the [link shared_state shared
116 state] if shared state is ready; otherwise stores __future_error__ with error
117 condition __broken_promise__ as if by [member_link promise..set_exception]:
118 the shared state is set ready.]]
121 [operator_heading packaged_task..operator_assign..operator=]
123 packaged_task & operator=( packaged_task && other) noexcept;
126 [[Effects:] [Transfers the ownership of [link shared_state shared state] to
128 [[Postcondition:] [`other` contains no valid shared state.]]
129 [[Throws:] [Nothing.]]
132 [member_heading packaged_task..swap]
134 void swap( packaged_task & other) noexcept;
137 [[Effects:] [Swaps the [link shared_state shared state] between other and
139 [[Throws:] [Nothing.]]
142 [member_heading packaged_task..valid]
144 bool valid() const noexcept;
147 [[Effects:] [Returns `true` if `*this` contains a [link shared_state shared
149 [[Throws:] [Nothing.]]
152 [member_heading packaged_task..get_future]
154 future< R > get_future();
157 [[Returns:] [A __future__ with the same [link shared_state shared state].]]
158 [[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
161 [operator_heading packaged_task..operator_apply..operator()]
163 void operator()( Args && ... args);
166 [[Effects:] [Invokes the stored callable target. Any exception thrown by the
167 callable target `fn` is stored in the [link shared_state shared state] as if
168 by [member_link promise..set_exception]. Otherwise, the value returned by `fn`
169 is stored in the shared state as if by [member_link promise..set_value].]]
170 [[Throws:] [__future_error__ with __no_state__.]]
173 [member_heading packaged_task..reset]
178 [[Effects:] [Resets the [link shared_state shared state] and abandons the
179 result of previous executions. A new shared state is constructed.]]
180 [[Throws:] [__future_error__ with __no_state__.]]
183 [function_heading_for swap..packaged_task]
185 template< typename Signature >
186 void swap( packaged_task< Signature > & l, packaged_task< Signature > & r) noexcept;
189 [[Effects:] [Same as `l.swap( r)`.]]