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