cc/trees/blocking_task_runner.h

   1 // Copyright 2013 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 CC_TREES_BLOCKING_TASK_RUNNER_H_
   6 #define CC_TREES_BLOCKING_TASK_RUNNER_H_
   7
   8 #include <vector>
   9
  10 #include "base/location.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/single_thread_task_runner.h"
  13 #include "base/synchronization/lock.h"
  14 #include "cc/base/cc_export.h"
  15
  16 namespace cc {
  17
  18 // This class wraps a SingleThreadTaskRunner but allows posted tasks to be
  19 // run without a round trip through the message loop. This shortcutting
  20 // removes guarantees about ordering. Tasks posted while the
  21 // BlockingTaskRunner is in a capturing state will run in order, and tasks
  22 // posted while the BlockingTaskRunner is /not/ in a capturing state will
  23 // run in order, but the two sets of tasks will *not* run in order relative
  24 // to when they were posted.
  25 //
  26 // To use this class, post tasks to the task runner returned by
  27 // BlockingTaskRunner::current() on the thread you want the tasks to run.
  28 // Hold a reference to the BlockingTaskRunner as long as you intend to
  29 // post tasks to it.
  30 //
  31 // Then, on the thread from which the BlockingTaskRunner was created, you
  32 // may instantiate a BlockingTaskRunner::CapturePostTasks. While this object
  33 // exists, the task runner will collect any PostTasks called on it, posting
  34 // tasks to that thread from anywhere. This CapturePostTasks object provides
  35 // a window in time where tasks can shortcut past the MessageLoop. As soon
  36 // as the CapturePostTasks object is destroyed (goes out of scope), all
  37 // tasks that had been posted to the thread during the window will be exectuted
  38 // immediately.
  39 //
  40 // Beware of re-entrancy, make sure the CapturePostTasks object is destroyed at
  41 // a time when it makes sense for the embedder to call arbitrary things.
  42 class CC_EXPORT BlockingTaskRunner
  43     : public base::RefCountedThreadSafe<BlockingTaskRunner> {
  44  public:
  45   // Returns the BlockingTaskRunner for the current thread, creating one if
  46   // necessary.
  47   static scoped_refptr<BlockingTaskRunner> current();
  48
  49   // While an object of this type is held alive on a thread, any tasks
  50   // posted to the thread will be captured and run as soon as the object
  51   // is destroyed, shortcutting past the MessageLoop.
  52   class CC_EXPORT CapturePostTasks {
  53    public:
  54     CapturePostTasks();
  55     ~CapturePostTasks();
  56
  57    private:
  58     scoped_refptr<BlockingTaskRunner> blocking_runner_;
  59
  60     DISALLOW_COPY_AND_ASSIGN(CapturePostTasks);
  61   };
  62
  63   // True if tasks posted to the BlockingTaskRunner will run on the current
  64   // thread.
  65   bool BelongsToCurrentThread() {
  66     return task_runner_->BelongsToCurrentThread();
  67   }
  68
  69   // Posts a task using the contained SingleThreadTaskRunner unless |capture_|
  70   // is true. When |capture_| is true, tasks posted will be caught and stored
  71   // until the capturing stops. At that time the tasks will be run directly
  72   // instead of being posted to the SingleThreadTaskRunner.
  73   bool PostTask(const tracked_objects::Location& from_here,
  74                 const base::Closure& task);
  75
  76  private:
  77   friend class base::RefCountedThreadSafe<BlockingTaskRunner>;
  78
  79   explicit BlockingTaskRunner(
  80       scoped_refptr<base::SingleThreadTaskRunner> task_runner);
  81   virtual ~BlockingTaskRunner();
  82
  83   void SetCapture(bool capture);
  84
  85   scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
  86
  87   base::Lock lock_;
  88   int capture_;
  89   std::vector<base::Closure> captured_tasks_;
  90 };
  91
  92 }  // namespace cc
  93
  94 #endif  // CC_TREES_BLOCKING_TASK_RUNNER_H_