base/message_pump.h

   1 // Copyright (c) 2012 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_MESSAGE_PUMP_H_
   6 #define BASE_MESSAGE_PUMP_H_
   7
   8 #include "base/base_export.h"
   9 #include "base/memory/ref_counted.h"
  10
  11 namespace base {
  12
  13 class TimeTicks;
  14
  15 class BASE_EXPORT MessagePump : public RefCountedThreadSafe<MessagePump> {
  16  public:
  17   // Please see the comments above the Run method for an illustration of how
  18   // these delegate methods are used.
  19   class BASE_EXPORT Delegate {
  20    public:
  21     virtual ~Delegate() {}
  22
  23     // Called from within Run in response to ScheduleWork or when the message
  24     // pump would otherwise call DoDelayedWork.  Returns true to indicate that
  25     // work was done.  DoDelayedWork will still be called if DoWork returns
  26     // true, but DoIdleWork will not.
  27     virtual bool DoWork() = 0;
  28
  29     // Called from within Run in response to ScheduleDelayedWork or when the
  30     // message pump would otherwise sleep waiting for more work.  Returns true
  31     // to indicate that delayed work was done.  DoIdleWork will not be called
  32     // if DoDelayedWork returns true.  Upon return |next_delayed_work_time|
  33     // indicates the time when DoDelayedWork should be called again.  If
  34     // |next_delayed_work_time| is null (per Time::is_null), then the queue of
  35     // future delayed work (timer events) is currently empty, and no additional
  36     // calls to this function need to be scheduled.
  37     virtual bool DoDelayedWork(TimeTicks* next_delayed_work_time) = 0;
  38
  39     // Called from within Run just before the message pump goes to sleep.
  40     // Returns true to indicate that idle work was done.
  41     virtual bool DoIdleWork() = 0;
  42   };
  43
  44   MessagePump();
  45
  46   // The Run method is called to enter the message pump's run loop.
  47   //
  48   // Within the method, the message pump is responsible for processing native
  49   // messages as well as for giving cycles to the delegate periodically.  The
  50   // message pump should take care to mix delegate callbacks with native
  51   // message processing so neither type of event starves the other of cycles.
  52   //
  53   // The anatomy of a typical run loop:
  54   //
  55   //   for (;;) {
  56   //     bool did_work = DoInternalWork();
  57   //     if (should_quit_)
  58   //       break;
  59   //
  60   //     did_work |= delegate_->DoWork();
  61   //     if (should_quit_)
  62   //       break;
  63   //
  64   //     TimeTicks next_time;
  65   //     did_work |= delegate_->DoDelayedWork(&next_time);
  66   //     if (should_quit_)
  67   //       break;
  68   //
  69   //     if (did_work)
  70   //       continue;
  71   //
  72   //     did_work = delegate_->DoIdleWork();
  73   //     if (should_quit_)
  74   //       break;
  75   //
  76   //     if (did_work)
  77   //       continue;
  78   //
  79   //     WaitForWork();
  80   //   }
  81   //
  82   // Here, DoInternalWork is some private method of the message pump that is
  83   // responsible for dispatching the next UI message or notifying the next IO
  84   // completion (for example).  WaitForWork is a private method that simply
  85   // blocks until there is more work of any type to do.
  86   //
  87   // Notice that the run loop cycles between calling DoInternalWork, DoWork,
  88   // and DoDelayedWork methods.  This helps ensure that none of these work
  89   // queues starve the others.  This is important for message pumps that are
  90   // used to drive animations, for example.
  91   //
  92   // Notice also that after each callout to foreign code, the run loop checks
  93   // to see if it should quit.  The Quit method is responsible for setting this
  94   // flag.  No further work is done once the quit flag is set.
  95   //
  96   // NOTE: Care must be taken to handle Run being called again from within any
  97   // of the callouts to foreign code.  Native message pumps may also need to
  98   // deal with other native message pumps being run outside their control
  99   // (e.g., the MessageBox API on Windows pumps UI messages!).  To be specific,
 100   // the callouts (DoWork and DoDelayedWork) MUST still be provided even in
 101   // nested sub-loops that are "seemingly" outside the control of this message
 102   // pump.  DoWork in particular must never be starved for time slices unless
 103   // it returns false (meaning it has run out of things to do).
 104   //
 105   virtual void Run(Delegate* delegate) = 0;
 106
 107   // Quit immediately from the most recently entered run loop.  This method may
 108   // only be used on the thread that called Run.
 109   virtual void Quit() = 0;
 110
 111   // Schedule a DoWork callback to happen reasonably soon.  Does nothing if a
 112   // DoWork callback is already scheduled.  This method may be called from any
 113   // thread.  Once this call is made, DoWork should not be "starved" at least
 114   // until it returns a value of false.
 115   virtual void ScheduleWork() = 0;
 116
 117   // Schedule a DoDelayedWork callback to happen at the specified time,
 118   // cancelling any pending DoDelayedWork callback.  This method may only be
 119   // used on the thread that called Run.
 120   virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time) = 0;
 121
 122  protected:
 123   virtual ~MessagePump();
 124   friend class RefCountedThreadSafe<MessagePump>;
 125 };
 126
 127 }  // namespace base
 128
 129 #endif  // BASE_MESSAGE_PUMP_H_