| 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 // | |
| 29 // SimpleWatcher exposes the concept of "arming" from the low-level Watcher API. | |
| 30 // In general, a SimpleWatcher must be "armed" in order to dispatch a single | |
| 31 // notification, and must then be rearmed before it will dispatch another. For | |
| 32 // more details, see the documentation for ArmingPolicy and the Arm() and | |
| 33 // ArmOrNotify() methods below. | |
| 34 class MOJO_CPP_SYSTEM_EXPORT SimpleWatcher { | |
| 35 public: | |
| 36 // A callback to be called any time a watched handle changes state in some | |
| 37 // interesting way. The |result| argument indicates one of the following | |
| 38 // conditions depending on its value: | |
| 39 // | |
| 40 // |MOJO_RESULT_OK|: One or more of the signals being watched is satisfied. | |
| 41 // | |
| 42 // |MOJO_RESULT_FAILED_PRECONDITION|: None of the signals being watched can | |
| 43 // ever be satisfied again. | |
| 44 // | |
| 45 // |MOJO_RESULT_CANCELLED|: The watched handle has been closed. No further | |
| 46 // notifications will be fired, as this equivalent to an implicit | |
| 47 // CancelWatch(). | |
| 48 // | |
| 49 // Note that unlike the first two conditions, this callback may be invoked | |
| 50 // with |MOJO_RESULT_CANCELLED| even while the SimpleWatcher is disarmed. | |
| 51 using ReadyCallback = base::Callback<void(MojoResult result)>; | |
| 52 | |
| 53 // Selects how this SimpleWatcher is to be armed. | |
| 54 enum class ArmingPolicy { | |
| 55 // The SimpleWatcher is armed automatically on Watch() and rearmed again | |
| 56 // after every invocation of the ReadyCallback. There is no need to manually | |
| 57 // call Arm() on a SimpleWatcher using this policy. This mode is equivalent | |
| 58 // to calling ArmOrNotify() once after Watch() and once again after every | |
| 59 // dispatched notification in MANUAL mode. | |
| 60 // | |
| 61 // This provides a reasonable approximation of edge-triggered behavior, | |
| 62 // mitigating (but not completely eliminating) the potential for redundant | |
| 63 // notifications. | |
| 64 // | |
| 65 // NOTE: It is important when using AUTOMATIC policy that your ReadyCallback | |
| 66 // always attempt to change the state of the handle (e.g. read available | |
| 67 // messages on a message pipe.) Otherwise this will result in a potentially | |
| 68 // large number of avoidable redundant tasks. | |
| 69 // | |
| 70 // For perfect edge-triggered behavior, use MANUAL policy and manually Arm() | |
| 71 // the SimpleWatcher as soon as it becomes possible to do so again. | |
| 72 AUTOMATIC, | |
| 73 | |
| 74 // The SimpleWatcher is never armed automatically. Arm() or ArmOrNotify() | |
| 75 // must be called manually before any non-cancellation notification can be | |
| 76 // dispatched to the ReadyCallback. See the documentation for Arm() and | |
| 77 // ArmNotify() methods below for more details. | |
| 78 MANUAL, | |
| 79 }; | |
| 80 | |
| 81 SimpleWatcher(const tracked_objects::Location& from_here, | |
| 82 ArmingPolicy arming_policy, | |
| 83 scoped_refptr<base::SingleThreadTaskRunner> runner = | |
| 84 base::ThreadTaskRunnerHandle::Get()); | |
| 85 ~SimpleWatcher(); | |
| 86 | |
| 87 // Indicates if the SimpleWatcher is currently watching a handle. | |
| 88 bool IsWatching() const; | |
| 89 | |
| 90 // Starts watching |handle|. A SimpleWatcher may only watch one handle at a | |
| 91 // time, but it is safe to call this more than once as long as the previous | |
| 92 // watch has been cancelled (i.e. |IsWatching()| returns |false|.) | |
| 93 // | |
| 94 // If |handle| is not a valid watchable (message or data pipe) handle or | |
| 95 // |signals| is not a valid set of signals to watch, this returns | |
| 96 // |MOJO_RESULT_INVALID_ARGUMENT|. | |
| 97 // | |
| 98 // Otherwise |MOJO_RESULT_OK| is returned and the handle will be watched until | |
| 99 // either |handle| is closed, the SimpleWatcher is destroyed, or Cancel() is | |
| 100 // explicitly called. | |
| 101 // | |
| 102 // Once the watch is started, |callback| may be called at any time on the | |
| 103 // current thread until |Cancel()| is called or the handle is closed. Note | |
| 104 // that |callback| can be called for results other than | |
| 105 // |MOJO_RESULT_CANCELLED| only if the SimpleWatcher is currently armed. Use | |
| 106 // ArmingPolicy to configure how a SimpleWatcher is armed. | |
| 107 // | |
| 108 // |MOJO_RESULT_CANCELLED| may be dispatched even while the SimpleWatcher | |
| 109 // is disarmed, and no further notifications will be dispatched after that. | |
| 110 // | |
| 111 // Destroying the SimpleWatcher implicitly calls |Cancel()|. | |
| 112 MojoResult Watch(Handle handle, | |
| 113 MojoHandleSignals signals, | |
| 114 const ReadyCallback& callback); | |
| 115 | |
| 116 // Cancels the current watch. Once this returns, the ReadyCallback previously | |
| 117 // passed to |Watch()| will never be called again for this SimpleWatcher. | |
| 118 // | |
| 119 // Note that when cancelled with an explicit call to |Cancel()| the | |
| 120 // ReadyCallback will not be invoked with a |MOJO_RESULT_CANCELLED| result. | |
| 121 void Cancel(); | |
| 122 | |
| 123 // Manually arms the SimpleWatcher. | |
| 124 // | |
| 125 // Arming the SimpleWatcher allows it to fire a single notification regarding | |
| 126 // some future relevant change in the watched handle's state. It's only valid | |
| 127 // to call Arm() while a handle is being watched (see Watch() above.) | |
| 128 // | |
| 129 // SimpleWatcher is always disarmed immediately before invoking its | |
| 130 // ReadyCallback and must be rearmed again before another notification can | |
| 131 // fire. | |
| 132 // | |
| 133 // If the watched handle already meets the watched signaling conditions - | |
| 134 // i.e., if it would have notified immediately once armed - the SimpleWatcher | |
| 135 // is NOT armed, and this call fails with a return value of | |
| 136 // |MOJO_RESULT_FAILED_PRECONDITION|. In that case, what would have been the | |
| 137 // result code for that immediate notification is instead placed in | |
| 138 // |*ready_result| if |ready_result| is non-null. | |
| 139 // | |
| 140 // If the watcher is successfully armed, this returns |MOJO_RESULT_OK| and | |
| 141 // |ready_result| is ignored. | |
| 142 MojoResult Arm(MojoResult* ready_result = nullptr); | |
| 143 | |
| 144 // Manually arms the SimpleWatcher OR posts a task to invoke the ReadyCallback | |
| 145 // with the ready result of the failed arming attempt. | |
| 146 // | |
| 147 // This is meant as a convenient helper for a common usage of Arm(), and it | |
| 148 // ensures that the ReadyCallback will be invoked asynchronously again as soon | |
| 149 // as the watch's conditions are satisfied, assuming the SimpleWatcher isn't | |
| 150 // cancelled first. | |
| 151 // | |
| 152 // Unlike Arm() above, this can never fail. | |
| 153 void ArmOrNotify(); | |
| 154 | |
| 155 Handle handle() const { return handle_; } | |
| 156 ReadyCallback ready_callback() const { return callback_; } | |
| 157 | |
| 158 // Sets the tag used by the heap profiler. | |
| 159 // |tag| must be a const string literal. | |
| 160 void set_heap_profiler_tag(const char* heap_profiler_tag) { | |
| 161 heap_profiler_tag_ = heap_profiler_tag; | |
| 162 } | |
| 163 | |
| 164 private: | |
| 165 class Context; | |
| 166 | |
| 167 void OnHandleReady(scoped_refptr<const Context> context, MojoResult result); | |
| 168 | |
| 169 base::ThreadChecker thread_checker_; | |
| 170 | |
| 171 // The policy used to determine how this SimpleWatcher is armed. | |
| 172 const ArmingPolicy arming_policy_; | |
| 173 | |
| 174 // The TaskRunner of this SimpleWatcher's owning thread. This field is safe to | |
| 175 // access from any thread. | |
| 176 const scoped_refptr<base::SingleThreadTaskRunner> task_runner_; | |
| 177 | |
| 178 // Whether |task_runner_| is the same as base::ThreadTaskRunnerHandle::Get() | |
| 179 // for the thread. | |
| 180 const bool is_default_task_runner_; | |
| 181 | |
| 182 ScopedWatcherHandle watcher_handle_; | |
| 183 | |
| 184 // A thread-safe context object corresponding to the currently active watch, | |
| 185 // if any. | |
| 186 scoped_refptr<Context> context_; | |
| 187 | |
| 188 // Fields below must only be accessed on the SimpleWatcher's owning thread. | |
| 189 | |
| 190 // The handle currently under watch. Not owned. | |
| 191 Handle handle_; | |
| 192 | |
| 193 // The callback to call when the handle is signaled. | |
| 194 ReadyCallback callback_; | |
| 195 | |
| 196 // Tracks if the SimpleWatcher has already notified of unsatisfiability. This | |
| 197 // is used to prevent redundant notifications in AUTOMATIC mode. | |
| 198 bool unsatisfiable_ = false; | |
| 199 | |
| 200 // Tag used to ID memory allocations that originated from notifications in | |
| 201 // this watcher. | |
| 202 const char* heap_profiler_tag_ = nullptr; | |
| 203 | |
| 204 base::WeakPtrFactory<SimpleWatcher> weak_factory_; | |
| 205 | |
| 206 DISALLOW_COPY_AND_ASSIGN(SimpleWatcher); | |
| 207 }; | |
| 208 | |
| 209 } // namespace mojo | |
| 210 | |
| 211 #endif // MOJO_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2750373002:
Revert of Mojo: Armed Watchers (Closed)
