[mojo-edk] Add MojoWatch and MojoCancelWatch APIs

mojo/public/c/system/functions.h

 // Copyright 2014 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 basic functions common to different Mojo system APIs.
 //
 // Note: This header should be compilable as C.
 
 #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"
 #include "mojo/public/c/system/types.h"
 
 #ifdef __cplusplus
 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
 // such a parameter is used may depend on other parameters or the requested
 // operation's success/failure. E.g., a separate |flags| parameter may control
 // whether a given "in/out" parameter is used for input, output, or both.)
 
 // Returns the time, in microseconds, since some undefined point in the past.
 // The values are only meaningful relative to other values that were obtained
 // from the same device without an intervening system restart. Such values are
@@ skipping 91 matching lines @@
 //   |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME
 //       |handle[i]| will ever satisfy any of the signals in |signals[i]|.
 MOJO_SYSTEM_EXPORT MojoResult
 MojoWaitMany(const MojoHandle* handles,
              const MojoHandleSignals* signals,
              uint32_t num_handles,
              MojoDeadline deadline,
              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
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_