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

mojo/public/c/environment/async_waiter.h

Index: mojo/public/c/environment/async_waiter.h
diff --git a/mojo/public/c/environment/async_waiter.h b/mojo/public/c/environment/async_waiter.h
index 1eb06317d70f25b4a4ec357bb31771659f8ec9d9..b5a1f7523fe6b329981050bdc76f2e6d35eb517a 100644
--- a/mojo/public/c/environment/async_waiter.h
+++ b/mojo/public/c/environment/async_waiter.h
@@ -11,19 +11,54 @@ typedef uintptr_t MojoAsyncWaitID;
 
 typedef void (*MojoAsyncWaitCallback)(void* closure, MojoResult result);
 
+// Functions for asynchronously waiting (and cancelling asynchronous waits) on a
+// handle.
+//
+// Thread-safety:
+//   - |CancelWait(wait_id)| may only be called on the same thread as the
+//     |AsyncWait()| that provided |wait_id| was called on.
+//   - A given |MojoAsyncWaiter|'s functions may only be called on the thread(s)
+//     that it is defined to be valid on (typically including the thread on
+//     which the |MojoAsyncWaiter| was provided). E.g., a library may require
+//     initialization with a single |MojoAsyncWaiter| and stipulate that it only
+//     be used on threads on which that |MojoAsyncWaiter| is valid.
+//   - If a |MojoAsyncWaiter| is valid on multiple threads, then its functions
+//     must be thread-safe (subject to the first restriction above).
 struct MojoAsyncWaiter {
-  // Asynchronously call MojoWait on a background thread, and pass the result
-  // of MojoWait to the given MojoAsyncWaitCallback on the current thread.
-  // Returns a non-zero MojoAsyncWaitID that can be used with CancelWait to
-  // stop waiting. This identifier becomes invalid once the callback runs.
+  // Arranges for |callback| to be called on the current thread at some future
+  // when |handle| satisfies |signals| or it is known that it will never satisfy
+  // |signals| (with the same behavior as |MojoWait()|).
+  //
+  // |callback| will not be called in the nested context of |AsyncWait()|, but
+  // only, e.g., from some run loop. |callback| is provided with the |closure|
+  // argument as well as the result of the wait. For each call to |AsyncWait()|,
+  // |callback| will be called at most once.
+  //
+  // |handle| must not be closed or transferred (via |MojoWriteMessage()|; this
+  // is equivalent to closing the handle) until either the callback has been
+  // executed or the async wait has been cancelled using the returned (nonzero)
+  // |MojoAsyncWaitID| (see |CancelWait()|). Otherwise, an invalid (or, worse,
+  // re-used) handle may be waited on by the implementation of this
+  // |MojoAsyncWaiter|.
+  //
+  // Note that once the callback has been called, the returned |MojoAsyncWaitID|
+  // becomes invalid.
   MojoAsyncWaitID (*AsyncWait)(MojoHandle handle,
                                MojoHandleSignals signals,
                                MojoDeadline deadline,
                                MojoAsyncWaitCallback callback,
                                void* closure);
 
-  // Cancel an existing call to AsyncWait with the given MojoAsyncWaitID. The
-  // corresponding MojoAsyncWaitCallback will not be called in this case.
+  // Cancels an outstanding async wait (specified by |wait_id|) initiated by
+  // |AsyncWait()|. This may only be called from the same thread on which the
+  // corresponding |AsyncWait()| was called, and may only be called if the
+  // callback to |AsyncWait()| has not been called.
+  //
+  // Once this has been called, the callback provided to |AsyncWait()| will not
+  // be called. Moreover, it is then immediately safe to close or transfer the
+  // handle provided to |AsyncWait()|. (I.e., the implementation of this
+  // |MojoAsyncWaiter| will no longer wait on, or do anything else with, the
+  // handle.)
   void (*CancelWait)(MojoAsyncWaitID wait_id);
 };