OLD | NEW |
(Empty) | |
| 1 // Copyright 2017 The Chromium Authors. All rights reserved. |
| 2 // Use of this source code is governed by a BSD-style license that can be |
| 3 // found in the LICENSE file. |
| 4 |
| 5 #ifndef MOJO_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_ |
| 6 #define MOJO_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_ |
| 7 |
| 8 #include "base/callback.h" |
| 9 #include "base/location.h" |
| 10 #include "base/macros.h" |
| 11 #include "base/memory/ref_counted.h" |
| 12 #include "base/memory/weak_ptr.h" |
| 13 #include "base/threading/thread_checker.h" |
| 14 #include "base/threading/thread_task_runner_handle.h" |
| 15 #include "mojo/public/c/system/types.h" |
| 16 #include "mojo/public/cpp/system/system_export.h" |
| 17 #include "mojo/public/cpp/system/watcher.h" |
| 18 |
| 19 namespace base { |
| 20 class SingleThreadTaskRunner; |
| 21 } |
| 22 |
| 23 namespace mojo { |
| 24 |
| 25 // This provides a convenient thread-bound watcher implementation to safely |
| 26 // watch a single handle, dispatching state change notifications to an arbitrary |
| 27 // SingleThreadTaskRunner running on the same thread as the SimpleWatcher. |
| 28 class MOJO_CPP_SYSTEM_EXPORT SimpleWatcher { |
| 29 public: |
| 30 // A callback to be called any time a watched handle changes state in some |
| 31 // interesting way. The |result| argument indicates one of the following |
| 32 // conditions depending on its value: |
| 33 // |
| 34 // |MOJO_RESULT_OK|: One or more of the signals being watched is satisfied. |
| 35 // |
| 36 // |MOJO_RESULT_FAILED_PRECONDITION|: None of the signals being watched can |
| 37 // ever be satisfied again. |
| 38 // |
| 39 // |MOJO_RESULT_CANCELLED|: The handle was closed while the SimpleWatcher is |
| 40 // still alive. No more notifications will be fired. |
| 41 using ReadyCallback = base::Callback<void(MojoResult result)>; |
| 42 |
| 43 // Selects how this SimpleWatcher is to be armed. |
| 44 enum class ArmingPolicy { |
| 45 // The SimpleWatcher is armed automatically on Watch() and rearmed again |
| 46 // after every invocation of the ReadyCallback. There is no need to manually |
| 47 // call Arm() on a SimpleWatcher using this policy. |
| 48 // |
| 49 // This provides a reasonable approximation of edge-triggered behavior, |
| 50 // mitigating (but not completely eliminating) the potential for redundant |
| 51 // notifications. |
| 52 // |
| 53 // NOTE: It is important when using AUTOMATIC policy that your ReadyCallback |
| 54 // always attempt to change the state of the handle (e.g. read available |
| 55 // messages on a message pipe.) Otherwise this will result in a potentially |
| 56 // large number of avoidable redundant tasks. |
| 57 // |
| 58 // For perfect edge-triggered behavior, use MANUAL policy and manually Arm() |
| 59 // the SimpleWatcher as soon as it becomes possible to do so again. |
| 60 AUTOMATIC, |
| 61 |
| 62 // The SimpleWatcher is never armed automatically. Arm() must be called |
| 63 // manually before any non-cancellation notification can be dispatched to |
| 64 // the ReadyCallback. Immediately before the ReadyCallback is invoked, the |
| 65 // SimpleWatcher is disarmed again and will require another manual call to |
| 66 // Arm() before the next notification can fire. |
| 67 MANUAL, |
| 68 }; |
| 69 |
| 70 SimpleWatcher(const tracked_objects::Location& from_here, |
| 71 ArmingPolicy arming_policy, |
| 72 scoped_refptr<base::SingleThreadTaskRunner> runner = |
| 73 base::ThreadTaskRunnerHandle::Get()); |
| 74 ~SimpleWatcher(); |
| 75 |
| 76 // Indicates if the SimpleWatcher is currently watching a handle. |
| 77 bool IsWatching() const; |
| 78 |
| 79 // Starts watching |handle|. A SimpleWatcher may only watch one handle at a |
| 80 // time, but it is safe to call this more than once as long as the previous |
| 81 // watch has been cancelled (i.e. |IsWatching()| returns |false|.) |
| 82 // |
| 83 // If |handle| is not a valid watchable (message or data pipe) handle or |
| 84 // |signals| is not a valid set of signals to watch, this returns |
| 85 // |MOJO_RESULT_INVALID_ARGUMENT|. |
| 86 // |
| 87 // Otherwise |MOJO_RESULT_OK| is returned and the handle will be watched until |
| 88 // either |handle| is closed, the SimpleWatcher is destroyed, or Cancel() is |
| 89 // explicitly called. |
| 90 // |
| 91 // Once the watch is started, |callback| may be called at any time on the |
| 92 // current thread until |Cancel()| is called or the handle is closed. Note |
| 93 // that |callback| can be called for results other than |
| 94 // |MOJO_RESULT_CANCELLED| only if the SimpleWatcher is currently armed. Use |
| 95 // ArmingPolicy to configure how a SimpleWatcher is armed. |
| 96 // |
| 97 // |MOJO_RESULT_CANCELLED| may be dispatched even while the SimpleWatcher |
| 98 // is disarmed, and no further notifications will be dispatched after that. |
| 99 // |
| 100 // Destroying the SimpleWatcher implicitly calls |Cancel()|. |
| 101 MojoResult Watch(Handle handle, |
| 102 MojoHandleSignals signals, |
| 103 const ReadyCallback& callback); |
| 104 |
| 105 // Cancels the current watch. Once this returns, the ReadyCallback previously |
| 106 // passed to |Watch()| will never be called again for this SimpleWatcher. |
| 107 // |
| 108 // Note that when cancelled with an explicit call to |Cancel()| the |
| 109 // ReadyCallback will not be invoked with a |MOJO_RESULT_CANCELLED| result. |
| 110 void Cancel(); |
| 111 |
| 112 // Manually arm the watcher. If the watcher could not be armed because the |
| 113 // watched handle would notify immediately, this returns |
| 114 // |MOJO_RESULT_FAILED_PRECONDITION| and places what would be the result code |
| 115 // of the notification into |*ready_result| if |ready_result| is non-null. |
| 116 // |
| 117 // If the watcher is successfully armed, this returns |MOJO_RESULT_OK| and |
| 118 // |ready_result| is ignored. |
| 119 MojoResult Arm(MojoResult* ready_result = nullptr); |
| 120 |
| 121 // Manually arm the watcher, or post a task to invoke the ReadyCallback |
| 122 // with the result of the failed arming attempt. This is meant as a convenient |
| 123 // helper for a common usage of Arm(), and it ensures that the ReadyCallback |
| 124 // will be invoked asynchronously again as soon as the watch's conditions are |
| 125 // satisfied, assuming the SimpleWatcher isn't cancelled first. |
| 126 // |
| 127 // Unlike Arm() above, this can never fail. |
| 128 void ArmOrNotify(); |
| 129 |
| 130 Handle handle() const { return handle_; } |
| 131 ReadyCallback ready_callback() const { return callback_; } |
| 132 |
| 133 // Sets the tag used by the heap profiler. |
| 134 // |tag| must be a const string literal. |
| 135 void set_heap_profiler_tag(const char* heap_profiler_tag) { |
| 136 heap_profiler_tag_ = heap_profiler_tag; |
| 137 } |
| 138 |
| 139 private: |
| 140 class Context; |
| 141 |
| 142 void OnHandleReady(scoped_refptr<const Context> context, MojoResult result); |
| 143 |
| 144 base::ThreadChecker thread_checker_; |
| 145 |
| 146 // The policy used to determine how this SimpleWatcher is armed. |
| 147 const ArmingPolicy arming_policy_; |
| 148 |
| 149 // The TaskRunner of this SimpleWatcher's owning thread. This field is safe to |
| 150 // access from any thread. |
| 151 const scoped_refptr<base::SingleThreadTaskRunner> task_runner_; |
| 152 |
| 153 // Whether |task_runner_| is the same as base::ThreadTaskRunnerHandle::Get() |
| 154 // for the thread. |
| 155 const bool is_default_task_runner_; |
| 156 |
| 157 ScopedWatcherHandle watcher_handle_; |
| 158 |
| 159 // A thread-safe context object corresponding to the currently active watch, |
| 160 // if any. |
| 161 scoped_refptr<Context> context_; |
| 162 |
| 163 // Fields below must only be accessed on the SimpleWatcher's owning thread. |
| 164 |
| 165 // The handle currently under watch. Not owned. |
| 166 Handle handle_; |
| 167 |
| 168 // The callback to call when the handle is signaled. |
| 169 ReadyCallback callback_; |
| 170 |
| 171 // Tracks if the SimpleWatcher has already notified of unsatisfiability. This |
| 172 // is used to prevent redundant notifications in AUTOMATIC mode. |
| 173 bool unsatisfiable_ = false; |
| 174 |
| 175 // Tag used to ID memory allocations that originated from notifications in |
| 176 // this watcher. |
| 177 const char* heap_profiler_tag_ = nullptr; |
| 178 |
| 179 base::WeakPtrFactory<SimpleWatcher> weak_factory_; |
| 180 |
| 181 DISALLOW_COPY_AND_ASSIGN(SimpleWatcher); |
| 182 }; |
| 183 |
| 184 } // namespace mojo |
| 185 |
| 186 #endif // MOJO_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_ |
OLD | NEW |