run_loop.h revision 4e180b6a0b4720a9b8e9e959a882386f690f08ff
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef BASE_RUN_LOOP_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define BASE_RUN_LOOP_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/base_export.h" 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/callback.h" 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/memory/weak_ptr.h" 11ca12bfac764ba476d6cd062bf1dde12cc64c3f40Ben Murdoch#include "base/message_loop/message_loop.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace base { 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(OS_ANDROID) 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class MessagePumpForUI; 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(OS_IOS) 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class MessagePumpUIApplication; 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Helper class to Run a nested MessageLoop. Please do not use nested 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// MessageLoops in production code! If you must, use this class instead of 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// calling MessageLoop::Run/Quit directly. RunLoop::Run can only be called once 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// per RunLoop lifetime. Create a RunLoop on the stack and call Run/Quit to run 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// a nested MessageLoop. 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BASE_EXPORT RunLoop { 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) RunLoop(); 3058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)#if !defined(OS_MACOSX) && !defined(OS_ANDROID) && \ 3158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) !defined(USE_GTK_MESSAGE_PUMP) 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit RunLoop(MessageLoop::Dispatcher* dispatcher); 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ~RunLoop(); 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3658537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)#if !defined(OS_MACOSX) && !defined(OS_ANDROID) && \ 3758537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) !defined(USE_GTK_MESSAGE_PUMP) 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void set_dispatcher(MessageLoop::Dispatcher* dispatcher) { 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) dispatcher_ = dispatcher; 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Run the current MessageLoop. This blocks until Quit is called. Before 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // calling Run, be sure to grab an AsWeakPtr or the QuitClosure in order to 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // stop the MessageLoop asynchronously. MessageLoop::Quit and QuitNow will 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // also trigger a return from Run, but those are deprecated. 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Run(); 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Run the current MessageLoop until it doesn't find any tasks or messages in 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the queue (it goes idle). WARNING: This may never return! Only use this 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // when repeating tasks such as animated web pages have been shut down. 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void RunUntilIdle(); 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool running() const { return running_; } 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Quit an earlier call to Run(). There can be other nested RunLoops servicing 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the same task queue (MessageLoop); Quitting one RunLoop has no bearing on 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the others. Quit can be called before, during or after Run. If called 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // before Run, Run will return immediately when called. Calling Quit after the 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // RunLoop has already finished running has no effect. 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // WARNING: You must NEVER assume that a call to Quit will terminate the 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // targetted message loop. If a nested message loop continues running, the 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // target may NEVER terminate. It is very easy to livelock (run forever) in 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // such a case. 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Quit(); 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Convenience method to get a closure that safely calls Quit (has no effect 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // if the RunLoop instance is gone). 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Example: 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // RunLoop run_loop; 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // PostTask(run_loop.QuitClosure()); 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // run_loop.Run(); 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) base::Closure QuitClosure(); 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 78c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) friend class MessageLoop; 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(OS_ANDROID) 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Android doesn't support the blocking MessageLoop::Run, so it calls 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // BeforeRun and AfterRun directly. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) friend class base::MessagePumpForUI; 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#if defined(OS_IOS) 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // iOS doesn't support the blocking MessageLoop::Run, so it calls 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // BeforeRun directly. 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) friend class base::MessagePumpUIApplication; 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Return false to abort the Run. 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool BeforeRun(); 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void AfterRun(); 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) MessageLoop* loop_; 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Parent RunLoop or NULL if this is the top-most RunLoop. 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) RunLoop* previous_run_loop_; 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 10058537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles)#if !defined(OS_MACOSX) && !defined(OS_ANDROID) && \ 10158537e28ecd584eab876aee8be7156509866d23aTorne (Richard Coles) !defined(USE_GTK_MESSAGE_PUMP) 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) MessageLoop::Dispatcher* dispatcher_; 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Used to count how many nested Run() invocations are on the stack. 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int run_depth_; 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool run_called_; 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool quit_called_; 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool running_; 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Used to record that QuitWhenIdle() was called on the MessageLoop, meaning 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // that we should quit Run once it becomes idle. 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool quit_when_idle_received_; 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1164e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles) // WeakPtrFactory for QuitClosure safety. 1174e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles) base::WeakPtrFactory<RunLoop> weak_factory_; 1184e180b6a0b4720a9b8e9e959a882386f690f08ffTorne (Richard Coles) 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_COPY_AND_ASSIGN(RunLoop); 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace base 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // BASE_RUN_LOOP_H_ 125