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