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