From Jason Turner

[futures.task]

C++14 → C++17 10.3 KB 104 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpz06h5ui2/{from.md → to.md} +51 -42
tmp/tmpz06h5ui2/{from.md → to.md} RENAMED
@@ -9,21 +9,19 @@ and the result (whether normal or exceptional) stored in the shared
9
  state. Any futures that share the shared state will then be able to
10
  access the stored result.
11
 
12
  ``` cpp
13
  namespace std {
14
- template<class> class packaged_task; // undefined
15
 
16
  template<class R, class... ArgTypes>
17
  class packaged_task<R(ArgTypes...)> {
18
  public:
19
  // construction and destruction
20
  packaged_task() noexcept;
21
  template <class F>
22
  explicit packaged_task(F&& f);
23
- template <class F, class Allocator>
24
- explicit packaged_task(allocator_arg_t, const Allocator& a, F&& f);
25
  ~packaged_task();
26
 
27
  // no copy
28
  packaged_task(const packaged_task&) = delete;
29
  packaged_task& operator=(const packaged_task&) = delete;
@@ -55,73 +53,73 @@ namespace std {
55
 
56
  ``` cpp
57
  packaged_task() noexcept;
58
  ```
59
 
60
- *Effects:* constructs a `packaged_task` object with no shared state and
61
  no stored task.
62
 
63
  ``` cpp
64
  template <class F>
65
  packaged_task(F&& f);
66
- template <class F, class Allocator>
67
- explicit packaged_task(allocator_arg_t, const Allocator& a, F&& f);
68
  ```
69
 
70
- *Requires:* *`INVOKE`*`(f, t1, t2, ..., tN, R)`, where `t1, t2, ..., tN`
71
  are values of the corresponding types in `ArgTypes...`, shall be a valid
72
  expression. Invoking a copy of `f` shall behave the same as invoking
73
  `f`.
74
 
75
- *Remarks:* These constructors shall not participate in overload
76
- resolution if `decay_t<F>` is the same type as
77
- `std::packaged_task<R(ArgTypes...)>`.
78
 
79
- *Effects:* constructs a new `packaged_task` object with a shared state
80
- and initializes the object’s stored task with `std::forward<F>(f)`. The
81
- constructors that take an `Allocator` argument use it to allocate memory
82
- needed to store the internal data structures.
83
 
84
- *Throws:* any exceptions thrown by the copy or move constructor of `f`,
85
- or `std::bad_alloc` if memory for the internal data structures could not
86
- be allocated.
 
 
 
 
 
87
 
88
  ``` cpp
89
  packaged_task(packaged_task&& rhs) noexcept;
90
  ```
91
 
92
- *Effects:* constructs a new `packaged_task` object and transfers
93
  ownership of `rhs`’s shared state to `*this`, leaving `rhs` with no
94
  shared state. Moves the stored task from `rhs` to `*this`.
95
 
96
- `rhs` has no shared state.
97
 
98
  ``` cpp
99
  packaged_task& operator=(packaged_task&& rhs) noexcept;
100
  ```
101
 
102
  *Effects:*
103
 
104
- - releases any shared state ([[futures.state]]).
105
- - `packaged_task(std::move(rhs)).swap(*this)`.
106
 
107
  ``` cpp
108
  ~packaged_task();
109
  ```
110
 
111
- *Effects:* Abandons any shared state. ([[futures.state]]).
112
 
113
  ``` cpp
114
  void swap(packaged_task& other) noexcept;
115
  ```
116
 
117
- *Effects:* exchanges the shared states and stored tasks of `*this` and
118
  `other`.
119
 
120
- `*this` has the same shared state and stored task (if any) as `other`
121
- prior to the call to `swap`. `other` has the same shared state and
122
- stored task (if any) as `*this` prior to the call to `swap`.
123
 
124
  ``` cpp
125
  bool valid() const noexcept;
126
  ```
127
 
@@ -144,14 +142,14 @@ future<R> get_future();
144
 
145
  ``` cpp
146
  void operator()(ArgTypes... args);
147
  ```
148
 
149
- *Effects:* *`INVOKE`*`(f, t1, t2, ..., tN, R)`, where `f` is the stored
150
- task of `*this` and `t1, t2, ..., tN` are the values in `args...`. If
151
- the task returns normally, the return value is stored as the
152
- asynchronous result in the shared state of `*this`, otherwise the
153
  exception thrown by the task is stored. The shared state of `*this` is
154
  made ready, and any threads blocked in a function waiting for the shared
155
  state of `*this` to become ready are unblocked.
156
 
157
  *Throws:* a `future_error` exception object if there is no shared state
@@ -165,18 +163,18 @@ or the stored task has already been invoked.
165
 
166
  ``` cpp
167
  void make_ready_at_thread_exit(ArgTypes... args);
168
  ```
169
 
170
- *Effects:* *`INVOKE`*`(f, t1, t2, ..., tN, R)`, where `f` is the stored
171
- task and `t1, t2, ..., tN` are the values in `args...`. If the task
172
- returns normally, the return value is stored as the asynchronous result
173
- in the shared state of `*this`, otherwise the exception thrown by the
174
- task is stored. In either case, this shall be done without making that
175
- state ready ([[futures.state]]) immediately. Schedules the shared state
176
- to be made ready when the current thread exits, after all objects of
177
- thread storage duration associated with the current thread have been
178
  destroyed.
179
 
180
  *Throws:* `future_error` if an error condition occurs.
181
 
182
  *Error conditions:*
@@ -187,13 +185,15 @@ destroyed.
187
 
188
  ``` cpp
189
  void reset();
190
  ```
191
 
192
- *Effects:* as if `*this = packaged_task(std::move(f))`, where `f` is the
193
- task stored in `*this`. This constructs a new shared state for `*this`.
194
- The old state is abandoned ([[futures.state]]).
 
 
195
 
196
  *Throws:*
197
 
198
  - `bad_alloc` if memory for the new shared state could not be allocated.
199
  - any exception thrown by the move constructor of the task stored in the
@@ -206,11 +206,11 @@ The old state is abandoned ([[futures.state]]).
206
  ``` cpp
207
  template <class R, class... ArgTypes>
208
  void swap(packaged_task<R(ArgTypes...)>& x, packaged_task<R(ArgTypes...)>& y) noexcept;
209
  ```
210
 
211
- *Effects:* `x.swap(y)`
212
 
213
  ``` cpp
214
  template <class R, class Alloc>
215
  struct uses_allocator<packaged_task<R>, Alloc>
216
  : true_type { };
@@ -224,12 +224,14 @@ template <class R, class Alloc>
224
  [atomics]: atomics.md#atomics
225
  [basic.life]: basic.md#basic.life
226
  [basic.stc.thread]: basic.md#basic.stc.thread
227
  [bitmask.types]: library.md#bitmask.types
228
  [class]: class.md#class
 
229
  [except.terminate]: except.md#except.terminate
230
  [func.require]: utilities.md#func.require
 
231
  [futures]: #futures
232
  [futures.async]: #futures.async
233
  [futures.errors]: #futures.errors
234
  [futures.future_error]: #futures.future_error
235
  [futures.overview]: #futures.overview
@@ -239,24 +241,28 @@ template <class R, class Alloc>
239
  [futures.task]: #futures.task
240
  [futures.task.members]: #futures.task.members
241
  [futures.task.nonmembers]: #futures.task.nonmembers
242
  [futures.unique_future]: #futures.unique_future
243
  [intro.multithread]: intro.md#intro.multithread
 
244
  [res.on.data.races]: library.md#res.on.data.races
245
  [res.on.exception.handling]: library.md#res.on.exception.handling
 
246
  [syserr]: diagnostics.md#syserr
247
  [syserr.syserr]: diagnostics.md#syserr.syserr
248
  [tab:thread.lib.summary]: #tab:thread.lib.summary
249
  [thread]: #thread
250
  [thread.condition]: #thread.condition
251
  [thread.condition.condvar]: #thread.condition.condvar
252
  [thread.condition.condvarany]: #thread.condition.condvarany
 
253
  [thread.decaycopy]: #thread.decaycopy
254
  [thread.general]: #thread.general
255
  [thread.lock]: #thread.lock
256
  [thread.lock.algorithm]: #thread.lock.algorithm
257
  [thread.lock.guard]: #thread.lock.guard
 
258
  [thread.lock.shared]: #thread.lock.shared
259
  [thread.lock.shared.cons]: #thread.lock.shared.cons
260
  [thread.lock.shared.locking]: #thread.lock.shared.locking
261
  [thread.lock.shared.mod]: #thread.lock.shared.mod
262
  [thread.lock.shared.obs]: #thread.lock.shared.obs
@@ -282,12 +288,15 @@ template <class R, class Alloc>
282
  [thread.req.lockable.req]: #thread.req.lockable.req
283
  [thread.req.lockable.timed]: #thread.req.lockable.timed
284
  [thread.req.native]: #thread.req.native
285
  [thread.req.paramname]: #thread.req.paramname
286
  [thread.req.timing]: #thread.req.timing
 
 
287
  [thread.sharedtimedmutex.class]: #thread.sharedtimedmutex.class
288
  [thread.sharedtimedmutex.requirements]: #thread.sharedtimedmutex.requirements
 
289
  [thread.thread.algorithm]: #thread.thread.algorithm
290
  [thread.thread.assign]: #thread.thread.assign
291
  [thread.thread.class]: #thread.thread.class
292
  [thread.thread.constr]: #thread.thread.constr
293
  [thread.thread.destr]: #thread.thread.destr
 
9
  state. Any futures that share the shared state will then be able to
10
  access the stored result.
11
 
12
  ``` cpp
13
  namespace std {
14
+ template<class> class packaged_task; // not defined
15
 
16
  template<class R, class... ArgTypes>
17
  class packaged_task<R(ArgTypes...)> {
18
  public:
19
  // construction and destruction
20
  packaged_task() noexcept;
21
  template <class F>
22
  explicit packaged_task(F&& f);
 
 
23
  ~packaged_task();
24
 
25
  // no copy
26
  packaged_task(const packaged_task&) = delete;
27
  packaged_task& operator=(const packaged_task&) = delete;
 
53
 
54
  ``` cpp
55
  packaged_task() noexcept;
56
  ```
57
 
58
+ *Effects:* Constructs a `packaged_task` object with no shared state and
59
  no stored task.
60
 
61
  ``` cpp
62
  template <class F>
63
  packaged_task(F&& f);
 
 
64
  ```
65
 
66
+ *Requires:* *INVOKE*\<R\>(f, t1, t2, ..., tN), where `t1, t2, ..., tN`
67
  are values of the corresponding types in `ArgTypes...`, shall be a valid
68
  expression. Invoking a copy of `f` shall behave the same as invoking
69
  `f`.
70
 
71
+ *Remarks:* This constructor shall not participate in overload resolution
72
+ if `decay_t<F>` is the same type as `packaged_task<R(ArgTypes...)>`.
 
73
 
74
+ *Effects:* Constructs a new `packaged_task` object with a shared state
75
+ and initializes the object’s stored task with `std::forward<F>(f)`.
 
 
76
 
77
+ *Throws:*
78
+
79
+ - Any exceptions thrown by the copy or move constructor of `f`.
80
+ - For the first version, `bad_alloc` if memory for the internal data
81
+ structures could not be allocated.
82
+ - For the second version, any exceptions thrown by
83
+ `allocator_traits<Allocator>::template`
84
+ `rebind_traits<`*`unspecified`*`>::allocate`.
85
 
86
  ``` cpp
87
  packaged_task(packaged_task&& rhs) noexcept;
88
  ```
89
 
90
+ *Effects:* Constructs a new `packaged_task` object and transfers
91
  ownership of `rhs`’s shared state to `*this`, leaving `rhs` with no
92
  shared state. Moves the stored task from `rhs` to `*this`.
93
 
94
+ *Postconditions:* `rhs` has no shared state.
95
 
96
  ``` cpp
97
  packaged_task& operator=(packaged_task&& rhs) noexcept;
98
  ```
99
 
100
  *Effects:*
101
 
102
+ - Releases any shared state ([[futures.state]]);
103
+ - calls `packaged_task(std::move(rhs)).swap(*this)`.
104
 
105
  ``` cpp
106
  ~packaged_task();
107
  ```
108
 
109
+ *Effects:* Abandons any shared state ([[futures.state]]).
110
 
111
  ``` cpp
112
  void swap(packaged_task& other) noexcept;
113
  ```
114
 
115
+ *Effects:* Exchanges the shared states and stored tasks of `*this` and
116
  `other`.
117
 
118
+ *Postconditions:* `*this` has the same shared state and stored task (if
119
+ any) as `other` prior to the call to `swap`. `other` has the same shared
120
+ state and stored task (if any) as `*this` prior to the call to `swap`.
121
 
122
  ``` cpp
123
  bool valid() const noexcept;
124
  ```
125
 
 
142
 
143
  ``` cpp
144
  void operator()(ArgTypes... args);
145
  ```
146
 
147
+ *Effects:* As if by *INVOKE*\<R\>(f, t1, t2, ..., tN), where `f` is the
148
+ stored task of `*this` and `t1, t2, ..., tN` are the values in
149
+ `args...`. If the task returns normally, the return value is stored as
150
+ the asynchronous result in the shared state of `*this`, otherwise the
151
  exception thrown by the task is stored. The shared state of `*this` is
152
  made ready, and any threads blocked in a function waiting for the shared
153
  state of `*this` to become ready are unblocked.
154
 
155
  *Throws:* a `future_error` exception object if there is no shared state
 
163
 
164
  ``` cpp
165
  void make_ready_at_thread_exit(ArgTypes... args);
166
  ```
167
 
168
+ *Effects:* As if by *INVOKE*\<R\>(f, t1, t2, ..., tN), where `f` is the
169
+ stored task and `t1, t2, ..., tN` are the values in `args...`. If the
170
+ task returns normally, the return value is stored as the asynchronous
171
+ result in the shared state of `*this`, otherwise the exception thrown by
172
+ the task is stored. In either case, this shall be done without making
173
+ that state ready ([[futures.state]]) immediately. Schedules the shared
174
+ state to be made ready when the current thread exits, after all objects
175
+ of thread storage duration associated with the current thread have been
176
  destroyed.
177
 
178
  *Throws:* `future_error` if an error condition occurs.
179
 
180
  *Error conditions:*
 
185
 
186
  ``` cpp
187
  void reset();
188
  ```
189
 
190
+ *Effects:* As if `*this = packaged_task(std::move(f))`, where `f` is the
191
+ task stored in `*this`.
192
+
193
+ [*Note 1*: This constructs a new shared state for `*this`. The old
194
+ state is abandoned ([[futures.state]]). — *end note*]
195
 
196
  *Throws:*
197
 
198
  - `bad_alloc` if memory for the new shared state could not be allocated.
199
  - any exception thrown by the move constructor of the task stored in the
 
206
  ``` cpp
207
  template <class R, class... ArgTypes>
208
  void swap(packaged_task<R(ArgTypes...)>& x, packaged_task<R(ArgTypes...)>& y) noexcept;
209
  ```
210
 
211
+ *Effects:* As if by `x.swap(y)`.
212
 
213
  ``` cpp
214
  template <class R, class Alloc>
215
  struct uses_allocator<packaged_task<R>, Alloc>
216
  : true_type { };
 
224
  [atomics]: atomics.md#atomics
225
  [basic.life]: basic.md#basic.life
226
  [basic.stc.thread]: basic.md#basic.stc.thread
227
  [bitmask.types]: library.md#bitmask.types
228
  [class]: class.md#class
229
+ [condition_variable.syn]: #condition_variable.syn
230
  [except.terminate]: except.md#except.terminate
231
  [func.require]: utilities.md#func.require
232
+ [future.syn]: #future.syn
233
  [futures]: #futures
234
  [futures.async]: #futures.async
235
  [futures.errors]: #futures.errors
236
  [futures.future_error]: #futures.future_error
237
  [futures.overview]: #futures.overview
 
241
  [futures.task]: #futures.task
242
  [futures.task.members]: #futures.task.members
243
  [futures.task.nonmembers]: #futures.task.nonmembers
244
  [futures.unique_future]: #futures.unique_future
245
  [intro.multithread]: intro.md#intro.multithread
246
+ [mutex.syn]: #mutex.syn
247
  [res.on.data.races]: library.md#res.on.data.races
248
  [res.on.exception.handling]: library.md#res.on.exception.handling
249
+ [shared_mutex.syn]: #shared_mutex.syn
250
  [syserr]: diagnostics.md#syserr
251
  [syserr.syserr]: diagnostics.md#syserr.syserr
252
  [tab:thread.lib.summary]: #tab:thread.lib.summary
253
  [thread]: #thread
254
  [thread.condition]: #thread.condition
255
  [thread.condition.condvar]: #thread.condition.condvar
256
  [thread.condition.condvarany]: #thread.condition.condvarany
257
+ [thread.condition.nonmember]: #thread.condition.nonmember
258
  [thread.decaycopy]: #thread.decaycopy
259
  [thread.general]: #thread.general
260
  [thread.lock]: #thread.lock
261
  [thread.lock.algorithm]: #thread.lock.algorithm
262
  [thread.lock.guard]: #thread.lock.guard
263
+ [thread.lock.scoped]: #thread.lock.scoped
264
  [thread.lock.shared]: #thread.lock.shared
265
  [thread.lock.shared.cons]: #thread.lock.shared.cons
266
  [thread.lock.shared.locking]: #thread.lock.shared.locking
267
  [thread.lock.shared.mod]: #thread.lock.shared.mod
268
  [thread.lock.shared.obs]: #thread.lock.shared.obs
 
288
  [thread.req.lockable.req]: #thread.req.lockable.req
289
  [thread.req.lockable.timed]: #thread.req.lockable.timed
290
  [thread.req.native]: #thread.req.native
291
  [thread.req.paramname]: #thread.req.paramname
292
  [thread.req.timing]: #thread.req.timing
293
+ [thread.sharedmutex.class]: #thread.sharedmutex.class
294
+ [thread.sharedmutex.requirements]: #thread.sharedmutex.requirements
295
  [thread.sharedtimedmutex.class]: #thread.sharedtimedmutex.class
296
  [thread.sharedtimedmutex.requirements]: #thread.sharedtimedmutex.requirements
297
+ [thread.syn]: #thread.syn
298
  [thread.thread.algorithm]: #thread.thread.algorithm
299
  [thread.thread.assign]: #thread.thread.assign
300
  [thread.thread.class]: #thread.thread.class
301
  [thread.thread.constr]: #thread.thread.constr
302
  [thread.thread.destr]: #thread.thread.destr