33 Concurrency support library [thread]

33.10 Futures [futures]

33.10.7 Class template future [futures.unique.future]

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]

Recommended practice: Implementations should detect this case and throw an object of type future_error with an error condition of future_errc::no_state.

🔗

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; }; }

For the primary template, R shall be an object type that meets the Cpp17Destructible requirements.

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.

🔗

future() noexcept;

Effects: The object does not refer to a shared state.

Postconditions: valid() == false.

🔗

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).

Postconditions:

(9.1)
valid() returns the same value as rhs.valid() prior to the constructor invocation.
(9.2)
rhs.valid() == false.

🔗

~future();

Effects:

(10.1)
Releases any shared state ([futures.state]);
(10.2)
destroys *this.

🔗

future& operator=(future&& rhs) noexcept;

Effects: If addressof(rhs) == this is true, there are no effects.

Otherwise:

(11.1)
Releases any shared state ([futures.state]).
(11.2)
move assigns the contents of rhs to *this.

Postconditions:

(12.1)
valid() returns the same value as rhs.valid() prior to the assignment.
(12.2)
If addressof(rhs) == this is false, rhs.valid() == false.

Postconditions: valid() == false.

Returns: shared_future<R>(std::move(*this)).

🔗

R future::get();
R& future<R&>::get();
void future<void>::get();

[Note 3:

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:

(16.1)
wait()s until the shared state is ready, then retrieves the value stored in the shared state;
(16.2)
releases any shared state ([futures.state]).

Postconditions: valid() == false.

Returns:

(18.1)
future::get() returns the value v stored in the object's shared state as std::move(v).
(18.2)
future<R&>::get() returns the reference stored as value in the object's shared state.
(18.3)
future<void>::get() returns nothing.

Throws: The stored exception, if an exception was stored in the shared state.

🔗

bool valid() const noexcept;

Returns: true only if *this refers to a shared state.

🔗

void wait() const;

Effects: Blocks until the shared state is ready.

🔗

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:

(23.1)
future_status::deferred if the shared state contains a deferred function.
(23.2)
future_status::ready if the shared state is ready.
(23.3)
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]).

🔗

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:

(26.1)
future_status::deferred if the shared state contains a deferred function.
(26.2)
future_status::ready if the shared state is ready.
(26.3)
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]).