OLD | NEW |
| (Empty) |
1 // Copyright 2016 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_WATCHER_H_ | |
6 #define MOJO_PUBLIC_CPP_SYSTEM_WATCHER_H_ | |
7 | |
8 #include "base/callback.h" | |
9 #include "base/macros.h" | |
10 #include "base/memory/ref_counted.h" | |
11 #include "base/memory/scoped_ptr.h" | |
12 #include "base/memory/weak_ptr.h" | |
13 #include "base/single_thread_task_runner.h" | |
14 #include "base/threading/thread_checker.h" | |
15 #include "mojo/public/c/system/types.h" | |
16 #include "mojo/public/cpp/system/handle.h" | |
17 | |
18 namespace mojo { | |
19 | |
20 // A Watcher watches a single Mojo handle for signal state changes. | |
21 // | |
22 // NOTE: Watchers may only be used on threads which have a running MessageLoop. | |
23 class Watcher { | |
24 public: | |
25 // A callback to be called any time a watched handle changes state in some | |
26 // interesting way. The |result| argument indicates one of the following | |
27 // conditions depending on its value: | |
28 // | |
29 // |MOJO_RESULT_OK|: One or more of the signals being watched is satisfied. | |
30 // | |
31 // |MOJO_RESULT_FAILED_PRECONDITION|: None of the signals being watched can | |
32 // ever be satisfied again. | |
33 // | |
34 // |MOJO_RESULT_CANCELLED|: The handle has been closed and the watch has | |
35 // been cancelled implicitly. | |
36 // | |
37 // |MOJO_RESULT_ABORTED|: Notifications can no longer be delivered for this | |
38 // watcher for some unspecified reason, e.g., the watching thread may | |
39 // be shutting down soon. Note that it is still necessary to explicitly | |
40 // Cancel() the watch in this case. | |
41 using ReadyCallback = base::Callback<void(MojoResult result)>; | |
42 | |
43 // TODO(rockot/yzshen): Support giving Watcher an explicit TaskRunner for | |
44 // more fine-grained control over dispatch behavior. | |
45 Watcher(); | |
46 | |
47 // NOTE: This destructor automatically calls |Cancel()| if the Watcher is | |
48 // still active. | |
49 ~Watcher(); | |
50 | |
51 // Indicates if the Watcher is currently watching a handle. | |
52 bool IsWatching() const; | |
53 | |
54 // Starts watching |handle|. A Watcher may only watch one handle at a time, | |
55 // but it is safe to call this more than once as long as the previous watch | |
56 // has been cancelled (i.e. |is_watching()| returns |false|.) | |
57 // | |
58 // If no signals in |signals| can ever be satisfied for |handle|, this returns | |
59 // |MOJO_RESULT_FAILED_PRECONDITION|. | |
60 // | |
61 // If |handle| is not a valid watchable (message or data pipe) handle, this | |
62 // returns |MOJO_RESULT_INVALID_ARGUMENT|. | |
63 // | |
64 // Otherwise |MOJO_RESULT_OK| is returned and the handle will be watched until | |
65 // closure or cancellation. | |
66 // | |
67 // Once the watch is started, |callback| may be called at any time on the | |
68 // current thread until |Cancel()| is called or the handle is closed. | |
69 // | |
70 // Destroying the Watcher implicitly calls |Cancel()|. | |
71 MojoResult Start(Handle handle, | |
72 MojoHandleSignals signals, | |
73 const ReadyCallback& callback); | |
74 | |
75 // Cancels the current watch. Once this returns, the callback previously | |
76 // passed to |Start()| will never be called again for this Watcher. | |
77 void Cancel(); | |
78 | |
79 private: | |
80 class MessageLoopObserver; | |
81 friend class MessageLoopObserver; | |
82 | |
83 void OnHandleReady(MojoResult result); | |
84 | |
85 static void CallOnHandleReady(uintptr_t context, | |
86 MojoResult result, | |
87 MojoHandleSignalsState signals_state); | |
88 | |
89 base::ThreadChecker thread_checker_; | |
90 | |
91 // The TaskRunner of this Watcher's owning thread. This field is safe to | |
92 // access from any thread. | |
93 const scoped_refptr<base::SingleThreadTaskRunner> task_runner_; | |
94 | |
95 scoped_ptr<MessageLoopObserver> message_loop_observer_; | |
96 | |
97 // A persistent weak reference to this Watcher which can be passed to the | |
98 // Dispatcher any time this object should be signalled. Safe to access (but | |
99 // not to dereference!) from any thread. | |
100 base::WeakPtr<Watcher> weak_self_; | |
101 | |
102 // Fields below must only be accessed on the Watcher's owning thread. | |
103 | |
104 // The handle currently under watch. Not owned. | |
105 Handle handle_; | |
106 | |
107 // The callback to call when the handle is signaled. | |
108 ReadyCallback callback_; | |
109 | |
110 base::WeakPtrFactory<Watcher> weak_factory_; | |
111 | |
112 DISALLOW_COPY_AND_ASSIGN(Watcher); | |
113 }; | |
114 | |
115 } // namespace mojo | |
116 | |
117 #endif // MOJO_PUBLIC_CPP_SYSTEM_WATCHER_H_ | |
OLD | NEW |