33 Concurrency support library [thread]

33.10 Futures [futures]

33.10.8 Class template shared_future [futures.shared.future]

The class template shared_future defines a type for asynchronous return objects which may share their shared state with other asynchronous return objects.

A default-constructed shared_future object has no shared state.

A shared_future object with shared state can be created by conversion from a future object and shares its shared state with the original asynchronous provider of the shared state.

The result (value or exception) of a shared_future object can be set by calling a respective function on an object that shares the same shared state.

[Note 1:

Member functions of shared_future do not synchronize with themselves, but they synchronize with the shared state.

— end note]

The effect of calling any member function other than the destructor, the move-assignment operator, the copy-assignment operator, or valid() on a shared_future object for which valid() == false is undefined.

[Note 2:

It is valid to copy or move from a shared_future object for which valid() is 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 shared_future { public: shared_future() noexcept; shared_future(const shared_future& rhs) noexcept; shared_future(future<R>&&) noexcept; shared_future(shared_future&& rhs) noexcept; ~shared_future(); shared_future& operator=(const shared_future& rhs) noexcept; shared_future& operator=(shared_future&& rhs) noexcept; // retrieving the value see below get() const; // 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 shared_future and two specializations, shared_future<R&> and shared_future<void>.

These differ only in the return type and return value of the member function get, as set out in its description, below.

🔗

shared_future() noexcept;

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

Postconditions: valid() == false.

🔗

shared_future(const shared_future& rhs) noexcept;

Effects: The object refers to the same shared state as rhs (if any).

Postconditions: valid() returns the same value as rhs.valid().

🔗

shared_future(future<R>&& rhs) noexcept;
shared_future(shared_future&& rhs) noexcept;

Effects: Move constructs a shared_future object that refers to the shared state that was originally referred to by rhs (if any).

Postconditions:

(11.1)
valid() returns the same value as rhs.valid() returned prior to the constructor invocation.
(11.2)
rhs.valid() == false.

🔗

~shared_future();

Effects:

(12.1)
Releases any shared state ([futures.state]);
(12.2)
destroys *this.

🔗

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

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

Otherwise:

(13.1)
Releases any shared state ([futures.state]);
(13.2)
move assigns the contents of rhs to *this.

Postconditions:

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

🔗

shared_future& operator=(const shared_future& rhs) noexcept;

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

Otherwise:

(15.1)
Releases any shared state ([futures.state]);
(15.2)
assigns the contents of rhs to *this.
[Note 3:
As a result, *this refers to the same shared state as rhs (if any).
— end note]

Postconditions: valid() == rhs.valid().

🔗

const R& shared_future::get() const;
R& shared_future<R&>::get() const;
void shared_future<void>::get() const;

[Note 4:

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]

[Note 5:

Access to a value object stored in the shared state is unsynchronized, so operations on R might introduce a data race ([intro.multithread]).

— end note]

Effects: wait()s until the shared state is ready, then retrieves the value stored in the shared state.

Returns:

(20.1)
shared_future::get() returns a const reference to the value stored in the object's shared state.

[Note 6:
Access through that reference after the shared state has been destroyed produces undefined behavior; this can be avoided by not storing the reference in any storage with a greater lifetime than the shared_future object that returned the reference.
— end note]
(20.2)
shared_future<R&>::get() returns the reference stored as value in the object's shared state.
(20.3)
shared_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:

(25.1)
future_status::deferred if the shared state contains a deferred function.
(25.2)
future_status::ready if the shared state is ready.
(25.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:

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