1[/ 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 6] 7 8[#class_packaged_task] 9[section:packaged_task Template `packaged_task<>`] 10 11A __packaged_task__ wraps a callable target that returns a value so that the 12return value can be computed asynchronously. 13 14Conventional usage of `packaged_task<>` is like this: 15 16# Instantiate `packaged_task<>` with template arguments matching the signature 17 of the callable. Pass the callable to the [link packaged_task_packaged_task 18 constructor]. 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<>`. 25 26This is, in fact, pretty much what [ns_function_link fibers..async] 27encapsulates. 28 29 #include <boost/fiber/future/packaged_task.hpp> 30 31 namespace boost { 32 namespace fibers { 33 34 template< class R, typename ... Args > 35 class packaged_task< R( Args ... ) > { 36 public: 37 packaged_task() noexcept; 38 39 template< typename Fn > 40 explicit packaged_task( Fn &&); 41 42 template< typename Fn, typename __Allocator__ > 43 packaged_task( __allocator_arg_t__, Allocator const&, Fn &&); 44 45 packaged_task( packaged_task &&) noexcept; 46 47 packaged_task & operator=( packaged_task &&) noexcept; 48 49 packaged_task( packaged_task const&) = delete; 50 51 packaged_task & operator=( packaged_task const&) = delete; 52 53 ~packaged_task(); 54 55 void swap( packaged_task &) noexcept; 56 57 bool valid() const noexcept; 58 59 future< R > get_future(); 60 61 void operator()( Args ...); 62 63 void reset(); 64 }; 65 66 template< typename Signature > 67 void swap( packaged_task< Signature > &, packaged_task< Signature > &) noexcept; 68 69 }} 70 71[heading Default constructor `packaged_task()`] 72 73 packaged_task() noexcept; 74 75[variablelist 76[[Effects:] [Constructs an object of class `packaged_task` with no [link 77shared_state shared state].]] 78[[Throws:] [Nothing.]] 79] 80 81[#packaged_task_packaged_task] 82[heading Templated constructor `packaged_task()`] 83 84 template< typename Fn > 85 explicit packaged_task( Fn && fn); 86 87 template< typename Fn, typename __Allocator__ > 88 packaged_task( __allocator_arg_t__, Allocator const& alloc, Fn && fn); 89 90[variablelist 91[[Effects:] [Constructs an object of class `packaged_task` with a [link 92shared_state shared state] and copies or moves the callable target `fn` to 93internal storage.]] 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__]] 97] 98 99[heading Move constructor] 100 101 packaged_task( packaged_task && other) noexcept; 102 103[variablelist 104[[Effects:] [Creates a packaged_task by moving the [link shared_state shared 105state] from `other`.]] 106[[Postcondition:] [`other` contains no valid shared state.]] 107[[Throws:] [Nothing.]] 108] 109 110[heading Destructor] 111 112 ~packaged_task(); 113 114[variablelist 115[[Effects:] [Destroys `*this` and abandons the [link shared_state shared 116state] if shared state is ready; otherwise stores __future_error__ with error 117condition __broken_promise__ as if by [member_link promise..set_exception]: 118the shared state is set ready.]] 119] 120 121[operator_heading packaged_task..operator_assign..operator=] 122 123 packaged_task & operator=( packaged_task && other) noexcept; 124 125[variablelist 126[[Effects:] [Transfers the ownership of [link shared_state shared state] to 127`*this`.]] 128[[Postcondition:] [`other` contains no valid shared state.]] 129[[Throws:] [Nothing.]] 130] 131 132[member_heading packaged_task..swap] 133 134 void swap( packaged_task & other) noexcept; 135 136[variablelist 137[[Effects:] [Swaps the [link shared_state shared state] between other and 138`*this`.]] 139[[Throws:] [Nothing.]] 140] 141 142[member_heading packaged_task..valid] 143 144 bool valid() const noexcept; 145 146[variablelist 147[[Effects:] [Returns `true` if `*this` contains a [link shared_state shared 148state].]] 149[[Throws:] [Nothing.]] 150] 151 152[member_heading packaged_task..get_future] 153 154 future< R > get_future(); 155 156[variablelist 157[[Returns:] [A __future__ with the same [link shared_state shared state].]] 158[[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]] 159] 160 161[operator_heading packaged_task..operator_apply..operator()] 162 163 void operator()( Args && ... args); 164 165[variablelist 166[[Effects:] [Invokes the stored callable target. Any exception thrown by the 167callable target `fn` is stored in the [link shared_state shared state] as if 168by [member_link promise..set_exception]. Otherwise, the value returned by `fn` 169is stored in the shared state as if by [member_link promise..set_value].]] 170[[Throws:] [__future_error__ with __no_state__.]] 171] 172 173[member_heading packaged_task..reset] 174 175 void reset(); 176 177[variablelist 178[[Effects:] [Resets the [link shared_state shared state] and abandons the 179result of previous executions. A new shared state is constructed.]] 180[[Throws:] [__future_error__ with __no_state__.]] 181] 182 183[function_heading_for swap..packaged_task] 184 185 template< typename Signature > 186 void swap( packaged_task< Signature > & l, packaged_task< Signature > & r) noexcept; 187 188[variablelist 189[[Effects:] [Same as `l.swap( r)`.]] 190] 191 192[endsect] 193