From Jason Turner

[futures.task.members]

C++17 → C++20 7.3 KB 100 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp4233b7c4/{from.md → to.md} +47 -46
tmp/tmp4233b7c4/{from.md → to.md} RENAMED
@@ -1,74 +1,68 @@
1
- #### `packaged_task` member functions <a id="futures.task.members">[[futures.task.members]]</a>
2
 
3
  ``` cpp
4
  packaged_task() noexcept;
5
  ```
6
 
7
- *Effects:* Constructs a `packaged_task` object with no shared state and
8
- no stored task.
9
 
10
  ``` cpp
11
  template<class F>
12
  packaged_task(F&& f);
13
  ```
14
 
15
- *Requires:* *INVOKE*\<R\>(f, t1, t2, ..., tN), where `t1, t2, ..., tN`
16
- are values of the corresponding types in `ArgTypes...`, shall be a valid
17
- expression. Invoking a copy of `f` shall behave the same as invoking
 
 
 
18
  `f`.
19
 
20
- *Remarks:* This constructor shall not participate in overload resolution
21
- if `decay_t<F>` is the same type as `packaged_task<R(ArgTypes...)>`.
22
-
23
  *Effects:* Constructs a new `packaged_task` object with a shared state
24
  and initializes the object’s stored task with `std::forward<F>(f)`.
25
 
26
- *Throws:*
27
-
28
- - Any exceptions thrown by the copy or move constructor of `f`.
29
- - For the first version, `bad_alloc` if memory for the internal data
30
- structures could not be allocated.
31
- - For the second version, any exceptions thrown by
32
- `allocator_traits<Allocator>::template`
33
- `rebind_traits<`*`unspecified`*`>::allocate`.
34
 
35
  ``` cpp
36
  packaged_task(packaged_task&& rhs) noexcept;
37
  ```
38
 
39
- *Effects:* Constructs a new `packaged_task` object and transfers
40
- ownership of `rhs`’s shared state to `*this`, leaving `rhs` with no
41
- shared state. Moves the stored task from `rhs` to `*this`.
42
 
43
- *Postconditions:* `rhs` has no shared state.
44
 
45
  ``` cpp
46
  packaged_task& operator=(packaged_task&& rhs) noexcept;
47
  ```
48
 
49
  *Effects:*
50
 
51
- - Releases any shared state ([[futures.state]]);
52
  - calls `packaged_task(std::move(rhs)).swap(*this)`.
53
 
54
  ``` cpp
55
  ~packaged_task();
56
  ```
57
 
58
- *Effects:* Abandons any shared state ([[futures.state]]).
59
 
60
  ``` cpp
61
  void swap(packaged_task& other) noexcept;
62
  ```
63
 
64
  *Effects:* Exchanges the shared states and stored tasks of `*this` and
65
  `other`.
66
 
67
- *Postconditions:* `*this` has the same shared state and stored task (if
68
- any) as `other` prior to the call to `swap`. `other` has the same shared
69
- state and stored task (if any) as `*this` prior to the call to `swap`.
70
 
71
  ``` cpp
72
  bool valid() const noexcept;
73
  ```
74
 
@@ -79,11 +73,18 @@ future<R> get_future();
79
  ```
80
 
81
  *Returns:* A `future` object that shares the same shared state as
82
  `*this`.
83
 
84
- *Throws:* a `future_error` object if an error occurs.
 
 
 
 
 
 
 
85
 
86
  *Error conditions:*
87
 
88
  - `future_already_retrieved` if `get_future` has already been called on
89
  a `packaged_task` object with the same shared state as `*this`.
@@ -91,19 +92,19 @@ future<R> get_future();
91
 
92
  ``` cpp
93
  void operator()(ArgTypes... args);
94
  ```
95
 
96
- *Effects:* As if by *INVOKE*\<R\>(f, t1, t2, ..., tN), where `f` is the
97
- stored task of `*this` and `t1, t2, ..., tN` are the values in
98
- `args...`. If the task returns normally, the return value is stored as
99
- the asynchronous result in the shared state of `*this`, otherwise the
100
- exception thrown by the task is stored. The shared state of `*this` is
101
- made ready, and any threads blocked in a function waiting for the shared
102
- state of `*this` to become ready are unblocked.
103
 
104
- *Throws:* a `future_error` exception object if there is no shared state
105
  or the stored task has already been invoked.
106
 
107
  *Error conditions:*
108
 
109
  - `promise_already_satisfied` if the stored task has already been
@@ -112,19 +113,19 @@ or the stored task has already been invoked.
112
 
113
  ``` cpp
114
  void make_ready_at_thread_exit(ArgTypes... args);
115
  ```
116
 
117
- *Effects:* As if by *INVOKE*\<R\>(f, t1, t2, ..., tN), where `f` is the
118
- stored task and `t1, t2, ..., tN` are the values in `args...`. If the
119
- task returns normally, the return value is stored as the asynchronous
120
- result in the shared state of `*this`, otherwise the exception thrown by
121
- the task is stored. In either case, this shall be done without making
122
- that state ready ([[futures.state]]) immediately. Schedules the shared
123
- state to be made ready when the current thread exits, after all objects
124
- of thread storage duration associated with the current thread have been
125
- destroyed.
126
 
127
  *Throws:* `future_error` if an error condition occurs.
128
 
129
  *Error conditions:*
130
 
@@ -137,12 +138,12 @@ void reset();
137
  ```
138
 
139
  *Effects:* As if `*this = packaged_task(std::move(f))`, where `f` is the
140
  task stored in `*this`.
141
 
142
- [*Note 1*: This constructs a new shared state for `*this`. The old
143
- state is abandoned ([[futures.state]]). — *end note*]
144
 
145
  *Throws:*
146
 
147
  - `bad_alloc` if memory for the new shared state could not be allocated.
148
  - any exception thrown by the move constructor of the task stored in the
 
1
+ #### Member functions <a id="futures.task.members">[[futures.task.members]]</a>
2
 
3
  ``` cpp
4
  packaged_task() noexcept;
5
  ```
6
 
7
+ *Effects:* The object has no shared state and no stored task.
 
8
 
9
  ``` cpp
10
  template<class F>
11
  packaged_task(F&& f);
12
  ```
13
 
14
+ *Constraints:* `remove_cvref_t<F>` is not the same type as
15
+ `packaged_task<R(ArgTypes...)>`.
16
+
17
+ *Mandates:* `is_invocable_r_v<R, F&, ArgTypes...>` is `true`.
18
+
19
+ *Preconditions:* Invoking a copy of `f` behaves the same as invoking
20
  `f`.
21
 
 
 
 
22
  *Effects:* Constructs a new `packaged_task` object with a shared state
23
  and initializes the object’s stored task with `std::forward<F>(f)`.
24
 
25
+ *Throws:* Any exceptions thrown by the copy or move constructor of `f`,
26
+ or `bad_alloc` if memory for the internal data structures could not be
27
+ allocated.
 
 
 
 
 
28
 
29
  ``` cpp
30
  packaged_task(packaged_task&& rhs) noexcept;
31
  ```
32
 
33
+ *Effects:* Transfers ownership of `rhs`’s shared state to `*this`,
34
+ leaving `rhs` with no shared state. Moves the stored task from `rhs` to
35
+ `*this`.
36
 
37
+ *Ensures:* `rhs` has no shared state.
38
 
39
  ``` cpp
40
  packaged_task& operator=(packaged_task&& rhs) noexcept;
41
  ```
42
 
43
  *Effects:*
44
 
45
+ - Releases any shared state [[futures.state]];
46
  - calls `packaged_task(std::move(rhs)).swap(*this)`.
47
 
48
  ``` cpp
49
  ~packaged_task();
50
  ```
51
 
52
+ *Effects:* Abandons any shared state [[futures.state]].
53
 
54
  ``` cpp
55
  void swap(packaged_task& other) noexcept;
56
  ```
57
 
58
  *Effects:* Exchanges the shared states and stored tasks of `*this` and
59
  `other`.
60
 
61
+ *Ensures:* `*this` has the same shared state and stored task (if any) as
62
+ `other` prior to the call to `swap`. `other` has the same shared state
63
+ and stored task (if any) as `*this` prior to the call to `swap`.
64
 
65
  ``` cpp
66
  bool valid() const noexcept;
67
  ```
68
 
 
73
  ```
74
 
75
  *Returns:* A `future` object that shares the same shared state as
76
  `*this`.
77
 
78
+ *Synchronization:* Calls to this function do not introduce data
79
+ races  [[intro.multithread]] with calls to `operator()` or
80
+ `make_ready_at_thread_exit`.
81
+
82
+ [*Note 1*: Such calls need not synchronize with each
83
+ other. — *end note*]
84
+
85
+ *Throws:* A `future_error` object if an error occurs.
86
 
87
  *Error conditions:*
88
 
89
  - `future_already_retrieved` if `get_future` has already been called on
90
  a `packaged_task` object with the same shared state as `*this`.
 
92
 
93
  ``` cpp
94
  void operator()(ArgTypes... args);
95
  ```
96
 
97
+ *Effects:* As if by *INVOKE*\<R\>(f, t₁, t₂, …, t$_N$) [[func.require]],
98
+ where `f` is the stored task of `*this` and `t`₁`, t`₂`, `…`, t`$_N$ are
99
+ the values in `args...`. If the task returns normally, the return value
100
+ is stored as the asynchronous result in the shared state of `*this`,
101
+ otherwise the exception thrown by the task is stored. The shared state
102
+ of `*this` is made ready, and any threads blocked in a function waiting
103
+ for the shared state of `*this` to become ready are unblocked.
104
 
105
+ *Throws:* A `future_error` exception object if there is no shared state
106
  or the stored task has already been invoked.
107
 
108
  *Error conditions:*
109
 
110
  - `promise_already_satisfied` if the stored task has already been
 
113
 
114
  ``` cpp
115
  void make_ready_at_thread_exit(ArgTypes... args);
116
  ```
117
 
118
+ *Effects:* As if by *INVOKE*\<R\>(f, t₁, t₂, …, t$_N$) [[func.require]],
119
+ where `f` is the stored task and `t`₁`, t`₂`, `…`, t`$_N$ are the values
120
+ in `args...`. If the task returns normally, the return value is stored
121
+ as the asynchronous result in the shared state of `*this`, otherwise the
122
+ exception thrown by the task is stored. In either case, this is done
123
+ without making that state ready [[futures.state]] immediately. Schedules
124
+ the shared state to be made ready when the current thread exits, after
125
+ all objects of thread storage duration associated with the current
126
+ thread have been destroyed.
127
 
128
  *Throws:* `future_error` if an error condition occurs.
129
 
130
  *Error conditions:*
131
 
 
138
  ```
139
 
140
  *Effects:* As if `*this = packaged_task(std::move(f))`, where `f` is the
141
  task stored in `*this`.
142
 
143
+ [*Note 2*: This constructs a new shared state for `*this`. The old
144
+ state is abandoned [[futures.state]]. — *end note*]
145
 
146
  *Throws:*
147
 
148
  - `bad_alloc` if memory for the new shared state could not be allocated.
149
  - any exception thrown by the move constructor of the task stored in the