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