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