API definition for WaitSet.

mojo/public/c/system/wait_set.h

Index: mojo/public/c/system/wait_set.h
diff --git a/mojo/public/c/system/wait_set.h b/mojo/public/c/system/wait_set.h
new file mode 100644
index 0000000000000000000000000000000000000000..67c9cc8610fa1edb9bc0425411c716fde15dff97
--- /dev/null
+++ b/mojo/public/c/system/wait_set.h
@@ -0,0 +1,112 @@
+// Copyright 2015 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.
+
+// This file contains types/constants and functions specific to wait sets.
+//
+// Note: This header should be compilable as C.
+
+#ifndef MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_
+#define MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_
+
+#include "mojo/public/c/system/system_export.h"
+#include "mojo/public/c/system/types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Note: See the comment in functions.h about the meaning of the "optional"
+// label for pointer parameters.
+
+// Creates a wait set. A wait set is a way to efficiently wait on multiple
+// handles.
+//
+// On success, |*wait_set_handle| will contain a handle to a wait set.
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is null.
+//   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
+//       been reached.
+MOJO_SYSTEM_EXPORT MojoResult MojoCreateWaitSet(
+    MojoHandle* wait_set_handle);  // Out.
+
+// Add a wait on |handle| to |wait_set_handle|.

[yzshen1, 2015/11/18 23:50:58]

Nit: please use "Adds" because the omitted subject is "this function". (here and
elsewhere)

[Anand Mistry (off Chromium), 2015/11/19 04:13:45]

Done? Sorry, grammar has never been my strong point.

+//
+// A handle can only be added to any given wait set once, but may be added to
+// any number of different wait sets. To modify the signals being waited for,
+// the handle must first be removed, and then added with the new signals.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |handle| was successfully added to |wait_set_handle|.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or
+//       |wait_set_handle| is not a valid wait set.
+//   |MOJO_RESULT_ALREADY_EXISTS| if |handle| already exists in
+//       |wait_set_handle|.
+//
+// It is safe to add a handle to a wait set while performing a wait on another
+// thread.
+MOJO_SYSTEM_EXPORT MojoResult MojoAddWaiter(
+    MojoHandle wait_set_handle,
+    MojoHandle handle,
+    MojoHandleSignals signals);
+
+// Remove |handle| from |wait_set_handle|.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |handle| was successfully removed from
+//       |wait_set_handle|.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or
+//       |wait_set_handle| is not a valid wait set.
+//   |MOJO_RESULT_NOT_FOUND| if |handle| does not exist in |wait_set_handle|.
+//
+// It is safe to remove a handle from a wait set while performing a wait on
+// another thread.
+MOJO_SYSTEM_EXPORT MojoResult MojoRemoveWaiter(
+    MojoHandle wait_set_handle,
+    MojoHandle handle);
+
+// Retreive a ready from |wait_set_handle|. A handle is ready if:
+//   - Its signals are satisfied.
+//   - It becomes known that no signal for the handle will ever be satisfied.
+//   - It is closed.
+//
+// A wait set may have ready handles when it satisfies the
+// |MOJO_HANDLE_SIGNAL_READABLE| signal. Since handles may be added and removed
+// from a wait set concurrently, it is possible for a wait set to satisfy
+// |MOJO_HANDLE_SIGNAL_READABLE|, but not have any ready handles when
+// |MojoGetReadyHandle()| is called. These spurious wake-ups must be gracefully
+// handled.
+//
+// |*handle| will contain a handle whose signal has been satisfied, or can not
+// ever be satisfied. Care should be taken that if a handle is closed on another
+// thread, |*handle| would be invalid, but the return value may not be
+// |MOJO_RESULT_CANCELLED|.
+//
+// |signals_state| (optional): See documentation for |MojoHandleSignalsState|.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |*handle| has its signals satisfied.
+//   |MOJO_RESULT_CANCELLED| if |*handle| was closed (necessarily from another
+//       thread) during the wait.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is not a valid wait
+//       set.
+//   |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that
+//       |*handle| will ever satisfy any of its signals.
+//   |MOJO_RESULT_SHOULD_WAIT| if there are no ready handles.
+//
+// Mojo signals and satisfiability are logically 'level-triggered'. Therefore,
+// if a signal continues to be satisfied and is not removed from the wait set,
+// subsequent calls to |MojoGetReadyHandle()| will return the same handle.

[yzshen1, 2015/11/18 23:50:58]

I wonder how the wait set will determine the order to return ready handles.
(Maybe it is implementation related?)

(1) For example, assume {a, b} are two handles that are ready in the wait set. I
call MojoGetReadyHandle() and it returns |a|. The comment sounds like if I don't
do something with |a| (say, draining the data or removing it from the set),
subsequent calls will return |a| (instead of |b|) for sure.

(2) The other question is about starvation: assume {a, b} are two handles that
are ready in the wait set. I call MojoGetReadyHandle() and it returns |a|. I
drain the data of |a|, process the data and then call MojoGetReadyHandle()
again. In the mean time, there is new data available for |a|, so |a| is ready
again. If this pattern repeats, is it possible that |b| is never returned by
MojoGetReadyHandle() and "starved"?

It seems nice to add some comments to clarify.

[Anand Mistry (off Chromium), 2015/11/19 04:13:45]

Added a comment, and explanation inline.

On 2015/11/18 23:50:58, yzshen1 wrote:
I picked this wording because it represents a worst-case scenario that the user
must handle. It's not strictly correct because the implementation could
round-robin, or randomly pick. But this isn't guaranteed by the API. I chose not
to have any guarantees here in order to allow an efficient implementation,
similar to how mutexes generally aren't fair.
According to the API, yes (but in my current implementation, no, because I
round-robin). I would argue that if you run into this situation, you have bigger
problems. I think that this behaviour is reasonable and the notion of fairness
here should be handled at a higher level. The wait set has no notion of what the
best way to handle this case is. It might be that you want efficiency, and
repeatedly handling the same handle is most efficient. It could also be that you
want some other metric of fairness, such as distributing equal bandwidth between
renderers as not to starve any particular page. Encoding any notion of fairness
won't capture every case, and puts restrictions on the implementation.

That said, I'm willing to reconsider fairness as part of the API. Note that
epoll doesn't guarantee any notion of fairness. And the specific situation you
called out would be handled by an epoll user by using edge-triggering and
draining the ready queue each time before handling the each fd.

[yzshen1, 2015/11/19 06:52:25]

Thanks for the detailed reply!

I totally agree that "fairness" shouldn't be handled by this API because it
really depends on the user scenarios. I just think it is useful to explicitly
comment about it. (Your updated comment looks good.)

That being said, if the user wants to make scheduling decision himself, this API
seems a little inconvenient for the user to learn "the whole picture", i.e., all
the handles that are currently ready.

It seems the user needs to: call MojoGetReadyHandle() and then
MojoRemoveWaiter() to remove the ready handle returned; repeat this process
until no ready handle. And then add all those handles back to the wait set (if
he wants to continue watching).

Is my understanding correct?

+//
+MOJO_SYSTEM_EXPORT MojoResult MojoGetReadyHandle(
+    MojoHandle wait_set_handle,
+    MojoHandle *handle,                             // Out.

[yzshen1, 2015/11/18 23:50:58]

style nit: '*' should be adjacent to the type instead of the value. (here and
elsewhere)

[Anand Mistry (off Chromium), 2015/11/19 04:13:45]

Done.

+    struct MojoHandleSignalsState *signals_state);  // Optional out.
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_