Mojo: Move waiting APIs to public library

mojo/public/cpp/system/wait.h

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef MOJO_PUBLIC_CPP_SYSTEM_WAIT_H_
+#define MOJO_PUBLIC_CPP_SYSTEM_WAIT_H_
+
+#include <stddef.h>
+
+#include "mojo/public/c/system/types.h"
+#include "mojo/public/cpp/system/handle.h"
+#include "mojo/public/cpp/system/system_export.h"
+
+namespace mojo {
+
+// Blocks the calling thread, waiting for one or more signals in |signals| to be
+// become satisfied -- or for all of them to become unsatisfiable -- on the
+// given Handle.
+//
+// If |signals_state| is non-null, |handle| is valid, the wait is not cancelled
+// (see return values below), the last known signaling state of |handle| is
+// written to |*signals_state| before returning.
+//
+// Return values:
+//   |MOJO_RESULT_OK| if one or more signals in |signals| has been raised on
+//       |handle| .
+//   |MOJO_RESULT_FAILED_PRECONDITION| if the state of |handle| changes such
+//       that no signals in |signals| can ever be raised again.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle.
+//   |MOJO_RESULT_CANCELLED| if the wait was cancelled because |handle| was
+//       closed by some other thread while waiting.
+MOJO_CPP_SYSTEM_EXPORT MojoResult
+Wait(Handle handle,
+     MojoHandleSignals signals,
+     MojoHandleSignalsState* signals_state = nullptr);
+
+// Blocks the calling thread, waiting for any handle in |handles| to have one of
+// the corresponding signals in |signals| become satisfied or to have all of the

[yzshen1, 2017/03/17 17:10:27]

nit: At the first glance, I thought this method aborts only when all handles
become unsatisfiable.

I feel that the original comment for MojoWaitMany seems a little more clear:
// Waits on |handles[0]|, ..., |handles[num_handles-1]| until:	
//   - (At least) one handle 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.
// This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on	
// each handle/signals pair simultaneously, completing when the first	
// |MojoWait()| would complete.
...

WDYT? Thanks!

[Ken Rockot(use gerrit already), 2017/03/17 17:58:51]

Agreed. Fixed!

+// corresponding signals in |signals| become permanently unsatisfiable.
+//
+// |num_handles| specifies the number of Handle entries at |handles| as well as
+// the number of signals values in |signals|. Each entry in |signals|
+// corresponds to the signals to watch for the corresponding entry in |handles|.
+//
+// If |signals_states| is non-null, all other arguments are valid, and the wait
+// is not cancelled (see return values below), the last known signaling state of
+// each Handle in |handles| is written to its corresponding entry in
+// |signals_states| before returning.
+//
+// Returns values:
+//   |MOJO_RESULT_OK| if one of the Handles in |handles| had one or more of its
+//       correpsonding signals satisfied. |*result_index| contains the index
+//       of the Handle in question if |result_index| is non-null.
+//   |MOJO_RESULT_FAILED_PRECONDITION| if one of the Handles in |handles|
+//       changes state such that its corresponding signals become permanently
+//       unsatisfiable. |*result_index| contains the index of the handle in
+//       question if |result_index| is non-null.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if any Handle in |handles| is invalid,
+//       or if any of |handles|, |signals|, or |result_index| is null.

[yzshen1, 2017/03/17 17:10:27]

I thought |result_index| is allowed to be null?

[Ken Rockot(use gerrit already), 2017/03/17 17:58:51]

Indeed. Outdated comment. :)

Fixed!

+//   |MOJO_RESULT_CANCELLED| if the wait was cancelled because a handle in
+//       |handles| was closed by some other thread while waiting.
+//       |*result_index| contains the index of the closed Handle if
+//       |result_index| is non-null.
+MOJO_CPP_SYSTEM_EXPORT MojoResult
+WaitMany(const Handle* handles,
+         const MojoHandleSignals* signals,
+         size_t num_handles,
+         size_t* result_index = nullptr,
+         MojoHandleSignalsState* signals_states = nullptr);
+
+}  // namespace mojo
+
+#endif  // MOJO_PUBLIC_CPP_SYSTEM_WAIT_H_