[mojo-edk] Add MojoWatch and MojoCancelWatch APIs

mojo/public/c/system/functions.h

Index: mojo/public/c/system/functions.h
diff --git a/mojo/public/c/system/functions.h b/mojo/public/c/system/functions.h
index cd357b5b0067d073713e97098cc0876f28336ee6..66a6bba06de54a05a6ec8578d3292bfc8eb8b186 100644
--- a/mojo/public/c/system/functions.h
+++ b/mojo/public/c/system/functions.h
@@ -9,6 +9,7 @@
 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_
 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_
 
+#include <stddef.h>
 #include <stdint.h>
 
 #include "mojo/public/c/system/system_export.h"
@@ -18,6 +19,13 @@
 extern "C" {
 #endif
 
+// A callback used to notify watchers registered via |MojoWatch()|. Called when
+// some watched signals are satisfied or become unsatisfiable. See the
+// documentation for |MojoWatch()| for more details.
+typedef void (*MojoWatchCallback)(uintptr_t context,
+                                  MojoResult result,
+                                  struct MojoHandleSignalsState signals_state);
+
 // Note: Pointer parameters that are labelled "optional" may be null (at least
 // under some circumstances). Non-const pointer parameters are also labeled
 // "in", "out", or "in/out", to indicate how they are used. (Note that how/if
@@ -129,6 +137,66 @@ MojoWaitMany(const MojoHandle* handles,
              uint32_t* result_index,                          // Optional out
              struct MojoHandleSignalsState* signals_states);  // Optional out
 
+// Watches the given handle for one of the following events to happen:
+//   - 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.)
+//   - The handle is closed.
+//
+// |handle|: The handle to watch. Must be an open message pipe handle.
+//     TODO: Perhaps we could also support data pipes here.

[Anand Mistry (off Chromium), 2016/02/29 12:03:35]

If you want to replace wait, you need to support data pipe. Looking at
MessagePipe, it looks relatively simple to add.

[Ken Rockot(use gerrit already), 2016/02/29 20:59:06]

Yeah, was just trying to avoid more noise in the CL since we're not actually
deleting wait yet. However given your TLS suggestion it's even more trivial to
add this support. So, Done

+// |signals|: The signals to watch for.
+// |callback|: A function to be called any time one of the above events happens.
+//     The function must be safe to call from any thread.
+// |context|: User-provided context passed to |callback| when called. |context|
+//     is used to uniquely identify a registered watch and can be used to cancel
+//     the watch later using |MojoCancelWatch().|

[Anand Mistry (off Chromium), 2016/02/29 12:03:35]

nit: |MojoCancelWatch()|.

[Ken Rockot(use gerrit already), 2016/02/29 20:59:06]

Done

+//
+// Returns:
+//   |MOJO_RESULT_OK| if the watch has been successfully registered. Note that
+//       if the signals are already satisfied this may synchronously invoke
+//       |callback| before returning.
+//   |MOJO_RESULT_CANCELLED| if the watch was cancelled. In this case it is not
+//       necessary to explicitly call |MojoCancelWatch()|, and in fact it may be
+//       an error to do so as the handle may have been closed.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not an open message pipe
+//       handle.
+//   |MOJO_RESULT_FAILED_PRECONDITION| if it is already known that |signals| can
+//       never be satisfied.
+//   |MOJO_RESULT_ALREADY_EXISTS| if there is already a watch registered for
+//       the same combination of |handle| and |context|.
+//
+// Callback result codes:
+//   The callback may be called at any time with one of the following result

[Anand Mistry (off Chromium), 2016/02/29 12:03:35]

at any time... on any thread...

I think. I didn't see anything that ties callbacks to threads.

[Ken Rockot(use gerrit already), 2016/02/29 20:59:06]

Done

+//   codes to indicate various events:
+//
+//   |MOJO_RESULT_OK| indicates that some signal in |signals| has been
+//       satisfied.
+//   |MOJO_RESULT_FAILED_PRECONDITION| indicates that no signals in |signals|
+//       can ever be satisfied again.
+//   |MOJO_RESULT_CANCELLED| indicates that the handle has been closed. In this
+//       case the watch is implicitly cancelled and there is no need to call
+//       |MojoCancelWatch()|.
+MOJO_SYSTEM_EXPORT MojoResult
+MojoWatch(MojoHandle handle,
+          MojoHandleSignals signals,
+          MojoWatchCallback callback,
+          uintptr_t context);
+
+// Cancels a handle watch corresponding to some prior call to |MojoWatch()|.
+//
+// |context|: The same user-provided context given to some prior call to
+//     |MojoWatch()|. Only the watch corresponding to this context will be
+//     cancelled.
+//
+// Returns:
+//     |MOJO_RESULT_OK| if the watch corresponding to |context| was cancelled.

[Anand Mistry (off Chromium), 2016/02/29 12:03:35]

Can you clarify what happens if the watch is in the process of being run. It's
an important note when dealing with task cancellation.

[Ken Rockot(use gerrit already), 2016/02/29 20:59:06]

Done

+//     |MOJO_RESULT_INVALID_ARGUMENT| if no watch was registered with |context|
+//         for the given |handle|, or if |handle| is invalid.
+MOJO_SYSTEM_EXPORT MojoResult
+MojoCancelWatch(MojoHandle handle, uintptr_t context);
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif