From Jason Turner

[futures.shared_future]

C++14 → C++17 7.3 KB 78 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/tmp6t78yo7z/{from.md → to.md} +39 -32
tmp/tmp6t78yo7z/{from.md → to.md} RENAMED
@@ -8,31 +8,35 @@ can be created by conversion from a `future` object and shares its
8
  shared state with the original asynchronous provider (
9
  [[futures.state]]) of the shared state. The result (value or exception)
10
  of a `shared_future` object can be set by calling a respective function
11
  on an object that shares the same shared state.
12
 
13
- Member functions of `shared_future` do not synchronize with themselves,
14
- but they synchronize with the shared shared state.
15
 
16
  The effect of calling any member function other than the destructor, the
17
- move-assignment operator, or `valid()` on a `shared_future` object for
18
- which `valid() ==
19
- false` is undefined. Implementations are encouraged to detect this case
20
- and throw an object of type `future_error` with an error condition of
21
- `future_errc::no_state`.
 
 
 
 
22
 
23
  ``` cpp
24
  namespace std {
25
  template <class R>
26
  class shared_future {
27
  public:
28
  shared_future() noexcept;
29
- shared_future(const shared_future& rhs);
30
  shared_future(future<R>&&) noexcept;
31
  shared_future(shared_future&& rhs) noexcept;
32
  ~shared_future();
33
- shared_future& operator=(const shared_future& rhs);
34
  shared_future& operator=(shared_future&& rhs) noexcept;
35
 
36
  // retrieving the value
37
  see below get() const;
38
 
@@ -55,30 +59,30 @@ differ only in the return type and return value of the member function
55
 
56
  ``` cpp
57
  shared_future() noexcept;
58
  ```
59
 
60
- *Effects:* constructs an *empty* `shared_future` object that does not
61
  refer to a shared state.
62
 
63
- `valid() == false`.
64
 
65
  ``` cpp
66
- shared_future(const shared_future& rhs);
67
  ```
68
 
69
- *Effects:* constructs a `shared_future` object that refers to the same
70
  shared state as `rhs` (if any).
71
 
72
- `valid()` returns the same value as `rhs.valid()`.
73
 
74
  ``` cpp
75
  shared_future(future<R>&& rhs) noexcept;
76
  shared_future(shared_future&& rhs) noexcept;
77
  ```
78
 
79
- *Effects:* move constructs a `shared_future` object that refers to the
80
  shared state that was originally referred to by `rhs` (if any).
81
 
82
  *Postconditions:*
83
 
84
  - `valid()` returns the same value as `rhs.valid()` returned prior to
@@ -89,64 +93,67 @@ shared state that was originally referred to by `rhs` (if any).
89
  ~shared_future();
90
  ```
91
 
92
  *Effects:*
93
 
94
- - releases any shared state ([[futures.state]]);
95
  - destroys `*this`.
96
 
97
  ``` cpp
98
  shared_future& operator=(shared_future&& rhs) noexcept;
99
  ```
100
 
101
  *Effects:*
102
 
103
- - releases any shared state ([[futures.state]]);
104
  - move assigns the contents of `rhs` to `*this`.
105
 
106
  *Postconditions:*
107
 
108
  - `valid()` returns the same value as `rhs.valid()` returned prior to
109
  the assignment.
110
  - `rhs.valid() == false`.
111
 
112
  ``` cpp
113
- shared_future& operator=(const shared_future& rhs);
114
  ```
115
 
116
  *Effects:*
117
 
118
- - releases any shared state ([[futures.state]]);
119
- - assigns the contents of `rhs` to `*this`. As a result, `*this` refers
120
- to the same shared state as `rhs` (if any).
 
121
 
122
  *Postconditions:* `valid() == rhs.valid()`.
123
 
124
  ``` cpp
125
  const R& shared_future::get() const;
126
  R& shared_future<R&>::get() const;
127
  void shared_future<void>::get() const;
128
  ```
129
 
130
- *Note:* as described above, the template and its two required
131
  specializations differ only in the return type and return value of the
132
- member function `get`.
133
 
134
- *Note:* access to a value object stored in the shared state is
135
  unsynchronized, so programmers should apply only those operations on `R`
136
- that do not introduce a data race ([[intro.multithread]]).
 
137
 
138
  *Effects:* `wait()`s until the shared state is ready, then retrieves the
139
  value stored in the shared state.
140
 
141
  *Returns:*
142
 
143
  - `shared_future::get()` returns a const reference to the value stored
144
- in the object’s shared state. Access through that reference after the
145
- shared state has been destroyed produces undefined behavior; this can
146
- be avoided by not storing the reference in any storage with a greater
147
- lifetime than the `shared_future` object that returned the reference.
 
148
  - `shared_future<R&>::get()` returns the reference stored as value in
149
  the object’s shared state.
150
  - `shared_future<void>::get()` returns nothing.
151
 
152
  *Throws:* the stored exception, if an exception was stored in the shared
@@ -160,18 +167,18 @@ bool valid() const noexcept;
160
 
161
  ``` cpp
162
  void wait() const;
163
  ```
164
 
165
- *Effects:* blocks until the shared state is ready.
166
 
167
  ``` cpp
168
  template <class Rep, class Period>
169
  future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
170
  ```
171
 
172
- *Effects:* none if the shared state contains a deferred
173
  function ([[futures.async]]), otherwise blocks until the shared state
174
  is ready or until the relative timeout ([[thread.req.timing]])
175
  specified by `rel_time` has expired.
176
 
177
  *Returns:*
@@ -188,11 +195,11 @@ specified by `rel_time` has expired.
188
  ``` cpp
189
  template <class Clock, class Duration>
190
  future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
191
  ```
192
 
193
- *Effects:* none if the shared state contains a deferred
194
  function ([[futures.async]]), otherwise blocks until the shared state
195
  is ready or until the absolute timeout ([[thread.req.timing]])
196
  specified by `abs_time` has expired.
197
 
198
  *Returns:*
 
8
  shared state with the original asynchronous provider (
9
  [[futures.state]]) of the shared state. The result (value or exception)
10
  of a `shared_future` object can be set by calling a respective function
11
  on an object that shares the same shared state.
12
 
13
+ [*Note 1*: Member functions of `shared_future` do not synchronize with
14
+ themselves, but they synchronize with the shared state. — *end note*]
15
 
16
  The effect of calling any member function other than the destructor, the
17
+ move-assignment operator, the copy-assignment operator, or `valid()` on
18
+ a `shared_future` object for which `valid() == false` is undefined.
19
+
20
+ [*Note 2*: It is valid to copy or move from a `shared_future` object
21
+ for which `valid()` is `false`. — *end note*]
22
+
23
+ [*Note 3*: Implementations are encouraged to detect this case and throw
24
+ an object of type `future_error` with an error condition of
25
+ `future_errc::no_state`. — *end note*]
26
 
27
  ``` cpp
28
  namespace std {
29
  template <class R>
30
  class shared_future {
31
  public:
32
  shared_future() noexcept;
33
+ shared_future(const shared_future& rhs) noexcept;
34
  shared_future(future<R>&&) noexcept;
35
  shared_future(shared_future&& rhs) noexcept;
36
  ~shared_future();
37
+ shared_future& operator=(const shared_future& rhs) noexcept;
38
  shared_future& operator=(shared_future&& rhs) noexcept;
39
 
40
  // retrieving the value
41
  see below get() const;
42
 
 
59
 
60
  ``` cpp
61
  shared_future() noexcept;
62
  ```
63
 
64
+ *Effects:* Constructs an *empty* `shared_future` object that does not
65
  refer to a shared state.
66
 
67
+ *Postconditions:* `valid() == false`.
68
 
69
  ``` cpp
70
+ shared_future(const shared_future& rhs) noexcept;
71
  ```
72
 
73
+ *Effects:* Constructs a `shared_future` object that refers to the same
74
  shared state as `rhs` (if any).
75
 
76
+ *Postconditions:* `valid()` returns the same value as `rhs.valid()`.
77
 
78
  ``` cpp
79
  shared_future(future<R>&& rhs) noexcept;
80
  shared_future(shared_future&& rhs) noexcept;
81
  ```
82
 
83
+ *Effects:* Move constructs a `shared_future` object that refers to the
84
  shared state that was originally referred to by `rhs` (if any).
85
 
86
  *Postconditions:*
87
 
88
  - `valid()` returns the same value as `rhs.valid()` returned prior to
 
93
  ~shared_future();
94
  ```
95
 
96
  *Effects:*
97
 
98
+ - Releases any shared state ([[futures.state]]);
99
  - destroys `*this`.
100
 
101
  ``` cpp
102
  shared_future& operator=(shared_future&& rhs) noexcept;
103
  ```
104
 
105
  *Effects:*
106
 
107
+ - Releases any shared state ([[futures.state]]);
108
  - move assigns the contents of `rhs` to `*this`.
109
 
110
  *Postconditions:*
111
 
112
  - `valid()` returns the same value as `rhs.valid()` returned prior to
113
  the assignment.
114
  - `rhs.valid() == false`.
115
 
116
  ``` cpp
117
+ shared_future& operator=(const shared_future& rhs) noexcept;
118
  ```
119
 
120
  *Effects:*
121
 
122
+ - Releases any shared state ([[futures.state]]);
123
+ - assigns the contents of `rhs` to `*this`. \[*Note 4*: As a result,
124
+ `*this` refers to the same shared state as `rhs` (if
125
+ any). — *end note*]
126
 
127
  *Postconditions:* `valid() == rhs.valid()`.
128
 
129
  ``` cpp
130
  const R& shared_future::get() const;
131
  R& shared_future<R&>::get() const;
132
  void shared_future<void>::get() const;
133
  ```
134
 
135
+ [*Note 1*: As described above, the template and its two required
136
  specializations differ only in the return type and return value of the
137
+ member function `get`. — *end note*]
138
 
139
+ [*Note 2*: Access to a value object stored in the shared state is
140
  unsynchronized, so programmers should apply only those operations on `R`
141
+ that do not introduce a data
142
+ race ([[intro.multithread]]). — *end note*]
143
 
144
  *Effects:* `wait()`s until the shared state is ready, then retrieves the
145
  value stored in the shared state.
146
 
147
  *Returns:*
148
 
149
  - `shared_future::get()` returns a const reference to the value stored
150
+ in the object’s shared state. \[*Note 5*: Access through that
151
+ reference after the shared state has been destroyed produces undefined
152
+ behavior; this can be avoided by not storing the reference in any
153
+ storage with a greater lifetime than the `shared_future` object that
154
+ returned the reference. — *end note*]
155
  - `shared_future<R&>::get()` returns the reference stored as value in
156
  the object’s shared state.
157
  - `shared_future<void>::get()` returns nothing.
158
 
159
  *Throws:* the stored exception, if an exception was stored in the shared
 
167
 
168
  ``` cpp
169
  void wait() const;
170
  ```
171
 
172
+ *Effects:* Blocks until the shared state is ready.
173
 
174
  ``` cpp
175
  template <class Rep, class Period>
176
  future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
177
  ```
178
 
179
+ *Effects:* None if the shared state contains a deferred
180
  function ([[futures.async]]), otherwise blocks until the shared state
181
  is ready or until the relative timeout ([[thread.req.timing]])
182
  specified by `rel_time` has expired.
183
 
184
  *Returns:*
 
195
  ``` cpp
196
  template <class Clock, class Duration>
197
  future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
198
  ```
199
 
200
+ *Effects:* None if the shared state contains a deferred
201
  function ([[futures.async]]), otherwise blocks until the shared state
202
  is ready or until the absolute timeout ([[thread.req.timing]])
203
  specified by `abs_time` has expired.
204
 
205
  *Returns:*