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 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 class Delegate { 19 public: ~Delegate()20 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 ~MessagePump()42 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 // Schedule a DoDelayedWork callback to happen at the specified time, 115 // cancelling any pending DoDelayedWork callback. This method may only be 116 // used on the thread that called Run. 117 virtual void ScheduleDelayedWork(const Time& delayed_work_time) = 0; 118 }; 119 120 } // namespace base 121 122 #endif // BASE_MESSAGE_PUMP_H_ 123