From Jason Turner

[futures.promise]

C++17 → C++20 5.3 KB 53 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/tmpark5v8cx/{from.md → to.md} +27 -18
tmp/tmpark5v8cx/{from.md → to.md} RENAMED
@@ -7,16 +7,16 @@ namespace std {
7
  public:
8
  promise();
9
  template<class Allocator>
10
  promise(allocator_arg_t, const Allocator& a);
11
  promise(promise&& rhs) noexcept;
12
- promise(const promise& rhs) = delete;
13
  ~promise();
14
 
15
  // assignment
16
  promise& operator=(promise&& rhs) noexcept;
17
- promise& operator=(const promise& rhs) = delete;
18
  void swap(promise& other) noexcept;
19
 
20
  // retrieving the result
21
  future<R> get_future();
22
 
@@ -26,18 +26,20 @@ namespace std {
26
 
27
  // setting the result with deferred notification
28
  void set_value_at_thread_exit(see below);
29
  void set_exception_at_thread_exit(exception_ptr p);
30
  };
 
31
  template<class R>
32
  void swap(promise<R>& x, promise<R>& y) noexcept;
 
33
  template<class R, class Alloc>
34
  struct uses_allocator<promise<R>, Alloc>;
35
  }
36
  ```
37
 
38
- The implementation shall provide the template `promise` and two
39
  specializations, `promise<R&>` and `promise<{}void>`. These differ only
40
  in the argument type of the member functions `set_value` and
41
  `set_value_at_thread_exit`, as set out in their descriptions, below.
42
 
43
  The `set_value`, `set_exception`, `set_value_at_thread_exit`, and
@@ -49,62 +51,69 @@ the promise object.
49
  template<class R, class Alloc>
50
  struct uses_allocator<promise<R>, Alloc>
51
  : true_type { };
52
  ```
53
 
54
- *Requires:* `Alloc` shall be an Allocator ([[allocator.requirements]]).
 
55
 
56
  ``` cpp
57
  promise();
58
  template<class Allocator>
59
  promise(allocator_arg_t, const Allocator& a);
60
  ```
61
 
62
- *Effects:* constructs a `promise` object and a shared state. The second
63
- constructor uses the allocator `a` to allocate memory for the shared
64
- state.
65
 
66
  ``` cpp
67
  promise(promise&& rhs) noexcept;
68
  ```
69
 
70
- *Effects:* constructs a new `promise` object and transfers ownership of
71
- the shared state of `rhs` (if any) to the newly-constructed object.
72
 
73
- *Postconditions:* `rhs` has no shared state.
74
 
75
  ``` cpp
76
  ~promise();
77
  ```
78
 
79
- *Effects:* Abandons any shared state ([[futures.state]]).
80
 
81
  ``` cpp
82
  promise& operator=(promise&& rhs) noexcept;
83
  ```
84
 
85
- *Effects:* Abandons any shared state ([[futures.state]]) and then as if
86
  `promise(std::move(rhs)).swap(*this)`.
87
 
88
  *Returns:* `*this`.
89
 
90
  ``` cpp
91
  void swap(promise& other) noexcept;
92
  ```
93
 
94
  *Effects:* Exchanges the shared state of `*this` and `other`.
95
 
96
- *Postconditions:* `*this` has the shared state (if any) that `other` had
97
- prior to the call to `swap`. `other` has the shared state (if any) that
98
  `*this` had prior to the call to `swap`.
99
 
100
  ``` cpp
101
  future<R> get_future();
102
  ```
103
 
104
  *Returns:* A `future<R>` object with the same shared state as `*this`.
105
 
 
 
 
 
 
 
 
106
  *Throws:* `future_error` if `*this` has no shared state or if
107
  `get_future` has already been called on a `promise` with the same shared
108
  state as `*this`.
109
 
110
  *Error conditions:*
@@ -119,11 +128,11 @@ void promise::set_value(R&& r);
119
  void promise<R&>::set_value(R& r);
120
  void promise<void>::set_value();
121
  ```
122
 
123
  *Effects:* Atomically stores the value `r` in the shared state and makes
124
- that state ready ([[futures.state]]).
125
 
126
  *Throws:*
127
 
128
  - `future_error` if its shared state already has a stored value or
129
  exception, or
@@ -140,14 +149,14 @@ that state ready ([[futures.state]]).
140
 
141
  ``` cpp
142
  void set_exception(exception_ptr p);
143
  ```
144
 
145
- *Requires:* `p` is not null.
146
 
147
  *Effects:* Atomically stores the exception pointer `p` in the shared
148
- state and makes that state ready ([[futures.state]]).
149
 
150
  *Throws:* `future_error` if its shared state already has a stored value
151
  or exception.
152
 
153
  *Error conditions:*
@@ -185,11 +194,11 @@ associated with the current thread have been destroyed.
185
 
186
  ``` cpp
187
  void set_exception_at_thread_exit(exception_ptr p);
188
  ```
189
 
190
- *Requires:* `p` is not null.
191
 
192
  *Effects:* Stores the exception pointer `p` in the shared state without
193
  making that state ready immediately. Schedules that state to be made
194
  ready when the current thread exits, after all objects of thread storage
195
  duration associated with the current thread have been destroyed.
 
7
  public:
8
  promise();
9
  template<class Allocator>
10
  promise(allocator_arg_t, const Allocator& a);
11
  promise(promise&& rhs) noexcept;
12
+ promise(const promise&) = delete;
13
  ~promise();
14
 
15
  // assignment
16
  promise& operator=(promise&& rhs) noexcept;
17
+ promise& operator=(const promise&) = delete;
18
  void swap(promise& other) noexcept;
19
 
20
  // retrieving the result
21
  future<R> get_future();
22
 
 
26
 
27
  // setting the result with deferred notification
28
  void set_value_at_thread_exit(see below);
29
  void set_exception_at_thread_exit(exception_ptr p);
30
  };
31
+
32
  template<class R>
33
  void swap(promise<R>& x, promise<R>& y) noexcept;
34
+
35
  template<class R, class Alloc>
36
  struct uses_allocator<promise<R>, Alloc>;
37
  }
38
  ```
39
 
40
+ The implementation provides the template `promise` and two
41
  specializations, `promise<R&>` and `promise<{}void>`. These differ only
42
  in the argument type of the member functions `set_value` and
43
  `set_value_at_thread_exit`, as set out in their descriptions, below.
44
 
45
  The `set_value`, `set_exception`, `set_value_at_thread_exit`, and
 
51
  template<class R, class Alloc>
52
  struct uses_allocator<promise<R>, Alloc>
53
  : true_type { };
54
  ```
55
 
56
+ *Preconditions:* `Alloc` meets the *Cpp17Allocator* requirements
57
+ ([[cpp17.allocator]]).
58
 
59
  ``` cpp
60
  promise();
61
  template<class Allocator>
62
  promise(allocator_arg_t, const Allocator& a);
63
  ```
64
 
65
+ *Effects:* Creates a shared state. The second constructor uses the
66
+ allocator `a` to allocate memory for the shared state.
 
67
 
68
  ``` cpp
69
  promise(promise&& rhs) noexcept;
70
  ```
71
 
72
+ *Effects:* Transfers ownership of the shared state of `rhs` (if any) to
73
+ the newly-constructed object.
74
 
75
+ *Ensures:* `rhs` has no shared state.
76
 
77
  ``` cpp
78
  ~promise();
79
  ```
80
 
81
+ *Effects:* Abandons any shared state [[futures.state]].
82
 
83
  ``` cpp
84
  promise& operator=(promise&& rhs) noexcept;
85
  ```
86
 
87
+ *Effects:* Abandons any shared state [[futures.state]] and then as if
88
  `promise(std::move(rhs)).swap(*this)`.
89
 
90
  *Returns:* `*this`.
91
 
92
  ``` cpp
93
  void swap(promise& other) noexcept;
94
  ```
95
 
96
  *Effects:* Exchanges the shared state of `*this` and `other`.
97
 
98
+ *Ensures:* `*this` has the shared state (if any) that `other` had prior
99
+ to the call to `swap`. `other` has the shared state (if any) that
100
  `*this` had prior to the call to `swap`.
101
 
102
  ``` cpp
103
  future<R> get_future();
104
  ```
105
 
106
  *Returns:* A `future<R>` object with the same shared state as `*this`.
107
 
108
+ *Synchronization:* Calls to this function do not introduce data
109
+ races  [[intro.multithread]] with calls to `set_value`, `set_exception`,
110
+ `set_value_at_thread_exit`, or `set_exception_at_thread_exit`.
111
+
112
+ [*Note 1*: Such calls need not synchronize with each
113
+ other. — *end note*]
114
+
115
  *Throws:* `future_error` if `*this` has no shared state or if
116
  `get_future` has already been called on a `promise` with the same shared
117
  state as `*this`.
118
 
119
  *Error conditions:*
 
128
  void promise<R&>::set_value(R& r);
129
  void promise<void>::set_value();
130
  ```
131
 
132
  *Effects:* Atomically stores the value `r` in the shared state and makes
133
+ that state ready [[futures.state]].
134
 
135
  *Throws:*
136
 
137
  - `future_error` if its shared state already has a stored value or
138
  exception, or
 
149
 
150
  ``` cpp
151
  void set_exception(exception_ptr p);
152
  ```
153
 
154
+ *Preconditions:* `p` is not null.
155
 
156
  *Effects:* Atomically stores the exception pointer `p` in the shared
157
+ state and makes that state ready [[futures.state]].
158
 
159
  *Throws:* `future_error` if its shared state already has a stored value
160
  or exception.
161
 
162
  *Error conditions:*
 
194
 
195
  ``` cpp
196
  void set_exception_at_thread_exit(exception_ptr p);
197
  ```
198
 
199
+ *Preconditions:* `p` is not null.
200
 
201
  *Effects:* Stores the exception pointer `p` in the shared state without
202
  making that state ready immediately. Schedules that state to be made
203
  ready when the current thread exits, after all objects of thread storage
204
  duration associated with the current thread have been destroyed.