[futures.shared.future] (original) (raw)

32 Concurrency support library [thread]

32.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_futureobject 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, orvalid() on a shared_future object for which valid() == false is undefined.

[Note 2:

It is valid to copy or move from a shared_futureobject for which valid() is false.

— _end note_]

Recommended practice: Implementations should detect this case and throw an object of typefuture_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;see below get() const;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.

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

Postconditions: valid() == false.

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

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

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

Postconditions:

• valid() returns the same value as rhs.valid() returned prior to the constructor invocation.

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

Otherwise:

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

Postconditions:

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

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

Otherwise:

• Releases any shared state ([futures.state]);
• 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().

[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:

• 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_]
• shared_future<R&>​::​get() returns the reference stored as value in the object's shared state.
• shared_future<void>​::​get() returns nothing.

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

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

Effects: Blocks until the shared state is ready.

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

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