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. 4 5 #ifndef BASE_MESSAGE_PUMP_H_ 6 #define BASE_MESSAGE_PUMP_H_ 7 #pragma once 8 9 #include "base/base_api.h" 10 #include "base/memory/ref_counted.h" 11 12 namespace base { 13 14 class TimeTicks; 15 16 class BASE_API MessagePump : public RefCountedThreadSafe<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_API Delegate { 21 public: 22 virtual ~Delegate() {} 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. 42 virtual bool DoIdleWork() = 0; 43 }; 44 45 MessagePump(); 46 virtual ~MessagePump(); 47 48 // The Run method is called to enter the message pump's run loop. 49 // 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. 54 // 55 // The anatomy of a typical run loop: 56 // 57 // for (;;) { 58 // bool did_work = DoInternalWork(); 59 // if (should_quit_) 60 // break; 61 // 62 // did_work |= delegate_->DoWork(); 63 // if (should_quit_) 64 // break; 65 // 66 // TimeTicks next_time; 67 // did_work |= delegate_->DoDelayedWork(&next_time); 68 // if (should_quit_) 69 // break; 70 // 71 // if (did_work) 72 // continue; 73 // 74 // did_work = delegate_->DoIdleWork(); 75 // if (should_quit_) 76 // break; 77 // 78 // if (did_work) 79 // continue; 80 // 81 // WaitForWork(); 82 // } 83 // 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. 88 // 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. 93 // 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. 97 // 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). 106 // 107 virtual void Run(Delegate* delegate) = 0; 108 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; 112 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; 118 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; 123 }; 124 125 } // namespace base 126 127 #endif // BASE_MESSAGE_PUMP_H_ 128
