Mojo: Armed Watchers

mojo/edk/system/watcher.h

 // Copyright 2016 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_EDK_SYSTEM_WATCHER_H_
 #define MOJO_EDK_SYSTEM_WATCHER_H_
 
 #include "base/callback.h"
 #include "base/macros.h"
 #include "base/memory/ref_counted.h"
 #include "base/synchronization/lock.h"
+#include "mojo/edk/system/atomic_flag.h"
 #include "mojo/public/c/system/functions.h"
 #include "mojo/public/c/system/types.h"
 
 namespace mojo {
 namespace edk {
 
 struct HandleSignalsState;
 
-// This object corresponds to a watch added by a single call to |MojoWatch()|.
+// This object corresponds to a watcher added by a single call to
+// |MojoRegisterWatcher()|.
 //
 // An event may occur at any time which should trigger a Watcher to run its
 // callback, but the callback needs to be deferred until all EDK locks are
-// released. At the same time, a watch may be cancelled at any time by
-// |MojoCancelWatch()| and it is not OK for the callback to be invoked after
-// that happens.
+// released. At the same time, a watcher may be unregistered at any time by
+// |MojoUnregisterWatcher()| and it is not OK for the callback to be invoked
+// after that happens.
 //
 // Therefore a Watcher needs to have some associated thread-safe state to track
 // its cancellation, which is why it's ref-counted.
 class Watcher : public base::RefCountedThreadSafe<Watcher> {
  public:
   using WatchCallback = base::Callback<void(MojoResult,
                                             const HandleSignalsState&,
                                             MojoWatchNotificationFlags)>;
 
   // Constructs a new Watcher which watches for |signals| to be satisfied on a
   // handle and which invokes |callback| either when one such signal is
   // satisfied, or all such signals become unsatisfiable.
   Watcher(MojoHandleSignals signals, const WatchCallback& callback);
 
   // Runs the Watcher's callback with the given arguments if it hasn't been
   // cancelled yet.
   void MaybeInvokeCallback(MojoResult result,
                            const HandleSignalsState& state,
                            MojoWatchNotificationFlags flags);
 
-  // Notifies the Watcher of a state change. This may result in the Watcher
-  // adding a finalizer to the current RequestContext to invoke its callback,
-  // cancellation notwithstanding.
-  void NotifyForStateChange(const HandleSignalsState& signals_state);
+  // Notifies the Watcher of the handle's current signals state. This may result
+  // in the Watcher adding a finalizer to the current RequestContext to invoke
+  // its callback if the watcher is currently armed and not cancelled by the
+  // the time the RequestContext is unwound.
+  void NotifyState(const HandleSignalsState& signals_state);
 
   // Notifies the Watcher of handle closure. This always results in the Watcher
-  // adding a finalizer to the current RequestContext to invoke its callback,
-  // cancellation notwithstanding.
+  // adding a finalizer to the current RequestContext to invoke its callback
+  // if the watcher has not been cancelled by the time the RequestContextd is
+  // unwound.
   void NotifyClosed();
 
+  // Arms the watch, ensuring that any relevant future state changes will elicit
+  // a single new notification. Returns MOJO_RESULT_OK, or some other error
+  // code otherwise. See documentation for the public |MojoArmWatcher()| API for
+  // details.
+  //
+  // |current_state| must reflect the state of the handle at the time of this
+  // call.
+  MojoResult Arm(const HandleSignalsState& current_state);
+
   // Explicitly cancels the watch, guaranteeing that its callback will never be
   // be invoked again.
   void Cancel();
 
  private:
   friend class base::RefCountedThreadSafe<Watcher>;
 
   ~Watcher();
 
   // The set of signals which are watched by this Watcher.
   const MojoHandleSignals signals_;
 
   // The callback to invoke with a result and signal state any time signals in
   // |signals_| are satisfied or become permanently unsatisfiable.
   const WatchCallback callback_;
 
-  // Guards |is_cancelled_|.
-  base::Lock lock_;
+  // Tracks whether or not the watcher is armed.
+  AtomicFlag is_armed_;
+
+  // Guards |is_cancelled_| and provides mutual exclusion for the notification
+  // callback and cancellation events.
+  base::Lock notification_lock_;
 
   // Indicates whether the watch has been cancelled. A |Watcher| may exist for a
   // brief period of time after being cancelled if it's been attached as a
   // RequestContext finalizer. In such cases the callback must not be invoked,
   // hence this flag.
   bool is_cancelled_ = false;
 
   DISALLOW_COPY_AND_ASSIGN(Watcher);
 };
 
 }  // namespace edk
 }  // namespace mojo
 
 #endif  // MOJO_EDK_SYSTEM_WATCHER_H_