<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII">
<title>Managing C++ Associated Asynchronous State</title>
</head>
<body>
<h1>Managing C++ Associated Asynchronous State</h1>

<p>
ISO/IEC JTC1 SC22 WG21 N3192 = 10-0182 - 2010-11-12
</p>

<p>
Lawrence Crowl, crowl@google.com, Lawrence@Crowl.org
</p>

<p>
This paper revises
ISO/IEC JTC1 SC22 WG21 N3129 = 10-0119 - 2010-08-20.
<p>

<p>
This paper addresses national body comment US 194.
The changes in this paper are editorial in intent.
However, some of the FCD wording is broken with respect to the intent.
In that sense, the changes fix real bugs in the standard.
</p>

<p>
<a href="#Problem">Problem</a><br>
<a href="#Solution">Solution</a><br>
<a href="#Wording">Wording</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#futures.state">30.6.4 Associated asynchronous state [futures.state]</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#futures.promise">30.6.5 Class template promise [futures.promise]</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#futures.unique_future">30.6.6 Class template future [futures.unique_future]</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#futures.shared_future">30.6.7 Class template shared_future [futures.shared_future]</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#futures.atomic_future">30.6.8 Class template atomic_future [futures.atomic_future]</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#futures.task.members">30.6.10.1 packaged_task member functions [futures.task.members]</a><br>
</p>


<h2><a name="Problem">Problem</a></h2>

<p>
Within the Final Committee Draft,
the specification for managing associated asynchronous state [futures.state]
is confusing, sometimes omitted, and redundantly specified.
</p>


<h2><a name="Solution">Solution</a></h2>

<p>
Define terms-of-art for
<dfn>releasing</dfn>,
<dfn>making ready</dfn>,
and <dfn>abandoning</dfn>
an associated asynchronous state.
Define a term-of-art for <dfn>waiting functions</dfn>
on an associated asynchronous state.
Use those terms where appropriate.
</p>

<p>
This solution implements the intent of the existing wording.
That is, there is no new functionality.
</p>


<h2><a name="Wording">Wording</a></h2>

<p>
The wording is relative to the FCD.
</p>


<h3><a name="futures.state">30.6.4 Associated asynchronous state [futures.state]</a></h3>

<p>
Edit paragraph 3 as follows.
</p>

<blockquote>
<p>
An asynchronous return object is an object that
reads results from an associated asynchronous state.
<ins>
A waiting function of an asynchronous return object
is one that potentially blocks
to wait for the associated asynchronous state to be made ready.
</ins>
</p>
</blockquote>

<p>
Edit paragraph 5 as follows.
</p>

<blockquote>
<p> 
<del>
When the last reference to an associated asynchronous state is given up,
any resources held by that associated asynchronous state are released.
</del>
<ins>
When an asynchronous return object or an asynchronous provider
is said to
<dfn>release its associated asynchronous state</dfn>,
it means:</ins>
</p>
<ul>
<li><ins>
if the return object or provider
holds the last reference to its associated asynchronous state,
the associated state is destroyed; and
</ins></li>
<li><ins>
the return object or provider
gives up its reference to its associated asynchronous state.
</ins></li>
</ul>

<p>
<ins>
When an asynchronous provider is said to
<dfn>make its associated asynchronous state ready</dfn>,
it means:</ins>
<ul>
<li><ins>
first, the provider marks its associated asynchronous state as ready;
and
</ins></li>
<li><ins>
second, the provider unblocks any execution agents
waiting for its associated asynchronous state to become ready.
</ins></li>
</ul>
<p>
<ins>When an asynchronous provider is said to
<dfn>abandon its associated asynchronous state</dfn>,
it means:</ins>
</p>
<ul>
<li>
<p><ins>first, if that state is not ready, 
the provider
</ins></p>
<ul>
<li><ins>
stores an exception object of type <code>future_error</code>
with an error condition of <code>broken_promise</code>
within its associated asynchronous state; and then
</ins></li>
<li><ins>
makes its associated asynchronous state ready;
</ins></li>
</ul>
<li><p><ins>
second, the provider releases its associated asynchronous state.
</ins></p></li>
</ul>
</blockquote>


<h3><a name="futures.promise">30.6.5 Class template promise [futures.promise]</a></h3>

<p>
Edit paragraph 7, regarding the destructor, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
<del>
if the associated asynchronous state of <code>*this</code> is not ready,
stores an exception object of type <code>future_error</code>
with an error condition of <code>broken_promise</code>
Any threads blocked in a function waiting for
the asynchronous state associated with <code>*this</code> to become ready
are unblocked.
Destroys <code>*this</code> and
releases its reference to its associated asynchronous state if any.
If this is the last reference to that
associated asynchronous state, destroys that state.
</del>
<ins>
abandons any associated asynchronous state ([futures.state]).
</ins>
</p></blockquote>

<p>
Edit paragraph 8, regarding the move assignment operator, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
<ins>
abandons any associated asynchronous state ([futures.state])
and then as if
</ins>
<code>promise&lt;R&gt;(std::move(rhs)).swap(*this)</code>.
</p></blockquote>

<p>
Remove paragraph 9, as it is now redundant with the effects.
</p>

<blockquote><p>
<del>
<i>Postcondition:</i>
<code>rhs</code> has no associated asynchronous state.
<code>*this</code> has the associated asynchronous state
of <code>rhs</code> prior to the assignment.
</del>
</p></blockquote>

<p>
Edit paragraph 18, regarding <code>set_value</code>, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
atomically stores <ins>the value</ins> <code>r</code>
in the associated asynchronous state and
<del>
sets that state to ready.
Any threads blocked in a call of a blocking function of any future
that refers to the same associated asynchronous state as <code>*this</code>
are unblocked.
</del>
<ins>
makes that state ([futures.state]) ready.
</ins>
</p></blockquote>

<p>
Edit paragraph 22, regarding <code>set_exception</code>, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
atomically stores <ins>the exception</ins> <code>p</code>
in the associated asynchronous state and
<del>
sets that state to ready.
Any threads blocked in a call of a blocking function of any future
that refers to the same associated asynchronous state as <code>*this</code>
are unblocked.
</del>
<ins>
makes that state ([futures.state]) ready.
</ins>
</p></blockquote>

<p>
Edit paragraph 26, regarding <code>set_value_at_thread_exit</code>, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
Stores <ins>the value</ins> <code>r</code>
in the associated asynchronous state without
making
<del>the associated asynchronous</del> <ins>that</ins> state
ready immediately.
Schedules <del>the associated asynchronous</del> <ins>that</ins> state
to be made ready when the current thread exits,
after all objects of thread storage duration
associated with the current thread
have been destroyed.
</p></blockquote>

<p>
Edit paragraph 29, regarding <code>set_exception_at_thread_exit</code>,
as follows.
</p>

<blockquote><p>
<i>Effects:</i>
Stores <ins>the exception</ins> <code>p</code>
in the associated asynchronous state without
making
<del>the associated asynchronous</del> <ins>that</ins> state <ins>ready</ins>
immediately.
Schedules <del>the associated asynchronous</del> <ins>that</ins> state
to be made ready when the current thread exits,
after all objects of thread storage duration
associated with the current thread
have been destroyed.
</p></blockquote>


<h3><a name="futures.unique_future">30.6.6 Class template future [futures.unique_future]</a></h3>

<p>
Edit paragraph 10, regarding the destructor, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><del>gives up the reference to its</del>
<ins>releases any</ins> associated asynchronous state
<ins>([futures.state])</ins>.</li>
<li>destroys <code>*this</code>.</li>
</ul></blockquote>

<p>
Edit paragraph 11, regarding the move assignment operator, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><p>
<del>if <code>*this</code>
referred to an associated asynchronous state
prior to the assignment it
gives up this reference.</del>
<ins>releases any associated asynchronous state ([futures.state]).</ins>
</p></li>
<li><p>
<ins>move</ins> assigns the contents of <code>rhs</code> to <code>*this</code>.
</p></li>
</ul></blockquote>


<h3><a name="futures.shared_future">30.6.7 Class template shared_future [futures.shared_future]</a></h3>

<p>
Edit paragraph 13, regarding the destructor, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><del>gives up the reference to its</del>
<ins>releases any</ins> associated asynchronous state
<ins>([futures.state])</ins>.</li>
<li>destroys <code>*this</code>.</li>
</ul></blockquote>

<p>
Edit paragraph 14, regarding the move assignment operator, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><del>if <code>*this</code>
refers to an associated asynchronous state
it gives up this reference.</del> 
<ins>releases any associated asynchronous state ([futures.state]).</ins></li>
<li>assigns the contents of <code>rhs</code> to <code>*this</code>.</li>
</ul></blockquote>

<p>
Edit paragraph 16, regarding the copy assignment operator, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><del>if <code>*this</code>
refers to an associated asynchronous state
it gives up this reference.</del> 
<ins>releases any associated asynchronous state ([futures.state]).</ins></li>
<li>assigns the contents of <code>rhs</code> to <code>*this</code>.
[<i>Note:</i>
as a result,
<code>*this</code> refers to the same associated asynchronous state
as <code>rhs</code> (if any).
&mdash;<i>end note</i>]
</li>
</ul></blockquote>


<h3><a name="futures.atomic_future">30.6.8 Class template atomic_future [futures.atomic_future]</a></h3>

<p>
Edit paragraph 9, regarding the destructor, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><del>gives up the reference to its</del>
<ins>releases any</ins> associated asynchronous state
<ins>([futures.state])</ins>.</li>
<li>destroys <code>*this</code>.</li>
</ul></blockquote>

<p>
Edit paragraph 10, regarding the copy assignment operator, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><ins>releases any associated asynchronous state.</ins></li>
<li>assigns the contents of <code>rhs</code> to <code>*this</code>.
[<i>Note:</i>
as a result,
<code>*this</code> refers to the same associated asynchronous state
as <code>rhs</code> (if any).
&mdash;<i>end note</i>]
</li>
</ul></blockquote>


<h3><a name="futures.task.members">30.6.10.1 packaged_task member functions [futures.task.members]</a></h3>

<p>
Edit paragraph 9, regarding the move assignment operator, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
</p><ul>
<li><ins>releases any associated asynchronous state
([futures.state]).</ins></li>
<li><code>packaged_task&lt;R, ArgTypes...&gt;(other).swap(*this)</code>.</li>
</ul></blockquote>

<p>
Edit paragraph 10, regarding the destructor, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
<del>
if the associated asynchronous state of <code>*this</code> is not ready,
stores an exception object of type <code>future_error</code>
with an error code of <code>broken_promise</code>.
Any threads blocked in a function
waiting for the associated asynchronous state of <code>*this</code>
to become ready are unblocked.
Destroys <code>*this</code>
and releases its reference to its associated asynchronous state (if any).
If this is the last reference to that associated asynchronous state,
destroys that state.
</del>
<ins>
abandons any associated asynchronous state ([futures.state]).
</ins>
</p></blockquote>

<p>
Edit within paragraph 24, regarding <code>make_ready_at_thread_exit</code>,
as follows.
</p>

<blockquote><p>
....
this shall be done without
<del>making the state ready</del>
<ins>making that state ([futures.state]) ready</ins> immediately.
....
</p></blockquote>

<p>
Edit paragraph 27, regarding <code>reset</code>, as follows.
</p>

<blockquote><p>
<i>Effects:</i>
<del>returns the object to a state</del>
as if
<del>a newly-constructed instance
had just been assigned to <code>*this</code> by</del>
<code>*this = packaged_task(std::move(f))</code>,
where <code>f</code> is the task stored in <code>*this</code>.
[<i>Note:</i>
this constructs a new associated asynchronous state for <code>*this</code>.
The old state is <del>discarded,</del>
<ins>abandoned ([futures.state]).</ins>
<del>as described in the destructor for <code>packaged_task</code>.
<code>get_future</code> may now be called again for <code>*this</code>.</del>
&mdash;<i>end note</i>]
</p></blockquote>

</body>
</html>
