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