future.html

<cxx-clause id="futures">
<h1> Improvements to <code>std::future&lt;T></code> and Related APIs</h1>

<cxx-section id="futures.general">
<h1>General</h1>
<p>

The extensions proposed here are an evolution of the functionality of
<code>std::future</code> and <code>std::shared_future</code>. The extensions
enable wait-free composition of asynchronous operations. Class templates
<code>std::promise</code> and <code>std::packaged_task</code> are also updated
to be compatible with the updated <code>std::future</code>.

</p>

</cxx-section>

  <cxx-section id="header.future.synop">
    <h1>Header &lt;experimental/future> synopsis</h1>

    <cxx-ednote>
      An additional editorial fix as in Fundamental v1 TS is applied in the declaration of <code>swap</code> for <code>packaged_task</code>
    </cxx-ednote>

    <pre><code>#include &lt;future&gt;

namespace std {
  namespace experimental {
  inline namespace concurrency_v1 {

    template &lt;class R&gt; class promise;
    template &lt;class R&gt; class promise&lt;R&amp;&gt;;
    template &lt;&gt; class promise&lt;void&gt;;

    template &lt;class R&gt;
      void swap(promise&lt;R&gt;&amp; x, promise&lt;R&gt;&amp; y) noexcept;

    template &lt;class R&gt; class future;
    template &lt;class R&gt; class future&lt;R&amp;&gt;;
    template &lt;&gt; class future&lt;void&gt;;
    template &lt;class R&gt; class shared_future;
    template &lt;class R&gt; class shared_future&lt;R&amp;&gt;;
    template &lt;&gt; class shared_future&lt;void&gt;;

    template &lt;class&gt; class packaged_task; // undefined
    template &lt;class R, class... ArgTypes&gt;
      class packaged_task&lt;R(ArgTypes...)&gt;;

    template &lt;class R, class... ArgTypes&gt;
      void swap(packaged_task&lt;R(ArgTypes...)&gt;&amp;, packaged_task&lt;R(ArgTypes...)&gt;&amp;) noexcept;

    template &lt;class T>
      <em>see below</em> make_ready_future(T&amp;&amp; value);
    future&lt;void> make_ready_future();

    template &lt;class T>
      future&lt;T> make_exceptional_future(exception_ptr ex);
    template &lt;class T, class E>
      future&lt;T&gt; make_exceptional_future(E ex);

    template &lt;class InputIterator>
      <em>see below</em> when_all(InputIterator first, InputIterator last);
    template &lt;class... Futures>
      <em>see below</em> when_all(Futures&amp;&amp;... futures);

    template &lt;class Sequence>
    struct when_any_result;

    template &lt;class InputIterator>
      <em>see below</em> when_any(InputIterator first, InputIterator last);
    template &lt;class... Futures>
      <em>see below</em> when_any(Futures&amp;&amp;... futures);

  } // namespace concurrency_v1
  } // namespace experimental

  template &lt;class R, class Alloc&gt;
    struct uses_allocator&lt;experimental::promise&lt;R&gt;, Alloc&gt;;

  template &lt;class R, class Alloc&gt;
    struct uses_allocator&lt;experimental::packaged_task&lt;R&gt;, Alloc&gt;;

} // namespace std</code></pre>
  </cxx-section>

<cxx-section id="futures.unique_future">
<h1>Class template <code>future</code></h1>

<p>
The specifications of all declarations within this subclause <cxx-ref to="futures.unique_future"></cxx-ref>
and its subclauses are the same as the corresponding declarations,
as specified in <cxx-ref in="cxx" to="futures.unique_future"></cxx-ref>,
unless explicitly specified otherwise.
</p>

    <pre><code>namespace std {
  namespace experimental {
  inline namespace concurrency_v1 {

    template &lt;class R&gt;
    class future {
    public:
      future() noexcept;
      future(future &amp;&amp;) noexcept;
      future(const future&amp;) = delete;
      future(future&lt;future&lt;R>>&amp;&amp;) noexcept;
      ~future();
      future&amp; operator=(const future&amp;) = delete;
      future&amp; operator=(future&amp;&amp;) noexcept;
      shared_future&lt;R&gt; share();

      // retrieving the value
      <em>see below</em> get();

      // functions to check state
      bool valid() const noexcept;
      bool is_ready() const;

      void wait() const;
      template &lt;class Rep, class Period&gt;
        future_status wait_for(const chrono::duration&lt;Rep, Period&gt;&amp; rel_time) const;
      template &lt;class Clock, class Duration&gt;
        future_status wait_until(const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time) const;

      // continuations
      template &lt;class F>
        <em>see below</em> then(F&amp;&amp; func);

    };

  } // namespace concurrency_v1
  } // namespace experimental
  } // namespace std</code></pre>

<cxx-function>
  <cxx-signature>future(future&lt;future&lt;R>>&amp;&amp; rhs) noexcept;</cxx-signature>
  <cxx-Effects>Constructs a <code>future</code> object from the shared state referred to by
  <code>rhs</code>.


The <code>future</code> becomes ready when one of the following occurs:
<ul>
  <li>
    Both the <code>rhs</code> and <code>rhs.get()</code> are ready. The value or the exception from <code>rhs.get()</code> is stored in the <code>future</code>'s shared state.
  </li>

  <li>
    <code>rhs</code> is ready but <code>rhs.get()</code> is invalid. An exception of type <code>std::future_error</code>, with an error condition of <code>std::future_errc::broken_promise</code> is stored in the <code>future</code>'s shared state.
  </li>
</ul>

</cxx-Effects>
  <cxx-postconditions>
      <ul>
      <li><code>valid() == true</code>.</li>
      <li><code>rhs.valid() == false</code>.</li>
    </ul>
  </cxx-postconditions>
</cxx-function>

<p>

The member function template <code>then</code> provides a mechanism for attaching
a <i>continuation</i> to a <code>future</code> object, which will be executed
as specified below.

</p>
<cxx-function>
<cxx-signature>
template &lt;class F>
<em>see below</em> then(F&amp;&amp; func);
</cxx-signature>

<cxx-requires><code><em>INVOKE</em>(<em>DECAY_COPY</em> (std::forward&lt;F>(func)), std::move(*this))</code> shall be a valid expression.</cxx-requires>

  <cxx-Effects>
    The function creates a shared state that is associated with the returned
    <code>future</code> object. Additionally,
    <ul>
      <li>
        When the object's shared state is ready, the continuation
        <code><em>INVOKE</em>(<em>DECAY_COPY</em>(std::forward&lt;F>(func)), std::move(*this))</code> is called on
        an unspecified thread of execution with the call to 
        <code><em>DECAY_COPY</em>()</code> being evaluated in the thread that called 
        <code>then</code>.
      </li>
      <li>
      Any value returned from the continuation is stored as the result in the
      shared state of the resulting <code>future</code>. Any exception propagated from the execution of
      the continuation is stored as the exceptional result in the shared state of the resulting <code>future</code>.
      </li>
    </ul>
  </cxx-Effects>

  <cxx-Returns>


        When <code>result_of_t&lt;decay_t&lt;F>(future&lt;R>)></code>
        is <code>future&lt;R2></code>, for some type <code>R2</code>, the function returns <code>future&lt;R2></code>.

        Otherwise, the function returns <code>future&lt;result_of_t&lt;decay_t&lt;F>(future&lt;R>)>></code>.

      <cxx-Note>
        The rule above is referred to as <em>implicit unwrapping</em>. Without this rule,
        the return type of <code>then</code> taking a callable returning a
        <code>future&lt;R></code> would have been <code>future&lt;future&lt;R>></code>.
        This rule avoids such nested <code>future</code> objects.
        The type of <code>f2</code> below is
          <code>future&lt;int></code> and not <code>future&lt;future&lt;int>></code>:
        <cxx-example>
<pre>
future&lt;int> f1 = g();
future&lt;int> f2 = f1.then([](future&lt;int> f) {
                    future&lt;int> f3 = h();
                    return f3;
                 });
</pre>
        </cxx-example>
        </cxx-Note>
      </li>
    </ul>
  </cxx-Returns>

  <cxx-Postconditions>
  <code>valid() == false</code> on the original <code>future</code>.
    <code>valid() == true</code> on the <code>future</code> returned from <code>then.</code>
    <cxx-Note>
      In case of implicit unwrapping, the validity of the <code>future</code> returned from
      <code>func</code> cannot be established until after the completion of the
      continuation. If it is not valid, the resulting <code>future</code>
      becomes ready with an exception of type <code>std::future_error</code>,
      with an error condition of <code>std::future_errc::broken_promise</code>.
    </cxx-Note>
  </cxx-Postconditions>
</cxx-function>

<cxx-function>
  <cxx-signature>bool is_ready() const;</cxx-signature>
  <cxx-Returns> <code>true</code> if the shared state is ready, otherwise <code>false</code>.</cxx-Returns>
</cxx-function>

</cxx-section>

<cxx-section id="futures.shared_future">
<h1>Class template <code>shared_future</code></h1>
<p>
The specifications of all declarations within this subclause <cxx-ref to="futures.shared_future"></cxx-ref>
and its subclauses are the same as the corresponding declarations,
as specified in <cxx-ref in="cxx" to="futures.shared_future"></cxx-ref>,
unless explicitly specified otherwise.
</p>

<pre>
  namespace std {
  namespace experimental {
  inline namespace concurrency_v1 {

    template &lt;class R&gt;
    class shared_future {
    public:
      shared_future() noexcept;
      shared_future(const shared_future&amp;) noexcept;
      shared_future(future&lt;R>&amp;&amp;) noexcept;
      shared_future(future&lt;shared_future&lt;R>>&amp;&amp; rhs) noexcept;
      ~shared_future();
      shared_future&amp; operator=(const shared_future&amp;);
      shared_future&amp; operator=(shared_future&amp;&amp;) noexcept;

      // retrieving the value
      <em>see below</em> get();

      // functions to check state
      bool valid() const noexcept;
      bool is_ready() const;

      void wait() const;
      template &lt;class Rep, class Period&gt;
        future_status wait_for(const chrono::duration&lt;Rep, Period&gt;&amp; rel_time) const;
      template &lt;class Clock, class Duration&gt;
        future_status wait_until(const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time) const;

      // continuations
      template &lt;class F>
        <em>see below</em> then(F&amp;&amp; func) const;
    };

  } // namespace concurrency_v1
  } // namespace experimental
  } // namespace std
</pre>

<cxx-function>
  <cxx-signature>shared_future(future&lt;shared_future&lt;R>>&amp;&amp; rhs) noexcept;</cxx-signature>

  <cxx-Effects>Constructs a <code>shared_future</code> object from the shared state referred to by
  <code>rhs</code>.

The <code>shared_future</code> becomes ready when one of the following occurs:
<ul>
  <li>
    Both the <code>rhs</code> and <code>rhs.get()</code> are ready. The value or the exception from <code>rhs.get()</code> is stored in the <code>shared_future</code>'s shared state.
  </li>

  <li>
    <code>rhs</code> is ready but <code>rhs.get()</code> is invalid.
    The <code>shared_future</code> stores an exception of type <code>std::future_error</code>, with an error condition of <code>std::future_errc::broken_promise</code>.
  </li>
</ul>

</cxx-Effects>
  <cxx-postconditions>
      <ul>
      <li><code>valid() == true</code>.</li>
      <li><code>rhs.valid() == false</code>.</li>
    </ul>
  </cxx-postconditions>
</cxx-function>

<p>
The member function template <code>then</code> provides a mechanism for attaching
a <i>continuation</i> to a <code>shared_future</code> object, which will be executed
as specified below.
</p>

<cxx-function>
<cxx-signature>
template &lt;class F>
<em>see below</em> then(F&amp;&amp; func) const;
</cxx-signature>

<cxx-requires><code><em>INVOKE</em>(<em>DECAY_COPY</em> (std::forward&lt;F>(func)), *this)</code> shall be a valid expression.</cxx-requires>

  <cxx-Effects>
    The function creates a shared state that is associated with the returned
    <code>future</code> object. Additionally,
    <ul>
      <li>
        When the object's shared state is ready, the continuation
        <code><em>INVOKE</em>(<em>DECAY_COPY</em>(std::forward&lt;F>(func)), *this)</code> is called on
        an unspecified thread of execution with the call to
        <code><em>DECAY_COPY</em>()</code> being evaluated in the thread that called 
        <code>then</code>.
      </li>
      <li>
      Any value returned from the continuation is stored as the result in the
      shared state of the resulting <code>future</code>. Any exception propagated from the execution of
      the continuation is stored as the exceptional result in the shared state of the resulting <code>future</code>.
      </li>
    </ul>
  </cxx-Effects>

  <cxx-Returns>

        When <code>result_of_t&lt;decay_t&lt;F>(const shared_future&amp;)></code>
        is <code>future&lt;R2></code>, for some type <code>R2</code>, the function returns <code>future&lt;R2></code>.

        Otherwise, the function returns <code>future&lt;result_of_t&lt;decay_t&lt;F>(const shared_future&amp;)>></code>.

        <cxx-note>
          This analogous to <code>future</code>. See the notes on
          the return type of <code>future::then</code> in <cxx-ref to="futures.unique_future"></cxx-ref>.
        </cxx-note>
      </li>
    </ul>

  </cxx-Returns>

<cxx-postconditions>
  <code>valid() == true</code> on the original <code>shared_future</code> object.
  <code>valid() == true</code> on the <code>future</code> returned from <code>then.</code>

  
</cxx-postconditions>
</cxx-function>

<cxx-function>
<cxx-signature>bool is_ready() const;</cxx-signature>
<cxx-Returns> <code>true</code> if the shared state is ready, otherwise <code>false</code>.</cxx-Returns>
</cxx-function>

</cxx-section>

  <cxx-section id="futures.promise">
    <h1>Class template <code>promise</code></h1>

    <p>
      The specifications of all declarations within this subclause <cxx-ref to="futures.promise"></cxx-ref>
      and its subclauses are the same as the corresponding declarations,
      as specified in <cxx-ref in="cxx" to="futures.promise"></cxx-ref>,
      unless explicitly specified otherwise.
    </p>
    <p>
      The <code>future</code> returned by the function <code>get_future</code> is the one defined in the <code>experimental</code>
      namespace (<cxx-ref to="futures.unique_future"></cxx-ref>).
    </p>

  </cxx-section>

  <cxx-section id="futures.task">
    <h1>Class template <code>packaged_task</code></h1>

    <p>
      The specifications of all declarations within this subclause <cxx-ref to="futures.task"></cxx-ref>
      and its subclauses are the same as the corresponding declarations,
      as specified in <cxx-ref in="cxx" to="futures.task"></cxx-ref>,
      unless explicitly specified otherwise.
    </p>
    <p>
      The <code>future</code> returned by the function <code>get_future</code> is the one defined in the <code>experimental</code>
      namespace (<cxx-ref to="futures.unique_future"></cxx-ref>).
    </p>

  </cxx-section>

<!--             -->
<!-- M00when_all -->
<!--             -->

<cxx-section id="futures.when_all">
<h1> Function template <code>when_all</code></h1>

<p>
The function template <code>when_all</code> creates a <code>future</code> object that
becomes ready when all elements in a set of <code>future</code> and <code>shared_future</code> objects
become ready.
</p>

<cxx-function>
<cxx-signature>
template &lt;class InputIterator>
future&lt;vector&lt;typename iterator_traits&lt;InputIterator&gt;::value_type>>
when_all(InputIterator first, InputIterator last);

template &lt;class... Futures>
future&lt;tuple&lt;decay_t&lt;Futures&gt;...>> when_all(Futures&amp;&amp;... futures);
</cxx-signature>

<cxx-requires>
  

  All <code>future</code>s and <code>shared_future</code>s passed into 
  <code>when_all</code> must be in a valid state (i.e. <code>valid() == true</code>).
</cxx-requires>

<cxx-remarks>
  <ul>
    <li>
      
      The first overload shall not participate in overload resolution unless <code>iterator_traits&lt;InputIterator&gt;::value_type</code> is <code>future&lt;R></code>
      or <code>shared_future&lt;R></code> for some type <code>R</code>.
      
    </li>
    <li>
      For the second overload, let <em><code>D<sub>i</sub></code></em> be 
      <code>decay_t&lt;F<sub>i</sub>></code>, and
      let <em><code>U<sub>i</sub></code></em> be 
      <code>remove_reference_t&lt;F<sub>i</sub>></code> 
      for each <code>F<sub>i</sub></code> in
      <code>Futures</code>. This function shall not participate in overload resolution unless 
      for each <em>i</em> either <em><code>D<sub>i</sub></code></em> 
      is a <code>shared_future&lt;<em>R<sub>i</sub></em>&gt;</code>
      or <em><code>U<sub>i</sub></code></em> is a <code>future&lt;<em>R<sub>i</sub></em>&gt;</code>.
    </li>
  </ul>
</cxx-remarks>

<cxx-Effects>

<!-- M0when_all_effects -->

  <ul>

    <li>
    A new shared state containing a <code>Sequence</code> is
    created, where <code>Sequence</code> is 

    

    a <code>vector</code> for the first overload and a
    <code>tuple</code> for the second overload.

    A new <code>future</code> object that refers to that shared state is created
    and returned from <code>when_all</code>.
    </li>

    <li>
      If the first overload is called with <code>first == last</code>, <code>when_all</code>
      returns a <code>future</code> with an empty <code>vector</code> that is immediately
      ready.
    </li>

    <li>If the second overload is called with no arguments,
    <code>when_all</code> returns a <code>future&lt;tuple&lt;>></code> 
    that is immediately ready.</li>

    <li>
      Otherwise, any <code>future</code>s are moved, and any <code>shared_future</code>s
      are copied into, correspondingly, <code>future</code>s or 
      <code>shared_future</code>s of 
      <code>Sequence</code> in the shared state.
    </li>

    <li>
      The order of the objects in the shared state matches the order
      of the arguments supplied to <code>when_all</code>.
    </li>
    <li>
      Once all the <code>future</code>s and <code>shared_future</code>s supplied
      to the call to <code>when_all</code> are ready, the resulting <code>future</code>,
      as well as the <code>future</code>s and <code>shared_future</code>s
      of the <code>Sequence</code>, are ready.
    </li>
    <li>

    </li>
    <li>The shared state of the <code>future</code> returned by <code>when_all</code> 
      will not store an exception, but the
      shared states of <code>future</code>s and <code>shared_future</code>s held in the shared state may.</li>
  </ul>
</cxx-Effects>

<cxx-postconditions>
  <ul>
    <li>For the returned <code>future</code>, <code>valid() == true</code>.</li>
    <li>For all input <code>future</code>s, <code>valid() == false</code>.</li>
    <li>For all input <code>shared_future</code>s, <code>valid() == true</code>.</li>
  </ul>
</cxx-postconditions>

<cxx-returns>

A <code>future</code> object that becomes ready when all of the input
<code>future</code>sand <code>shared_future</code>s are ready.

</cxx-returns>
</cxx-function>
</cxx-section>

<!--             -->
<!-- M00when_any -->
<!--             -->

<cxx-section id="futures.when_any_result">
<h1> Class template <code>when_any_result</code></h1>

<p>
The library provides a template for storing the result of <code>when_any</code>.
</p>

<pre><code>
template&lt;class Sequence>
struct when_any_result {
    size_t index;
    Sequence futures;
};
</code></pre>

</cxx-section>

<cxx-section id="futures.when_any">
<h1> Function template <code>when_any</code></h1>

<p>
The function template <code>when_any</code> creates a <code>future</code> object that
becomes ready when at least one element in a set of <code>future</code> and <code>shared_future</code> objects
becomes ready.
</p>

<cxx-function>
<cxx-signature>
template &lt;class InputIterator>
future&lt;when_any_result&lt;vector&lt;typename iterator_traits&lt;InputIterator&gt;::value_type>>>
when_any(InputIterator first, InputIterator last);

template &lt;class... Futures>
future&lt;when_any_result&lt;tuple&lt;decay_t&lt;Futures&gt;...>>> when_any(Futures&amp;&amp;... futures);
</cxx-signature>

<cxx-requires>
  

  All <code>future</code>s and <code>shared_future</code>s passed into 
  <code>when_all</code> must be in a valid state (i.e. <code>valid() == true</code>).
</cxx-requires>

<cxx-remarks>
  <ul>
    <li>
      
      The first overload shall not participate in overload resolution unless <code>iterator_traits&lt;InputIterator&gt;::value_type</code> is <code>future&lt;R></code>
      or <code>shared_future&lt;R></code> for some type <code>R</code>.
      
    </li>
    <li>
      For the second overload, let <em><code>D<sub>i</sub></code></em> be 
      <code>decay_t&lt;F<sub>i</sub>></code>, and
      let <em><code>U<sub>i</sub></code></em> be 
      <code>remove_reference_t&lt;F<sub>i</sub>></code> 
      for each <code>F<sub>i</sub></code> in
      <code>Futures</code>. This function shall not participate in overload resolution unless 
      for each <em>i</em> either <em><code>D<sub>i</sub></code></em> 
      is a <code>shared_future&lt;<em>R<sub>i</sub></em>&gt;</code>
      or <em><code>U<sub>i</sub></code></em> is a <code>future&lt;<em>R<sub>i</sub></em>&gt;</code>.
    </li>
  </ul>
</cxx-remarks>

<cxx-Effects>

<!-- M0when_any_effects -->

  <ul>

    <li>
    A new shared state containing <code>when_any_result&lt;Sequence></code> is created,
    where <code>Sequence</code> is a <code>vector</code> for the first overload and a
    <code>tuple</code> for the second overload.

    A new <code>future</code> object that refers to that shared state is created and returned
    from <code>when_any</code>.
    </li>

    <li>
      If the first overload is called with <code>first == last</code>,
      <code>when_any</code> returns a <code>future</code> that is immediately ready.
      The value of the <code>index</code> field of the <code>when_any_result</code> is
      <code>static_cast&lt;size_t>(-1)</code>. The <code>futures</code> field is an empty <code>vector</code>.
    </li>

    <li>If the second overload of is called with no arguments,
      <code>when_any</code> returns a <code>future</code> that is immediately ready.
      The value of the <code>index</code> field of the <code>when_any_result</code> is
      <code>static_cast&lt;size_t>(-1)</code>. 
      The <code>futures</code> field is <code>tuple&lt;></code>.
    </li>

    <li>
      Otherwise, any <code>future</code>s are moved, and any <code>shared_future</code>s
      are copied into, correspondingly, <code>future</code>s or 
      <code>shared_future</code>s of the <code>futures</code> member of 
      <code>when_any_result&lt;Sequence></code> in the shared state.

    </li>
    <li>
      The order of the objects in the <code>futures</code> shared state matches the order
      of the arguments supplied to <code>when_any</code>. 
    </li>
    <li>

      Once at least one of the <code>future</code>s or <code>shared_future</code>s supplied
      to the call to <code>when_any</code> is ready, the resulting <code>future</code>
      is ready.

      Given the result future <code>f</code>,
      <code>f.get().index</code> is the position of the ready <code>future</code> 
      or <code>shared_future</code> in the
      <code>futures</code> member of 
      <code>when_any_result&lt;Sequence></code> in the shared state.

    </li>

    <li>The shared state of the <code>future</code> returned by <code>when_all</code> 
      will not store an exception, but the
      shared states of <code>future</code>s and <code>shared_future</code>s held in the shared state may.</li>
    </li>
  </ul>
</cxx-Effects>

<cxx-postconditions>
  <ul>
    <li>For the returned <code>future</code>, <code>valid() == true</code>.</li>
    <li>For all input <code>future</code>s, <code>valid() == false</code>.</li>
    <li>For all input <code>shared_future</code>s, <code>valid() == true</code>.</li>
  </ul>
</cxx-postconditions>

<cxx-Returns>
<ul>
  <li>A <code>future</code> object that becomes ready when any of the input
    <code>future</code>s and <code>shared_future</code>s are ready.
  </li>
</ul>
</cxx-Returns>

</cxx-function>
</cxx-section>

<cxx-section id="futures.make_ready_future">
<h1> Function template <code>make_ready_future</code></h1>


<cxx-function>
  <cxx-signature>
template &lt;class T>
future&lt;V> make_ready_future(T&amp;&amp; value);

future&lt;void> make_ready_future();
  </cxx-signature>
<p>
  Let <code>U</code> be <code>decay_t&lt;T></code>. Then <code>V</code> is <code>X&amp;</code> if <code>U</code> equals
  <code>reference_wrapper&lt;X></code>, otherwise <code>V</code> is <code>U</code>.
</p>
  <cxx-Effects>
    The function creates a shared state
      that is immediately ready and returns a <code>future</code> associated 
      with that shared state.
      For the first overload, the type of the shared state is <code>V</code> and the result is
      constructed from <code>std::forward&lt;T>(value)</code>.
      For the second overload, the type of the shared state is <code>void</code>.
    

  </cxx-Effects>


  <cxx-postconditions>
      For the returned <code>future, valid() == true</code> and <code>is_ready() == true</code>.
  </cxx-postconditions>
</cxx-function>
</cxx-section>

<cxx-section id="futures.make_exceptional_future">
<h1>Function template <code>make_exceptional_future</code></h1>


<cxx-function>
  <cxx-signature>
template &lt;class T>
future&lt;T&gt; make_exceptional_future(exception_ptr ex);
</cxx-signature>

  <cxx-Effects>Equivalent to
  <cxx-codeblock>
promise&lt;T&gt; p;
p.set_exception(ex);
return p.get_future();</cxx-codeblock>
  </cxx-Effects>

</cxx-function>
<cxx-function>
  <cxx-codeblock>
template &lt;class T, class E>
future&lt;T&gt; make_exceptional_future(E ex);</cxx-codeblock>

  <cxx-Effects>Equivalent to
  <cxx-codeblock>
promise&lt;T&gt; p;
p.set_exception(make_exception_ptr(ex));
return p.get_future();
  </cxx-codeblock>
  </cxx-Effects>

</cxx-function>
</cxx-section>

</cxx-section>

</cxx-clause>