Mojo: Armed Watchers

mojo/public/cpp/system/simple_watcher.h

+// Copyright 2017 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_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_
+#define MOJO_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_
+
+#include "base/callback.h"
+#include "base/location.h"
+#include "base/macros.h"
+#include "base/memory/ref_counted.h"
+#include "base/memory/weak_ptr.h"
+#include "base/threading/thread_checker.h"
+#include "base/threading/thread_task_runner_handle.h"
+#include "mojo/public/c/system/types.h"
+#include "mojo/public/cpp/system/system_export.h"
+#include "mojo/public/cpp/system/watcher.h"
+
+namespace base {
+class SingleThreadTaskRunner;
+}
+
+namespace mojo {
+
+// This provides a convenient thread-bound watcher implementation to safely
+// watch a single handle, dispatching state change notifications to an arbitrary
+// SingleThreadTaskRunner running on the same thread as the SimpleWatcher.
+class MOJO_CPP_SYSTEM_EXPORT SimpleWatcher {
+ public:
+  // A callback to be called any time a watched handle changes state in some
+  // interesting way. The |result| argument indicates one of the following
+  // conditions depending on its value:
+  //
+  //   |MOJO_RESULT_OK|: One or more of the signals being watched is satisfied.
+  //
+  //   |MOJO_RESULT_FAILED_PRECONDITION|: None of the signals being watched can
+  //       ever be satisfied again.
+  //
+  //   |MOJO_RESULT_CANCELLED|: The handle was closed while the SimpleWatcher is
+  //       still alive. No more notifications will be fired.
+  using ReadyCallback = base::Callback<void(MojoResult result)>;
+
+  // Selects how this SimpleWatcher is to be armed.

[mmenke, 2017/03/15 14:11:31]

Please add a definition of "arm", either here or above the class declaration, or
above the Arm() method.

[Ken Rockot(use gerrit already), 2017/03/15 17:33:28]

Done. I've tried to flesh out the documentation a bit more here.

+  enum class ArmingPolicy {
+    // The SimpleWatcher is armed automatically on Watch() and rearmed again
+    // after every invocation of the ReadyCallback. There is no need to manually
+    // call Arm() on a SimpleWatcher using this policy.
+    //
+    // This provides a reasonable approximation of edge-triggered behavior,
+    // mitigating (but not completely eliminating) the potential for redundant
+    // notifications.
+    //
+    // NOTE: It is important when using AUTOMATIC policy that your ReadyCallback
+    // always attempt to change the state of the handle (e.g. read available
+    // messages on a message pipe.) Otherwise this will result in a potentially
+    // large number of avoidable redundant tasks.
+    //
+    // For perfect edge-triggered behavior, use MANUAL policy and manually Arm()
+    // the SimpleWatcher as soon as it becomes possible to do so again.
+    AUTOMATIC,
+
+    // The SimpleWatcher is never armed automatically. Arm() must be called
+    // manually before any non-cancellation notification can be dispatched to
+    // the ReadyCallback. Immediately before the ReadyCallback is invoked, the
+    // SimpleWatcher is disarmed again and will require another manual call to
+    // Arm() before the next notification can fire.
+    MANUAL,
+  };
+
+  SimpleWatcher(const tracked_objects::Location& from_here,
+                ArmingPolicy arming_policy,
+                scoped_refptr<base::SingleThreadTaskRunner> runner =
+                    base::ThreadTaskRunnerHandle::Get());
+  ~SimpleWatcher();
+
+  // Indicates if the SimpleWatcher is currently watching a handle.
+  bool IsWatching() const;
+
+  // Starts watching |handle|. A SimpleWatcher may only watch one handle at a
+  // time, but it is safe to call this more than once as long as the previous
+  // watch has been cancelled (i.e. |IsWatching()| returns |false|.)
+  //
+  // If |handle| is not a valid watchable (message or data pipe) handle or
+  // |signals| is not a valid set of signals to watch, this returns
+  // |MOJO_RESULT_INVALID_ARGUMENT|.
+  //
+  // Otherwise |MOJO_RESULT_OK| is returned and the handle will be watched until
+  // either |handle| is closed, the SimpleWatcher is destroyed, or Cancel() is
+  // explicitly called.
+  //
+  // Once the watch is started, |callback| may be called at any time on the
+  // current thread until |Cancel()| is called or the handle is closed. Note
+  // that |callback| can be called for results other than
+  // |MOJO_RESULT_CANCELLED| only if the SimpleWatcher is currently armed. Use
+  // ArmingPolicy to configure how a SimpleWatcher is armed.
+  //
+  // |MOJO_RESULT_CANCELLED| may be dispatched even while the SimpleWatcher
+  // is disarmed, and no further notifications will be dispatched after that.
+  //
+  // Destroying the SimpleWatcher implicitly calls |Cancel()|.
+  MojoResult Watch(Handle handle,
+                   MojoHandleSignals signals,
+                   const ReadyCallback& callback);
+
+  // Cancels the current watch. Once this returns, the ReadyCallback previously
+  // passed to |Watch()| will never be called again for this SimpleWatcher.
+  //
+  // Note that when cancelled with an explicit call to |Cancel()| the
+  // ReadyCallback will not be invoked with a |MOJO_RESULT_CANCELLED| result.
+  void Cancel();
+
+  // Manually arm the watcher. If the watcher could not be armed because the
+  // watched handle would notify immediately, this returns
+  // |MOJO_RESULT_FAILED_PRECONDITION| and places what would be the result code
+  // of the notification into |*ready_result| if |ready_result| is non-null.
+  //
+  // If the watcher is successfully armed, this returns |MOJO_RESULT_OK| and
+  // |ready_result| is ignored.
+  MojoResult Arm(MojoResult* ready_result = nullptr);
+
+  // Manually arm the watcher, or post a task to invoke the ReadyCallback
+  // with the result of the failed arming attempt. This is meant as a convenient
+  // helper for a common usage of Arm(), and it ensures that the ReadyCallback
+  // will be invoked asynchronously again as soon as the watch's conditions are
+  // satisfied, assuming the SimpleWatcher isn't cancelled first.
+  //
+  // Unlike Arm() above, this can never fail.
+  void ArmOrNotify();
+
+  Handle handle() const { return handle_; }
+  ReadyCallback ready_callback() const { return callback_; }
+
+  // Sets the tag used by the heap profiler.
+  // |tag| must be a const string literal.
+  void set_heap_profiler_tag(const char* heap_profiler_tag) {
+    heap_profiler_tag_ = heap_profiler_tag;
+  }
+
+ private:
+  class Context;
+
+  void OnHandleReady(scoped_refptr<const Context> context, MojoResult result);
+
+  base::ThreadChecker thread_checker_;
+
+  // The policy used to determine how this SimpleWatcher is armed.
+  const ArmingPolicy arming_policy_;
+
+  // The TaskRunner of this SimpleWatcher's owning thread. This field is safe to
+  // access from any thread.
+  const scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
+
+  // Whether |task_runner_| is the same as base::ThreadTaskRunnerHandle::Get()
+  // for the thread.
+  const bool is_default_task_runner_;
+
+  ScopedWatcherHandle watcher_handle_;
+
+  // A thread-safe context object corresponding to the currently active watch,
+  // if any.
+  scoped_refptr<Context> context_;
+
+  // Fields below must only be accessed on the SimpleWatcher's owning thread.
+
+  // The handle currently under watch. Not owned.
+  Handle handle_;
+
+  // The callback to call when the handle is signaled.
+  ReadyCallback callback_;
+
+  // Tracks if the SimpleWatcher has already notified of unsatisfiability. This
+  // is used to prevent redundant notifications in AUTOMATIC mode.
+  bool unsatisfiable_ = false;
+
+  // Tag used to ID memory allocations that originated from notifications in
+  // this watcher.
+  const char* heap_profiler_tag_ = nullptr;
+
+  base::WeakPtrFactory<SimpleWatcher> weak_factory_;
+
+  DISALLOW_COPY_AND_ASSIGN(SimpleWatcher);
+};
+
+}  // namespace mojo
+
+#endif  // MOJO_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_