Mojo: Armed Watchers

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 f0a23d931dee03583dc464afb4b2b7dd4ef9d2a1..b8a63126bdb6606ee4425f159b2c89b97585991e 100644
--- a/mojo/public/c/system/functions.h
+++ b/mojo/public/c/system/functions.h
@@ -19,9 +19,9 @@
 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.
+// A callback used to notify watchers registered via |MojoRegisterWatcher()|.
+// Called when some watched signals are satisfied or become unsatisfiable. See
+// the documentation for |MojoRegisterWatcher()| for more details.
 typedef void (*MojoWatchCallback)(uintptr_t context,
                                   MojoResult result,
                                   struct MojoHandleSignalsState signals_state,
@@ -138,73 +138,109 @@ 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.
+// Registers a watcher on the given handle. A watcher may be used to trigger
+// arbitrary code execution when a handle's state changes to meet any of the
+// following conditions:
+//
+//   - A signal in |signals| is satisfied on |handle|.
+//   - No signal in |signals| can ever be satisfied on |handle| again.
+//   - |handle| is closed.
+//
+// A newly registered watcher is initially disarmed. Use |MojoArmWatcher()| to
+// arm a registered watcher and |MojoUnregisterWatcher()| to unregister it.
+//
+// Watchers must be armed to trigger a notification for any event other than
+// handle closure.
+//
+// Handle closure triggers a final notification on all of a handle's registered
+// watchers to indicate that they have been implicitly unregistered. This
+// notification is fired regardless of whether each watcher is armed at the
+// time.
+//
+// A watcher is always disarmed immediately before any |callback| invocation.
 //
-// |handle|: The handle to watch. Must be an open message pipe or data pipe
+// |handle|: The handle to watcher. Must be an open message pipe or data pipe

[yzshen1, 2017/03/03 00:03:50]

watchter -> watch?

[Ken Rockot(use gerrit already), 2017/03/03 00:37:05]

done

 //     handle.
 // |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 at any time.
+//     The function must be safe to call from any thread at any time. The
+//     watcher is always disarmed immediately before any invocation of this
+//     callback.
 // |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()|.
+//     is used to uniquely identify a registered watcher and can be used to arm
+//     or remove the watcher later using |MojoArmWatcher()| and
+//     |MojoUnregisterWatcher()|.
 //
 // 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_OK| if the watcher has been successfully registered.
 //   |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
+//       never be satisfied on |handle|. The watcher is not registered.
+//   |MOJO_RESULT_ALREADY_EXISTS| if there is already a watcher registered for
 //       the same combination of |handle| and |context|.
 //
 // Callback result codes:
-//   The callback may be called at any time on any thread with one of the
-//   following result codes to indicate various events:
+//   When the watcher is armed (see |MojoArmWatcher()| below), |callback| may be
+//   called at any time on any thread with one of the following result codes:
 //
-//   |MOJO_RESULT_OK| indicates that some signal in |signals| has been
+//   |MOJO_RESULT_OK| indicates that some signal in |signals| has become
 //       satisfied.
 //   |MOJO_RESULT_FAILED_PRECONDITION| indicates that no signals in |signals|
 //       can ever be satisfied again.
+//
+//   The watcher may also invoke |callback| with the following result code even
+//   while disarmed:
+//
 //   |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);
+//       case the watcher is implicitly unregistered and there is no need to
+//       call |MojoUnregisterWatcher()|.
+MOJO_SYSTEM_EXPORT MojoResult MojoRegisterWatcher(MojoHandle handle,
+                                                  MojoHandleSignals signals,
+                                                  MojoWatchCallback callback,
+                                                  uintptr_t context);
+
+// Arms a registered watcher, enabling a single notification to fire when a
+// relevant condition is met. See |MojoRegisterWatcher()| documentation for
+// details.
+//
+// |handle|: The handle on which the watcher is registered.
+// |context|: The context with which the watcher is registered.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if the watcher has been successfully armed.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid message pipe
+//       or data pipe handle or a watcher is not registered on that handle with
+//       the given |context|.
+//   |MOJO_RESULT_ALREADY_EXISTS| if one of the watched signals is already
+//       satisfied. The watcher is not armed.
+//   |MOJO_RESULT_FAILED_PRECONDITION| if none of the watched signals can ever
+//       be satisfied again. The watcher is not armed.
+MOJO_SYSTEM_EXPORT MojoResult MojoArmWatcher(MojoHandle handle,
+                                             uintptr_t context);
 
-// Cancels a handle watch corresponding to some prior call to |MojoWatch()|.
+// Unregisters the watcher associated with |context| on |handle|.
 //
-// NOTE: If the watch callback corresponding to |context| is currently running
-// this will block until the callback completes execution. It is therefore
-// illegal to call |MojoCancelWatch()| on a given |handle| and |context| from
-// within the associated callback itself, as this will always deadlock.
+// NOTE: If the watcher's callback is currently running as a result of
+// invocation by the watcher, this will block until the callback returns. It is
+// therefore illegal to unregister a watcher from within its own callback, as
+// that would always lead to deadlock.
 //
-// After |MojoCancelWatch()| function returns, the watch's associated callback
-// will NEVER be called again by Mojo.
+// After |MojoUnregisterWatcher()| returns, the watcher's associated callback
+// will will never be called again by Mojo.
 //
+// |handle|: The handle on which the watcher is registered.
 // |context|: The same user-provided context given to some prior call to
-//     |MojoWatch()|. Only the watch corresponding to this context will be
-//     cancelled.
+//     |MojoRegisterWatcher()|. Only the watcher corresponding to this context
+//     will be unregistered.
 //
 // Returns:
-//     |MOJO_RESULT_OK| if the watch corresponding to |context| was cancelled.
-//     |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);
+//     |MOJO_RESULT_OK| if the watcher corresponding to |context| was
+//         unregistered.
+//     |MOJO_RESULT_INVALID_ARGUMENT| if no watcher was registered with
+//         |context| for the given |handle|, or if |handle| is invalid.
+MOJO_SYSTEM_EXPORT MojoResult MojoUnregisterWatcher(MojoHandle handle,
+                                                    uintptr_t context);
 
 // Retrieves system properties. See the documentation for |MojoPropertyType| for
 // supported property types and their corresponding output value type.