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