Home | History | Annotate | Download | only in message_loop 
      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_LOOP_MESSAGE_PUMP_H_
      6 #define BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_
      7 
      8 #include "base/base_export.h"
      9 #include "base/threading/non_thread_safe.h"
     10 
     11 namespace base {
     12 
     13 class TimeTicks;
     14 
     15 class BASE_EXPORT MessagePump : public NonThreadSafe {
     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   virtual ~MessagePump();
     46 
     47   // The Run method is called to enter the message pump's run loop.
     48   //
     49   // Within the method, the message pump is responsible for processing native
     50   // messages as well as for giving cycles to the delegate periodically.  The
     51   // message pump should take care to mix delegate callbacks with native
     52   // message processing so neither type of event starves the other of cycles.
     53   //
     54   // The anatomy of a typical run loop:
     55   //
     56   //   for (;;) {
     57   //     bool did_work = DoInternalWork();
     58   //     if (should_quit_)
     59   //       break;
     60   //
     61   //     did_work |= delegate_->DoWork();
     62   //     if (should_quit_)
     63   //       break;
     64   //
     65   //     TimeTicks next_time;
     66   //     did_work |= delegate_->DoDelayedWork(&next_time);
     67   //     if (should_quit_)
     68   //       break;
     69   //
     70   //     if (did_work)
     71   //       continue;
     72   //
     73   //     did_work = delegate_->DoIdleWork();
     74   //     if (should_quit_)
     75   //       break;
     76   //
     77   //     if (did_work)
     78   //       continue;
     79   //
     80   //     WaitForWork();
     81   //   }
     82   //
     83   // Here, DoInternalWork is some private method of the message pump that is
     84   // responsible for dispatching the next UI message or notifying the next IO
     85   // completion (for example).  WaitForWork is a private method that simply
     86   // blocks until there is more work of any type to do.
     87   //
     88   // Notice that the run loop cycles between calling DoInternalWork, DoWork,
     89   // and DoDelayedWork methods.  This helps ensure that none of these work
     90   // queues starve the others.  This is important for message pumps that are
     91   // used to drive animations, for example.
     92   //
     93   // Notice also that after each callout to foreign code, the run loop checks
     94   // to see if it should quit.  The Quit method is responsible for setting this
     95   // flag.  No further work is done once the quit flag is set.
     96   //
     97   // NOTE: Care must be taken to handle Run being called again from within any
     98   // of the callouts to foreign code.  Native message pumps may also need to
     99   // deal with other native message pumps being run outside their control
    100   // (e.g., the MessageBox API on Windows pumps UI messages!).  To be specific,
    101   // the callouts (DoWork and DoDelayedWork) MUST still be provided even in
    102   // nested sub-loops that are "seemingly" outside the control of this message
    103   // pump.  DoWork in particular must never be starved for time slices unless
    104   // it returns false (meaning it has run out of things to do).
    105   //
    106   virtual void Run(Delegate* delegate) = 0;
    107 
    108   // Quit immediately from the most recently entered run loop.  This method may
    109   // only be used on the thread that called Run.
    110   virtual void Quit() = 0;
    111 
    112   // Schedule a DoWork callback to happen reasonably soon.  Does nothing if a
    113   // DoWork callback is already scheduled.  This method may be called from any
    114   // thread.  Once this call is made, DoWork should not be "starved" at least
    115   // until it returns a value of false.
    116   virtual void ScheduleWork() = 0;
    117 
    118   // Schedule a DoDelayedWork callback to happen at the specified time,
    119   // cancelling any pending DoDelayedWork callback.  This method may only be
    120   // used on the thread that called Run.
    121   virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time) = 0;
    122 };
    123 
    124 }  // namespace base
    125 
    126 #endif  // BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_
    127