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.
5 #ifndef BASE_MESSAGE_PUMP_H_
6 #define BASE_MESSAGE_PUMP_H_
9 #include "base/base_export.h"
10 #include "base/memory/ref_counted.h"
16 class BASE_EXPORT MessagePump
: public RefCountedThreadSafe
<MessagePump
> {
18 // Please see the comments above the Run method for an illustration of how
19 // these delegate methods are used.
20 class BASE_EXPORT Delegate
{
22 virtual ~Delegate() {}
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;
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;
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;
46 virtual ~MessagePump();
48 // The Run method is called to enter the message pump's run loop.
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.
55 // The anatomy of a typical run loop:
58 // bool did_work = DoInternalWork();
62 // did_work |= delegate_->DoWork();
66 // TimeTicks next_time;
67 // did_work |= delegate_->DoDelayedWork(&next_time);
74 // did_work = delegate_->DoIdleWork();
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.
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.
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.
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).
107 virtual void Run(Delegate
* delegate
) = 0;
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;
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;
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;
127 #endif // BASE_MESSAGE_PUMP_H_