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_RUN_LOOP_H_ 6 #define BASE_RUN_LOOP_H_ 7 8 #include "base/base_export.h" 9 #include "base/callback.h" 10 #include "base/memory/weak_ptr.h" 11 #include "base/message_loop/message_loop.h" 12 13 namespace base { 14 #if defined(OS_ANDROID) 15 class MessagePumpForUI; 16 #endif 17 18 #if defined(OS_WIN) 19 class MessagePumpDispatcher; 20 #endif 21 22 #if defined(OS_IOS) 23 class MessagePumpUIApplication; 24 #endif 25 26 // Helper class to Run a nested MessageLoop. Please do not use nested 27 // MessageLoops in production code! If you must, use this class instead of 28 // calling MessageLoop::Run/Quit directly. RunLoop::Run can only be called once 29 // per RunLoop lifetime. Create a RunLoop on the stack and call Run/Quit to run 30 // a nested MessageLoop. 31 class BASE_EXPORT RunLoop { 32 public: 33 RunLoop(); 34 #if defined(OS_WIN) 35 explicit RunLoop(MessagePumpDispatcher* dispatcher); 36 #endif 37 ~RunLoop(); 38 39 // Run the current MessageLoop. This blocks until Quit is called. Before 40 // calling Run, be sure to grab an AsWeakPtr or the QuitClosure in order to 41 // stop the MessageLoop asynchronously. MessageLoop::Quit and QuitNow will 42 // also trigger a return from Run, but those are deprecated. 43 void Run(); 44 45 // Run the current MessageLoop until it doesn't find any tasks or messages in 46 // the queue (it goes idle). WARNING: This may never return! Only use this 47 // when repeating tasks such as animated web pages have been shut down. 48 void RunUntilIdle(); 49 running()50 bool running() const { return running_; } 51 52 // Quit an earlier call to Run(). There can be other nested RunLoops servicing 53 // the same task queue (MessageLoop); Quitting one RunLoop has no bearing on 54 // the others. Quit can be called before, during or after Run. If called 55 // before Run, Run will return immediately when called. Calling Quit after the 56 // RunLoop has already finished running has no effect. 57 // 58 // WARNING: You must NEVER assume that a call to Quit will terminate the 59 // targetted message loop. If a nested message loop continues running, the 60 // target may NEVER terminate. It is very easy to livelock (run forever) in 61 // such a case. 62 void Quit(); 63 64 // Convenience method to get a closure that safely calls Quit (has no effect 65 // if the RunLoop instance is gone). 66 // 67 // Example: 68 // RunLoop run_loop; 69 // PostTask(run_loop.QuitClosure()); 70 // run_loop.Run(); 71 base::Closure QuitClosure(); 72 73 private: 74 friend class MessageLoop; 75 #if defined(OS_ANDROID) 76 // Android doesn't support the blocking MessageLoop::Run, so it calls 77 // BeforeRun and AfterRun directly. 78 friend class base::MessagePumpForUI; 79 #endif 80 81 #if defined(OS_IOS) 82 // iOS doesn't support the blocking MessageLoop::Run, so it calls 83 // BeforeRun directly. 84 friend class base::MessagePumpUIApplication; 85 #endif 86 87 // Return false to abort the Run. 88 bool BeforeRun(); 89 void AfterRun(); 90 91 MessageLoop* loop_; 92 93 // Parent RunLoop or NULL if this is the top-most RunLoop. 94 RunLoop* previous_run_loop_; 95 96 #if defined(OS_WIN) 97 MessagePumpDispatcher* dispatcher_; 98 #endif 99 100 // Used to count how many nested Run() invocations are on the stack. 101 int run_depth_; 102 103 bool run_called_; 104 bool quit_called_; 105 bool running_; 106 107 // Used to record that QuitWhenIdle() was called on the MessageLoop, meaning 108 // that we should quit Run once it becomes idle. 109 bool quit_when_idle_received_; 110 111 // WeakPtrFactory for QuitClosure safety. 112 base::WeakPtrFactory<RunLoop> weak_factory_; 113 114 DISALLOW_COPY_AND_ASSIGN(RunLoop); 115 }; 116 117 } // namespace base 118 119 #endif // BASE_RUN_LOOP_H_ 120