Home | History | Annotate | Download | only in base 
      1 // Copyright (c) 2006-2008 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 BASE_OBJECT_WATCHER_H_
      6 #define BASE_OBJECT_WATCHER_H_
      7 
      8 #include <windows.h>
      9 
     10 #include "base/message_loop.h"
     11 
     12 namespace base {
     13 
     14 // A class that provides a means to asynchronously wait for a Windows object to
     15 // become signaled.  It is an abstraction around RegisterWaitForSingleObject
     16 // that provides a notification callback, OnObjectSignaled, that runs back on
     17 // the origin thread (i.e., the thread that called StartWatching).
     18 //
     19 // This class acts like a smart pointer such that when it goes out-of-scope,
     20 // UnregisterWaitEx is automatically called, and any in-flight notification is
     21 // suppressed.
     22 //
     23 // Typical usage:
     24 //
     25 //   class MyClass : public base::ObjectWatcher::Delegate {
     26 //    public:
     27 //     void DoStuffWhenSignaled(HANDLE object) {
     28 //       watcher_.StartWatching(object, this);
     29 //     }
     30 //     virtual void OnObjectSignaled(HANDLE object) {
     31 //       // OK, time to do stuff!
     32 //     }
     33 //    private:
     34 //     base::ObjectWatcher watcher_;
     35 //   };
     36 //
     37 // In the above example, MyClass wants to "do stuff" when object becomes
     38 // signaled.  ObjectWatcher makes this task easy.  When MyClass goes out of
     39 // scope, the watcher_ will be destroyed, and there is no need to worry about
     40 // OnObjectSignaled being called on a deleted MyClass pointer.  Easy!
     41 //
     42 class ObjectWatcher : public MessageLoop::DestructionObserver {
     43  public:
     44   class Delegate {
     45    public:
     46     virtual ~Delegate() {}
     47     // Called from the MessageLoop when a signaled object is detected.  To
     48     // continue watching the object, AddWatch must be called again.
     49     virtual void OnObjectSignaled(HANDLE object) = 0;
     50   };
     51 
     52   ObjectWatcher();
     53   ~ObjectWatcher();
     54 
     55   // When the object is signaled, the given delegate is notified on the thread
     56   // where StartWatching is called.  The ObjectWatcher is not responsible for
     57   // deleting the delegate.
     58   //
     59   // Returns true if the watch was started.  Otherwise, false is returned.
     60   //
     61   bool StartWatching(HANDLE object, Delegate* delegate);
     62 
     63   // Stops watching.  Does nothing if the watch has already completed.  If the
     64   // watch is still active, then it is canceled, and the associated delegate is
     65   // not notified.
     66   //
     67   // Returns true if the watch was canceled.  Otherwise, false is returned.
     68   //
     69   bool StopWatching();
     70 
     71   // Returns the handle of the object being watched, or NULL if the object
     72   // watcher is stopped.
     73   HANDLE GetWatchedObject();
     74 
     75  private:
     76   // Called on a background thread when done waiting.
     77   static void CALLBACK DoneWaiting(void* param, BOOLEAN timed_out);
     78 
     79   // MessageLoop::DestructionObserver implementation:
     80   virtual void WillDestroyCurrentMessageLoop();
     81 
     82   // Internal state.
     83   struct Watch;
     84   Watch* watch_;
     85 
     86   DISALLOW_COPY_AND_ASSIGN(ObjectWatcher);
     87 };
     88 
     89 }  // namespace base
     90 
     91 #endif  // BASE_OBJECT_WATCHER_H_
     92