31 Thread support library [thread]

31.6 Futures [futures]

31.6.8 Class template shared_­future [futures.shared_future]

1
#
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.
2
#
[ Note
:
Member functions of shared_­future do not synchronize with themselves, but they synchronize with the shared state.
— end note
 ]
3
#
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
:
It is valid to copy or move from a shared_­future object for which valid() is false.
— end note
 ]
[ Note
:
Implementations should detect this case and throw an object of type future_­error with an error condition of future_­errc::no_­state.
— end note
 ]
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;
  };
}
4
#
The implementation shall provide 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;
5
#
Effects: Constructs an empty shared_­future object that does not refer to a shared state.
6
#
Ensures: valid() == false.
🔗
shared_future(const shared_future& rhs) noexcept;
7
#
Effects: Constructs a shared_­future object that refers to the same shared state as rhs (if any).
8
#
Ensures: valid() returns the same value as rhs.valid().
🔗
shared_future(future<R>&& rhs) noexcept; shared_future(shared_future&& rhs) noexcept;
9
#
Effects: Move constructs a shared_­future object that refers to the shared state that was originally referred to by rhs (if any).
10
#
Ensures:
  • (10.1)
    valid() returns the same value as rhs.valid() returned prior to the constructor invocation.
  • (10.2)
    rhs.valid() == false.
🔗
~shared_future();
11
#
Effects:
🔗
shared_future& operator=(shared_future&& rhs) noexcept;
12
#
Effects:
13
#
Ensures:
  • (13.1)
    valid() returns the same value as rhs.valid() returned prior to the assignment.
  • (13.2)
    rhs.valid() == false.
🔗
shared_future& operator=(const shared_future& rhs) noexcept;
14
#
Effects:
  • (14.1)
    Releases any shared state ([futures.state]);
  • (14.2)
    assigns the contents of rhs to *this.
    [ Note
    :
    As a result, *this refers to the same shared state as rhs (if any).
    — end note
     ]
15
#
Ensures: valid() == rhs.valid().
🔗
const R& shared_future::get() const; R& shared_future<R&>::get() const; void shared_future<void>::get() const;
16
#
[ Note
:
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
 ]
17
#
[ Note
:
Access to a value object stored in the shared state is unsynchronized, so programmers should apply only those operations on R that do not introduce a data race ([intro.multithread]).
— end note
 ]
18
#
Effects: wait()s until the shared state is ready, then retrieves the value stored in the shared state.
19
#
Returns:
  • (19.1)
    shared_­future::get() returns a const reference to the value stored in the object's shared state.
    [ Note
    :
    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
     ]
  • (19.2)
    shared_­future<R&>::get() returns the reference stored as value in the object's shared state.
  • (19.3)
    shared_­future<void>::get() returns nothing.
20
#
Throws: The stored exception, if an exception was stored in the shared state.
🔗
bool valid() const noexcept;
21
#
Returns: true only if *this refers to a shared state.
🔗
void wait() const;
22
#
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;
23
#
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.
24
#
Returns:
  • (24.1)
    future_­status::deferred if the shared state contains a deferred function.
  • (24.2)
    future_­status::ready if the shared state is ready.
  • (24.3)
    future_­status::timeout if the function is returning because the relative timeout ([thread.req.timing]) specified by rel_­time has expired.
25
#
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;
26
#
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.
27
#
Returns:
  • (27.1)
    future_­status::deferred if the shared state contains a deferred function.
  • (27.2)
    future_­status::ready if the shared state is ready.
  • (27.3)
    future_­status::timeout if the function is returning because the absolute timeout ([thread.req.timing]) specified by abs_­time has expired.
28
#
Throws: timeout-related exceptions ([thread.req.timing]).