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 13 namespace base { 14 15 class TimeTicks; 16 17 class 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
