[futures.unique.future] - C++17 → C++20

Files changed (1) hide show

tmp/tmp6z_bb8ei/{from.md → to.md} +194 -0

tmp/tmp6z_bb8ei/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,194 @@

+### Class template `future` <a id="futures.unique.future">[[futures.unique.future]]</a>
+The class template `future` defines a type for asynchronous return
+objects which do not share their shared state with other asynchronous
+return objects. A default-constructed `future` object has no shared
+state. A `future` object with shared state can be created by functions
+on asynchronous providers [[futures.state]] or by the move constructor
+and shares its shared state with the original asynchronous provider. The
+result (value or exception) of a `future` object can be set by calling a
+respective function on an object that shares the same shared state.
+[*Note 1*: Member functions of `future` do not synchronize with
+themselves or with member functions of `shared_future`. — *end note*]
+The effect of calling any member function other than the destructor, the
+move-assignment operator, `share`, or `valid` on a `future` object for
+which `valid() == false` is undefined.
+[*Note 2*: It is valid to move from a future object for which
+`valid() == false`. — *end note*]
+[*Note 3*: Implementations should detect this case and throw an object
+of type `future_error` with an error condition of
+`future_errc::no_state`. — *end note*]
+``` cpp
+namespace std {
+  template<class R>
+  class future {
+  public:
+    future() noexcept;
+    future(future&&) noexcept;
+    future(const future&) = delete;
+    ~future();
+    future& operator=(const future&) = delete;
+    future& operator=(future&&) noexcept;
+    shared_future<R> share() noexcept;
+    // retrieving the value
+    see below get();
+    // functions to check state
+    bool valid() const noexcept;
+    void wait() const;
+    template<class Rep, class Period>
+      future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
+    template<class Clock, class Duration>
+      future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
+  };
+}
+```
+The implementation provides the template `future` and two
+specializations, `future<R&>` and `future<{}void>`. These differ only in
+the return type and return value of the member function `get`, as set
+out in its description, below.
+``` cpp
+future() noexcept;
+```
+*Effects:* The object does not refer to a shared state.
+*Ensures:* `valid() == false`.
+``` cpp
+future(future&& rhs) noexcept;
+```
+*Effects:* Move constructs a `future` object that refers to the shared
+state that was originally referred to by `rhs` (if any).
+*Ensures:*
+- `valid()` returns the same value as `rhs.valid()` prior to the
+  constructor invocation.
+- `rhs.valid() == false`.
+``` cpp
+~future();
+```
+*Effects:*
+- Releases any shared state [[futures.state]];
+- destroys `*this`.
+``` cpp
+future& operator=(future&& rhs) noexcept;
+```
+*Effects:*
+- Releases any shared state [[futures.state]].
+- move assigns the contents of `rhs` to `*this`.
+*Ensures:*
+- `valid()` returns the same value as `rhs.valid()` prior to the
+  assignment.
+- `rhs.valid() == false`.
+``` cpp
+shared_future<R> share() noexcept;
+```
+*Returns:* `shared_future<R>(std::move(*this))`.
+*Ensures:* `valid() == false`.
+``` cpp
+R future::get();
+R& future<R&>::get();
+void future<void>::get();
+```
+[*Note 1*: As described above, the template and its two required
+specializations differ only in the return type and return value of the
+member function `get`. — *end note*]
+*Effects:*
+- `wait()`s until the shared state is ready, then retrieves the value
+  stored in the shared state;
+- releases any shared state [[futures.state]].
+*Returns:*
+- `future::get()` returns the value `v` stored in the object’s shared
+  state as `std::move(v)`.
+- `future<R&>::get()` returns the reference stored as value in the
+  object’s shared state.
+- `future<void>::get()` returns nothing.
+*Throws:* The stored exception, if an exception was stored in the shared
+state.
+*Ensures:* `valid() == false`.
+``` cpp
+bool valid() const noexcept;
+```
+*Returns:* `true` only if `*this` refers to a shared state.
+``` cpp
+void wait() const;
+```
+*Effects:* Blocks until the shared state is ready.
+``` cpp
+template<class Rep, class Period>
+  future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
+```
+*Effects:* None if the shared state contains a deferred
+function [[futures.async]], otherwise blocks until the shared state is
+ready or until the relative timeout [[thread.req.timing]] specified by
+`rel_time` has expired.
+*Returns:*
+- `future_status::deferred` if the shared state contains a deferred
+  function.
+- `future_status::ready` if the shared state is ready.
+- `future_status::timeout` if the function is returning because the
+  relative timeout [[thread.req.timing]] specified by `rel_time` has
+  expired.
+*Throws:* timeout-related exceptions [[thread.req.timing]].
+``` cpp
+template<class Clock, class Duration>
+  future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
+```
+*Effects:* None if the shared state contains a deferred
+function [[futures.async]], otherwise blocks until the shared state is
+ready or until the absolute timeout [[thread.req.timing]] specified by
+`abs_time` has expired.
+*Returns:*
+- `future_status::deferred` if the shared state contains a deferred
+  function.
+- `future_status::ready` if the shared state is ready.
+- `future_status::timeout` if the function is returning because the
+  absolute timeout [[thread.req.timing]] specified by `abs_time` has
+  expired.
+*Throws:* timeout-related exceptions [[thread.req.timing]].

Diff to HTML by rtfpessoa