Mojo: Improve comments for MojoWait/MojoWaitMany.

R=ncbray@chromium.org
NOTRY=True

Review URL: https://codereview.chromium.org/354023005

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@280120 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 29 insertions, 8 deletions

diff --git a/mojo/public/c/system/functions.h b/mojo/public/c/system/functions.h
index 9d2ef6c..6045f2f 100644
--- a/mojo/public/c/system/functions.h
+++ b/mojo/public/c/system/functions.h
@@ -42,18 +42,30 @@ MOJO_SYSTEM_EXPORT MojoTimeTicks MojoGetTimeTicksNow(void);
 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after.
 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle);
 
-// Waits on the given handle until a signal indicated by |signals| is satisfied
-// or until |deadline| has passed.
+// Waits on the given handle until a signal indicated by |signals| is satisfied,
+// it becomes known that no signal indicated by |signals| will ever be satisfied
+// (see the description of the |MOJO_RESULT_CANCELLED| and
+// |MOJO_RESULT_FAILED_PRECONDITION| return values below), or until |deadline|
+// has passed.
+//
+// If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until
+// one of the other wait termination conditions is satisfied). If |deadline| is
+// 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other
+// termination conditions (e.g., a signal is satisfied, or all signals are
+// unsatisfiable) is not already satisfied.
 //
 // Returns:
 //   |MOJO_RESULT_OK| if some signal in |signals| was satisfied (or is already
-//        satisfied).
+//       satisfied).
+//   |MOJO_RESULT_CANCELLED| if |handle| was closed (necessarily from another
+//       thread) during the wait.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if
 //       it has already been closed).
 //   |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of
 //       the signals being satisfied.
-//   |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that any
-//       signal in |signals| will ever be satisfied.
+//   |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the
+//       signals in |signals| can ever be satisfied (e.g., when waiting on one
+//       end of a message pipe and the other end is closed).
 //
 // If there are multiple waiters (on different threads, obviously) waiting on
 // the same handle and signal, and that signal becomes is satisfied, all waiters
@@ -62,13 +74,22 @@ MOJO_SYSTEM_EXPORT MojoResult MojoWait(MojoHandle handle,
                                        MojoHandleSignals signals,
                                        MojoDeadline deadline);
 
-// Waits on |handles[0]|, ..., |handles[num_handles-1]| for at least one of them
-// to satisfy a signal indicated by |signals[0]|, ..., |signals[num_handles-1]|,
-// respectively, or until |deadline| has passed.
+// Waits on |handles[0]|, ..., |handles[num_handles-1]| until (at least) one
+// satisfies a signal indicated in its respective |signals[0]|, ...,
+// |signals[num_handles-1]|, it becomes known that no signal in some
+// |signals[i]| will ever be satisfied, or until |deadline| has passed.
+//
+// This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on
+// each handle/signals pair simultaneously, completing when the first
+// |MojoWait()| would complete.
+//
+// See |MojoWait()| for more details about |deadline|.
 //
 // Returns:
 //   The index |i| (from 0 to |num_handles-1|) if |handle[i]| satisfies a signal
 //       from |signals[i]|.
+//   |MOJO_RESULT_CANCELLED| if some |handle[i]| was closed (necessarily from
+//       another thread) during the wait.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle
 //       (e.g., if it has already been closed).
 //   |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of