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