Mojo: Rewrite comments in mojo/public/c/environment/async_waiter.h.

Mojo: Rewrite comments in mojo/public/c/environment/async_waiter.h.

The new comments specify requirements instead of defining behavior
operationally using a particular implementation (and isn't consistent
with, e.g., the standalone implementation, which uses
mojo/public/cpp/utility/run_loop.*).

Note that this doesn't actually fix bugs or make things conform to these
requirements. See crbug.com/394884, crbug.com/394883, crbug.com/394886.

R=darin@chromium.org, sky@chromium.org

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=283888

[viettrungluu, 2014-07-17 20:31:21]

See also crbug.com/389666 and crbug.com/394488.

[sky, 2014-07-17 20:40:36]

LGTM

[darin (slow to review), 2014-07-17 20:54:26]

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
File mojo/public/c/environment/async_waiter.h (right):

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
mojo/public/c/environment/async_waiter.h:22: //     which the |MojoAsyncWaiter|
was provided). E.g., a library require
nit: "a library require" -> "a library [may] require" ?

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
mojo/public/c/environment/async_waiter.h:37: // |handle| must not be closed or
transferred (via |MojoWriteMessage()|; this
why is this a "must"? what's wrong with transferring a handle while another
thread is blocking calling MojoWait on that handle? won't the MojoWait just see
an error, and then everything is fine?

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
mojo/public/c/environment/async_waiter.h:54: // be called. Moreover, it is then
immediately safe to close or transfer the
I don't understand the "safety" argument here.

[viettrungluu, 2014-07-17 21:16:59]

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
File mojo/public/c/environment/async_waiter.h (right):

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
mojo/public/c/environment/async_waiter.h:22: //     which the |MojoAsyncWaiter|
was provided). E.g., a library require
On 2014/07/17 20:54:26, darin wrote:
> nit: "a library require" -> "a library [may] require" ?

Oops, fixed.

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
mojo/public/c/environment/async_waiter.h:37: // |handle| must not be closed or
transferred (via |MojoWriteMessage()|; this
On 2014/07/17 20:54:26, darin wrote:
> why is this a "must"? what's wrong with transferring a handle while another
> thread is blocking calling MojoWait on that handle? won't the MojoWait just
see
> an error, and then everything is fine?

a) There's no guarantee that there's even another thread (e.g., the standalone
impl). In which case there's no notification that that handle is no longer
valid. And of course then the handle value may end up be reused.
b) There's no guarantee that the other thread has started waiting either. You
can't really synchronize on another thread starting to wait in a reasonable way
(plus it'd make AsyncWait() slow).

https://codereview.chromium.org/405513002/diff/1/mojo/public/c/environment/as...
mojo/public/c/environment/async_waiter.h:54: // be called. Moreover, it is then
immediately safe to close or transfer the
On 2014/07/17 20:54:26, darin wrote:
> I don't understand the "safety" argument here.

This is really specifying a requirement on CancelWait(). I.e., an implementation
that posts a task to another thread and returns immediately is not compliant.

[darin (slow to review), 2014-07-17 21:36:29]

LGTM

[viettrungluu, 2014-07-17 21:41:19]

Committed patchset #3 manually as r283888 (presubmit successful).