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