base/run_loop.h

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