]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
11 | A __packaged_task__ wraps a callable target that returns a value so that the | |
12 | return value can be computed asynchronously. | |
13 | ||
14 | Conventional 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 | ||
26 | This is, in fact, pretty much what [ns_function_link fibers..async] | |
27 | encapsulates. | |
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 | |
77 | shared_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 | |
92 | shared_state shared state] and copies or moves the callable target `fn` to | |
93 | internal 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 | |
105 | state] 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 | |
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.]] | |
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 | |
148 | state].]] | |
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 | |
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__.]] | |
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 | |
179 | result 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] |