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 convnient thread-bound watcher implementation to safely watch | |
yzshen1
2017/03/13 20:21:18
convnient -> convenient
Ken Rockot(use gerrit already)
2017/03/13 22:00:10
Done
| |
26 // 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| will only be called for results other than | |
94 // |MOJO_RESULT_CANCELLED| if the SimpleWatcher is currently armed. Use | |
yzshen1
2017/03/13 20:21:18
I haven't understood this. Why is CANCELLED not di
Ken Rockot(use gerrit already)
2017/03/13 22:00:10
Sorry, wording is bad. CANCELLED is always dispatc
| |
95 // ArmingPolicy to configure how a SimpleWatcher is armed. | |
96 // | |
97 // Destroying the SimpleWatcher implicitly calls |Cancel()|. | |
98 MojoResult Watch(Handle handle, | |
99 MojoHandleSignals signals, | |
100 const ReadyCallback& callback); | |
101 | |
102 // Cancels the current watch. Once this returns, the ReadyCallback previously | |
103 // passed to |Watch()| will never be called again for this SimpleWatcher. | |
104 // | |
105 // Note that when cancelled with an explicit call to |Cancel()| the | |
106 // ReadyCallback will not be invoked with a |MOJO_RESULT_CANCELLED| result. | |
107 void Cancel(); | |
108 | |
109 // Manually arm the watcher. If the watcher could not be armed because the | |
110 // watched handle would notify immediately, this returns | |
111 // |MOJO_RESULT_FAILED_PRECONDITION| and places what would be the result code | |
112 // of the notification into |*ready_result| if |ready_result| is non-null. | |
113 // | |
114 // If the watcher is successfully armed, this returns |MOJO_RESULT_OK| and | |
115 // |ready_result| is ignored. | |
116 MojoResult Arm(MojoResult* ready_result = nullptr); | |
117 | |
118 // Manually arm the watcher, or post a task to invoke the ReadyCallback | |
119 // with the result of the failed arming attempt. This is meant as a convenient | |
120 // helper for a common usage of Arm(), and it ensures that the ReadyCallback | |
121 // will be invoked asynchronously again as soon as the watch's conditions are | |
122 // satisfied, assuming the SimpleWatcher isn't cancelled first. | |
123 // | |
124 // Unlike Arm() above, this can never fail. | |
125 void ArmOrNotify(); | |
126 | |
127 Handle handle() const { return handle_; } | |
128 ReadyCallback ready_callback() const { return callback_; } | |
129 | |
130 // Sets the tag used by the heap profiler. | |
131 // |tag| must be a const string literal. | |
132 void set_heap_profiler_tag(const char* heap_profiler_tag) { | |
133 heap_profiler_tag_ = heap_profiler_tag; | |
134 } | |
135 | |
136 private: | |
137 class Context; | |
138 | |
139 void OnHandleReady(scoped_refptr<const Context> context, MojoResult result); | |
140 | |
141 base::ThreadChecker thread_checker_; | |
142 | |
143 // The policy used to determine how this SimpleWatcher is armed. | |
144 const ArmingPolicy arming_policy_; | |
145 | |
146 // The TaskRunner of this SimpleWatcher's owning thread. This field is safe to | |
147 // access from any thread. | |
148 const scoped_refptr<base::SingleThreadTaskRunner> task_runner_; | |
149 | |
150 // Whether |task_runner_| is the same as base::ThreadTaskRunnerHandle::Get() | |
151 // for the thread. | |
152 const bool is_default_task_runner_; | |
153 | |
154 ScopedWatcherHandle watcher_handle_; | |
155 | |
156 // A thread-safe context object corresponding to the currently active watch, | |
157 // if any. | |
158 scoped_refptr<Context> context_; | |
159 | |
160 // Fields below must only be accessed on the SimpleWatcher's owning thread. | |
161 | |
162 // The handle currently under watch. Not owned. | |
163 Handle handle_; | |
164 | |
165 // The callback to call when the handle is signaled. | |
166 ReadyCallback callback_; | |
167 | |
168 // Tracks if the SimpleWatcher has already notified of unsatisfiability. This | |
169 // is used to prevent redundant notifications in AUTOMATIC mode. | |
170 bool unsatisfiable_ = false; | |
171 | |
172 // Tag used to ID memory allocations that originated from notifications in | |
173 // this watcher. | |
174 const char* heap_profiler_tag_ = nullptr; | |
175 | |
176 base::WeakPtrFactory<SimpleWatcher> weak_factory_; | |
177 | |
178 DISALLOW_COPY_AND_ASSIGN(SimpleWatcher); | |
179 }; | |
180 | |
181 } // namespace mojo | |
182 | |
183 #endif // MOJO_PUBLIC_CPP_SYSTEM_SIMPLE_WATCHER_H_ | |
OLD | NEW |