object_watcher.h (3893B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */ 3 // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved. 4 // Use of this source code is governed by a BSD-style license that can be 5 // found in the LICENSE file. 6 7 #ifndef BASE_OBJECT_WATCHER_H_ 8 #define BASE_OBJECT_WATCHER_H_ 9 10 #include <windows.h> 11 #ifdef GetClassName 12 # undef GetClassName 13 #endif 14 15 #include "base/message_loop.h" 16 17 namespace base { 18 19 // A class that provides a means to asynchronously wait for a Windows object to 20 // become signaled. It is an abstraction around RegisterWaitForSingleObject 21 // that provides a notification callback, OnObjectSignaled, that runs back on 22 // the origin thread (i.e., the thread that called StartWatching). 23 // 24 // This class acts like a smart pointer such that when it goes out-of-scope, 25 // UnregisterWaitEx is automatically called, and any in-flight notification is 26 // suppressed. 27 // 28 // Typical usage: 29 // 30 // ``` 31 // class MyClass : public base::ObjectWatcher::Delegate { 32 // public: 33 // void DoStuffWhenSignaled(HANDLE object) { 34 // watcher_.StartWatching(object, this); 35 // } 36 // virtual void OnObjectSignaled(HANDLE object) { 37 // // OK, time to do stuff! 38 // } 39 // private: 40 // base::ObjectWatcher watcher_; 41 // }; 42 // ``` 43 // 44 // In the above example, MyClass wants to "do stuff" when object becomes 45 // signaled. ObjectWatcher makes this task easy. When MyClass goes out of 46 // scope, the watcher_ will be destroyed, and there is no need to worry about 47 // OnObjectSignaled being called on a deleted MyClass pointer. Easy! 48 // 49 ////// 50 // 51 // Mozilla/Gecko addendum: 52 // 53 // An undocumented (but runtime-asserted) requirement for the above is that 54 // `MyClass` must be strictly thread-affine. In particular, `StartWatching()` 55 // and `StopWatching()` -- including the implicit `StopWatching()` call in 56 // `~ObjectWatcher()` -- must always be called on the same thread and from 57 // within the same `MessageLoop`. 58 // 59 // (If this did not hold, `OnObjectSignaled()` might be called on one thread 60 // while `MyClass` is in the middle of being destroyed on another.) 61 // 62 // This condition cannot be guaranteed for potentially-asynchronously-destroyed 63 // classes, nor for their owned or shared subobjects, nor for anything which 64 // might be sent to a non-thread-affine task queue. 65 // 66 class ObjectWatcher : public MessageLoop::DestructionObserver { 67 public: 68 class Delegate { 69 public: 70 virtual ~Delegate() {} 71 // Called from the MessageLoop when a signaled object is detected. To 72 // continue watching the object, AddWatch must be called again. 73 virtual void OnObjectSignaled(HANDLE object) = 0; 74 }; 75 76 ObjectWatcher(); 77 ~ObjectWatcher(); 78 79 // When the object is signaled, the given delegate is notified on the thread 80 // where StartWatching is called. The ObjectWatcher is not responsible for 81 // deleting the delegate. 82 // 83 // Returns true if the watch was started. Otherwise, false is returned. 84 // 85 bool StartWatching(HANDLE object, Delegate* delegate); 86 87 // Stops watching. Does nothing if the watch has already completed. If the 88 // watch is still active, then it is canceled, and the associated delegate is 89 // not notified. 90 // 91 // Returns true if the watch was canceled. Otherwise, false is returned. 92 // 93 bool StopWatching(); 94 95 // Returns the handle of the object being watched, or NULL if the object 96 // watcher is stopped. 97 HANDLE GetWatchedObject(); 98 99 private: 100 // Called on a background thread when done waiting. 101 static void CALLBACK DoneWaiting(void* param, BOOLEAN timed_out); 102 103 // MessageLoop::DestructionObserver implementation: 104 virtual void WillDestroyCurrentMessageLoop(); 105 106 // Internal state. 107 class Watch; 108 RefPtr<Watch> watch_; 109 110 DISALLOW_COPY_AND_ASSIGN(ObjectWatcher); 111 }; 112 113 } // namespace base 114 115 #endif // BASE_OBJECT_WATCHER_H_