<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>N2671: An Asynchronous Future Value: Proposed Wording</title>
  </head>

  <body>
<table>
  <tr>
    <td align="left">Document Number:</td>
    <td align="left">N2671=08-00181</td>
  </tr>
  <tr>
    <td align="left">Date:</td>
    <td align="left">2008-06-29</td>
  </tr>
  <tr>
    <td align="left">Project:</td>
    <td align="left">Programming Language C++</td>
  </tr>
</table>
<p>
Detlef Vollmann &lt;<a href="mailto:dv@vollmann.ch">dv@vollmann.ch</a>&gt;<br>
Howard Hinnant &lt;<a href="mailto:howard.hinnant@gmail.com">howard.hinnant@gmail.com&gt;</a><br>
Anthony Williams &lt;<a href="mailto:anthony@justsoftwaresolutions.co.uk">anthony@justsoftwaresolutions.co.uk</a>&gt;<br>
</p>
<h1>N2671: An Asynchronous Future Value: Proposed Wording</h1>
This paper provides full proposed wording for the mechanisms described in
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2627.html">N2627</a>.
The main differences to N2627 are:
<ul>
  <li>error reporting: now only one exception class is defined with
an accompanying error catagory;</li>
  <li> <code>packaged_task</code> was removed.</li>
</ul>
Minor changes include the renaming of the timed wait functions and making
some notes normative text.

<h2>Proposed changes to the Working Paper</h2>
Add to clause 30 "Thread support library" the following new subclause "Futures".
This subclause describes components that a C++ program can use to retrieve
in one thread the result (value or exception) from a function that has run in
another thread.
[Note: these components are not restricted to multi-threaded programs
but can be useful in single-threaded programs as well. --end note]

<h3>Header &lt;future&gt;</h3>

<pre>
namespace std {
    enum class future_errc
    {
        broken_promise,
        future_already_retrieved,
        promise_already_satisfied
    };

    template &lt;&gt; struct is_error_code_enum&lt;future_errc&gt; : public true_type {};

    constexpr error_code make_error_code(future_errc e);
    constexpr error_condition make_error_condition(future_errc e);

    extern const error_category* const future_category;

    class future_error;

    template &lt;typename R&gt; class unique_future;
    template &lt;typename R&gt; class unique_future&lt;R&&gt;;
    template &lt;&gt; class unique_future&lt;void&gt;;
    template &lt;typename R&gt; class shared_future;
    template &lt;typename R&gt; class shared_future&lt;R&&gt;;
    template &lt;&gt; class shared_future&lt;void&gt;;
    template &lt;typename R&gt; class promise;

}
</pre>

<h3>Error handling</h3>

<pre>
extern const error_category* const future_category;
</pre>

<p>
<code>future_category</code> shall point to a statically initialized
object of a type derived from class <code>error_category</code>.
</p>
<p>
The object's <code>default_error_condition</code> and equivalent
virtual functions shall behave as specified for the class
<code>error_category</code>.
The object name virtual function shall return a pointer to the string "FUTURE".
</p>
<pre>
constexpr error_code make_error_code(future_errc e);
</pre>

<p><strong>Returns:</strong>
<code>error_code(static_cast&lt;int&gt;(e), future_category)</code>.
</p>
<pre>
constexpr error_condition make_error_condition(future_errc e);
</pre>

<p><strong>Returns:</strong>
<code>error_condition(static_cast&lt;int&gt;(e), future_category)</code>.


<h3>Class <code>future_error</code></h3>
<pre>
namespace std
{

// put into sub-namespace and call it ???
    class future_error : public logic_error
    {
    public:
        future_error(error_code ec); // exposition only, not intended for general use

        const error_code&amp; code() const throw();
        const char*       what() const throw();
    };
}
</pre>

<pre>
    const error_code&amp; code() const throw();
</pre>
<p><strong>Returns:</strong>
<code>ec</code> from the constructor.
</p>
<pre>
    const char *what() const throw();
</pre>
<p><strong>Returns:</strong>
An NTBS incorporating <code>code().message()</code>.


<h3>Class template <code>unique_future</code></h3>
[[Note to the editor: this template has two specializations for
<code>void</code> and <code>R&amp;</code>, where only the
return type for the <code>get()</code> functions differ.
How is this best specified? --end note to editor]]
<pre>
namespace std
{
template &lt;typename R&gt;
class unique_future
{
public:
    unique_future(unique_future &amp;&amp;);
    unique_future(unique_future const &amp; rhs) = delete;

    ~unique_future();

    unique_future&amp; operator=(unique_future const &amp; rhs) = delete;

    // retrieving the value
    R&amp;&amp; get();
    R&amp; unique_future&lt;R&amp;&gt;::get(); // this is for the specialization unique_future&lt;R&amp;&gt;
    void unique_future&lt;void&gt;::get(); // this is for the specialization unique_future&lt;void&gt;

    // functions to check state, and wait for ready
    bool is_ready() const;
    bool has_exception() const;
    bool has_value() const;

    void wait() const;
    template &lt;class Rep, class Period>&gt;
    bool wait_for(const chrono::duration&lt;Rep, Period&gt;&amp; rel_time) const;
    template &lt;class Clock, class Duration&gt;
    bool wait_until(const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time) const;
};
}
</pre>

<pre>
    unique_future(const unique_future&amp;&amp; rhs);
</pre>

<p><strong>Effects:</strong>
MoveConstructs a <code>unique_future</code> whose associated state is the same
as the state of <code>rhs</code> before.
The associated state is the state and the (possibly not yet evaluated)
result (value or exception) associated with the <code>promise</code>
that provided the original future.
</p>

<p><strong>Postconditions:</strong>
<code>rhs</code> can be safely destroyed.
</p>

<pre>
    ~unique_future();
</pre>

<p><strong>Effects:</strong>
destroys <code>*this</code> and its associated state if no other object
refers to that.
</p>

<pre>
    R&amp;&amp; get();
    R&amp; unique_future&lt;R&amp;&gt;::get(); // this is for the specialization unique_future&lt;R&amp;&gt;
    void unique_future&lt;void&gt;::get(); // this is for the specialization unique_future&lt;void&gt;
</pre>

<p><strong>Effects:</strong>
Retrieves the value stored in the associated state.
</p>

<p><strong>Sychronization:</strong>
If <code>*this</code> is associated with a <code>promise</code>,
the completion of <code>set_value()</code> or <code>set_exception()</code>
to that <code>promise</code>
happens before ([intro.multithread])
<code>get()</code> returns.
</p>

<p><strong>Returns:</strong>
If the result type R is a reference, returns the stored reference.
If R is void, there is no return value.
Otherwise, returns an rvalue-reference to the value stored in the
asynchronous result. 
</p>

<p><strong>Throws:</strong>
the stored exception, if an exception was stored and not retrieved before.
</p>

<p>The return value of <code>is_ready</code> is unspecified
after a call to <code>get()</code>.
</p>
<p>It is unspecified what happens when get() is called a second time
on the same <code>unique_future</code>.
</p>


<pre>
    bool is_ready() const;
</pre>

<p><strong>Returns:</strong>
<code>true</code> if the associated state holds a value or an exception
ready for retrieval.
</p>


<pre>
    bool has_exception() const;
</pre>

<p><strong>Returns:</strong>
<code>true</code> if <code>is_ready() == true</code> and the
associated state contains an exception,
<code>false</code> otherwise.
</p>


<pre>
    bool has_value() const;
</pre>

<p><strong>Returns:</strong>
<code>true</code> if <code>is_ready() == true</code> and the
associated state contains a value,
<code>false</code> otherwise.
</p>


<pre>
    void wait() const;
</pre>

<p><strong>Effects:</strong>
Blocks until <code>*this</code> is ready.
</p>

<p><strong>Sychronization:</strong>
If <code>*this</code> is associated with a <code>promise</code>,
the completion of <code>set_value()</code> or <code>set_exception()</code>
to that <code>promise</code>
happens before ([intro.multithread])
<code>wait()</code> returns.<br>
</p>

<p><strong>Postconditions:</strong>
<code>is_ready() == true</code>.
</p>


<pre>
    template &lt;class Rep, class Period>&gt;
    bool wait_for(const chrono::duration&lt;Rep, Period&gt;&amp; rel_time) const;
</pre>

<p><strong>Effects:</strong>
Blocks until <code>*this</code> is ready
or until <code>rel_time</code> elapsed.
</p>

<p><strong>Returns:</strong>
<code>true</code> if the function returns because <code>*this</code>
is ready, <code>false</code> otherwise.
</p>

<p><strong>Postconditions:</strong>
<code>is_ready()</code> equals the return value.
</p>


<pre>
    template &lt;class Clock, class Duration&gt;
    bool wait_until(const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time) const;
</pre>

<p>Same as <code>wait_for()</code>, except that it blocks until
<code>abs_time</code> is reached if the associated state is not ready.
</p>


<h3>Class template <code>shared_future</code></h3>
[[Note to the editor: this template has two specializations for
<code>void</code> and <code>R&amp;</code>, where only the
return type for the <code>get()</code> functions differ.
How is this best specified? --end note to editor]]
<pre>
namespace std
{
template &lt;typename R&gt;
class shared_future
{
public:
    shared_future(shared_future const &amp; rhs);

    shared_future(unique_future&lt;R&gt;);

    ~shared_future();

    shared_future &amp; operator=(shared_future const &amp; rhs) = delete;

    // retrieving the value
    R const &amp; get() const;
    R&amp; shared_future&lt;R&amp;&gt;::get() const; // this is for the specialization shared_future&lt;R&amp;&gt;
    void shared_future&lt;void&gt;::get() const; // this is for the specialization shared_future&lt;void&gt;

    // functions to check state, and wait for ready
    bool is_ready() const;
    bool has_exception() const;
    bool has_value() const;

    void wait() const;
    template &lt;class Rep, class Period>&gt;
    bool wait_for(const chrono::duration&lt;Rep, Period&gt;&amp; rel_time) const;
    template &lt;class Clock, class Duration&gt;
    bool wait_until(const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time) const;
};
}
</pre>


<pre>
    shared_future(const shared_future&amp; rhs);
</pre>

<p><strong>Effects:</strong>
CopyConstructs a <code>shared_future</code> whose associated state is the same
as the state of <code>rhs</code> before.
The associated state is the state and the (possibly not yet evaluated)
result (value or exception) associated with the <code>promise</code>
that provided the original future.
</p>


<pre>
    shared_future(const unique_future&lt;R&gt; rhs);
</pre>

<p><strong>Effects:</strong>
MoveConstructs a <code>shared_future</code> whose associated state is the same
as the state of <code>rhs</code> before.
</p>

<p><strong>Postconditions:</strong>
<code>rhs</code> can be safely destroyed.
</p>

<pre>
    ~shared_future();
</pre>

<p><strong>Effects:</strong>
destroys <code>*this</code> and its associated state if no other object
refers to that.
</p>

<pre>
    R const &amp; get() const;
    R&amp; shared_future&lt;R&amp;&gt;::get() const; // this is for the specialization shared_future&lt;R&amp;&gt;
    void shared_future&lt;void&gt;::get() const; // this is for the specialization shared_future&lt;void&gt;
</pre>

<p><strong>Effects:</strong>
retrieves the value stored in the associated state.
</p>

<p><strong>Sychronization:</strong>
If <code>*this</code> is associated with a <code>promise</code>,
the completion of <code>set_value()</code> or <code>set_exception()</code>
to that <code>promise</code>
happens before ([intro.multithread])
<code>get()</code> returns.</p>

<p><strong>Returns:</strong>
If the result type R is a reference, returns the stored reference.
If R is void, there is no return value.
Otherwise, returns a const reference to the value stored in the
asynchronous result. 
</p>

<p><strong>Throws:</strong>
the stored exception, if an exception was stored and not retrieved before.
</p>


<pre>
    bool is_ready() const;
</pre>

<p><strong>Returns:</strong>
<code>true</code> if the associated state holds a value or an exception
ready for retrieval.
</p>


<pre>
    bool has_exception() const;
</pre>

<p><strong>Returns:</strong>
<code>true</code> if <code>is_ready() == true</code> and the
associated state contains an exception,
<code>false</code> otherwise.
</p>


<pre>
    bool has_value() const;
</pre>

<p><strong>Returns:</strong>
<code>true</code> if <code>is_ready() == true</code> and the
associated state contains a value,
<code>false</code> otherwise.
</p>


<pre>
    void wait() const;
</pre>

<p><strong>Effects:</strong>
Blocks until <code>*this</code> is ready.
</p>

<p><strong>Sychronization:</strong>
If <code>*this</code> is associated with a <code>promise</code>,
the completion of <code>set_value()</code> or <code>set_exception()</code>
to that <code>promise</code>
happens before ([intro.multithread])
<code>wait()</code> returns.</p>

<p><strong>Postconditions:</strong>
<code>is_ready() == true</code>.
</p>


<pre>
    template &lt;class Rep, class Period>&gt;
    bool wait_for(const chrono::duration&lt;Rep, Period&gt;&amp; rel_time) const;
</pre>

<p><strong>Effects:</strong>
Blocks until <code>*this</code> is ready
or until <code>rel_time</code> elapsed.
</p>

<p><strong>Returns:</strong>
<code>true</code> if the functions returns because <code>*this</code>
is ready, <code>false</code> otherwise.
</p>

<p><strong>Postconditions:</strong>
<code>is_ready()</code> equals the return value.
</p>


<pre>
    template &lt;class Clock, class Duration&gt;
    bool wait_until(const chrono::time_point&lt;Clock, Duration&gt;&amp; abs_time) const;
</pre>

<p>Same as <code>wait_for()</code>, except that it blocks until
<code>abs_time</code> is reached if the associated state is not ready.
</p>


<h3>Class template <code>promise</code></h3>
[[Note to the editor: this template has two specializations for
<code>void</code> and <code>R&amp;</code>, where only the
signatures for the <code>set_value()</code> functions differ.
How is this best specified? --end note to editor]]
<pre>
namespace std
{
template &lt;typename R&gt;
class promise
{
public:
    promise();
    template &lt;class Allocator&gt;
        promise(allocator_arg_t, Allocator const A&amp;);
    promise(promise &amp;&amp; rhs);
    template &lt;class Allocator&gt;
        promise(allocator_arg_t, Allocator const A&amp;,
                promise &amp; rhs);
    promise(promise const &amp; rhs) = delete;
    ~promise();

    // Assignment
    promise &amp; operator=(promise &amp;&amp; rhs);
    promise &amp; operator=(promise const &amp; rhs) = delete;
    void swap(promise&amp; other);

    // Result retrieval
    unique_future&lt;R&gt; get_future();

    void set_value(R const &amp; r);
    void set_value(R &amp;&amp; r);
    void promise&lt;R&amp;&gt;::set_value(R &amp; r); // this is for the specialization promise&lt;R&amp;&gt;
    void promise&lt;void&gt;::set_value(); // this is for the specialization promise&lt;void&gt;
    void set_exception(exception_ptr p);
};

template &lt;typename R, class Alloc&gt;
    struct uses_allocator&amp;promise&lt;R&gt;, Alloc&gt;;

template &lt;typename R&gt;
    struct constructible_with_allocator_prefix&lt;promise&lt;T2&gt;&gt;;
}
</pre>

<pre>
template &lt;typename R, class Alloc&gt;
    struct uses_allocator&amp;promise&lt;R&gt;, Alloc&gt;
     : true_type { };
</pre>

<p><strong>Requires:</strong>
Alloc shall be an Allocator ([allocator.requirements] 20.1.2)
</p>

<p><strong>Remarks:</strong>
Specialization of this trait informs other library components that
<code>promise</code> can be constructed with an allocator, even
though it does not have an allocator_type associated type.
</p>

<pre>
template &lt;typename R&gt;
    struct constructible_with_allocator_prefix&lt;promise&lt;T2&gt;&gt;
     : true_type { };
</pre>

<p><strong>Remarks:</strong>
Specialization of this trait informs other library components that a
<code>promise</code> can always be constructed with an allocator
prefix argument.
</p>



<pre>
    promise();
    template &lt;class Allocator&gt;
        promise(allocator_arg_t, Allocator const &amp;a);
</pre>

<p><strong>Effects:</strong>
constructs a <code>promise</code> and an associated state, using <code>a</code>
if given for allocating the memory for the associated state.
</p>


<pre>
    promise(promise &amp;&amp; rhs);
    template &lt;class Allocator&gt;
        promise(allocator_arg_t, Allocator const A&amp;,
                promise &amp; rhs);
</pre>

<p><strong>Effects:</strong>
MoveConstructs a <code>promise</code> whose associated state is the same
as the state of <code>rhs</code> before.
</p>

<p><strong>Postcondition:</strong>
<code>rhs</code> has no associated state.
</p>


<pre>
    ~promise();
</pre>

<p><strong>Effects:</strong>
destroys <code>*this</code> and its associated state if no other object
refers to it.
If another object refers to the associated state and that state is not
ready, sets that state to ready and stores a
<code>future_error</code> exception with
error code <code>broken_promise</code>
as result.
</p>


<pre>
    promise &amp; operator=(promise &amp;&amp; rhs);
</pre>

<p><strong>Effects:</strong>
MoveAssigns its associated state to <code>rhs</code>.
</p>

<p><strong>Postcondition:</strong>
<code>*this</code> has no associated state.
</p>

<p><strong>Returns:</strong>
<code>*this</code>.
</p>

<p><strong>Throws:</strong>
nothing.
</p>


<pre>
    void swap(promise&amp; other);
</pre>

<p><strong>Effects:</strong>
<code>swap(*this, other);</code>
</p>

<p><strong>Throws:</strong>
nothing.
</p>


<pre>
    unique_future&lt;R&gt; get_future();
</pre>

<p><strong>Returns:</strong>
a <code>unique_future&lt;R&gt;</code> with the same associated state
as <code>*this</code>.
</p>

<p><strong>Throws:</strong>
<code>future_error</code> if <code>*this</code> has no
associated state.
</p>

<p><strong>Error condition:</strong>
<code>future_already_retrieved</code> if <code>*this</code> has no
associated state.
</p>


<pre>
    void set_value(R const &amp; r);
    void set_value(R &amp;&amp; r);
    void promise&lt;R&amp;&gt;::set_value(R &amp; r); // this is for the specialization promise&lt;R&amp;&gt;
    void promise&lt;void&gt;::set_value(); // this is for the specialization promise&lt;void&gt;
</pre>

<p><strong>Effects:</strong>
stores <code>r</code> in the associated state and sets that state to ready.
Any blocking waits on the associated state are woken up.
</p>

<p><strong>Throws:</strong>
<code>future_error</code> if its associated state is already
ready.
</p>

<p><strong>Error condition:</strong>
<code>promise_already_satisfied</code> if its associated state is already
ready.
</p>



<pre>
    void set_exception(exception_ptr p);
</pre>

<p><strong>Effects:</strong>
stores <code>p</code> in the associated state sets that state to ready.
Any blocking waits on the associated state are woken up.
</p>

<p><strong>Throws:</strong>
<code>future_error</code> if its associated state is already
ready.
</p>

<p><strong>Error condition:</strong>
<code>promise_already_satisfied</code> if its associated state is already
ready.
</p>






  </body>
</html>

