base/test/task_runner_test_template.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 // This file defines tests that implementations of TaskRunner should
   6 // pass in order to be conformant, as well as test cases for optional behavior.
   7 // Here's how you use it to test your implementation.
   8 //
   9 // Say your class is called MyTaskRunner.  Then you need to define a
  10 // class called MyTaskRunnerTestDelegate in my_task_runner_unittest.cc
  11 // like this:
  12 //
  13 //   class MyTaskRunnerTestDelegate {
  14 //    public:
  15 //     // Tasks posted to the task runner after this and before
  16 //     // StopTaskRunner() is called is called should run successfully.
  17 //     void StartTaskRunner() {
  18 //       ...
  19 //     }
  20 //
  21 //     // Should return the task runner implementation.  Only called
  22 //     // after StartTaskRunner and before StopTaskRunner.
  23 //     scoped_refptr<MyTaskRunner> GetTaskRunner() {
  24 //       ...
  25 //     }
  26 //
  27 //     // Stop the task runner and make sure all tasks posted before
  28 //     // this is called are run. Caveat: delayed tasks are not run,
  29        // they're simply deleted.
  30 //     void StopTaskRunner() {
  31 //       ...
  32 //     }
  33 //   };
  34 //
  35 // The TaskRunnerTest test harness will have a member variable of
  36 // this delegate type and will call its functions in the various
  37 // tests.
  38 //
  39 // Then you simply #include this file as well as gtest.h and add the
  40 // following statement to my_task_runner_unittest.cc:
  41 //
  42 //   INSTANTIATE_TYPED_TEST_CASE_P(
  43 //       MyTaskRunner, TaskRunnerTest, MyTaskRunnerTestDelegate);
  44 //
  45 // Easy!
  46 //
  47 // The optional test harnesses TaskRunnerAffinityTest can be
  48 // instanciated in the same way, using the same delegate:
  49 //
  50 //   INSTANTIATE_TYPED_TEST_CASE_P(
  51 //       MyTaskRunner, TaskRunnerAffinityTest, MyTaskRunnerTestDelegate);
  52
  53
  54 #ifndef BASE_TEST_TASK_RUNNER_TEST_TEMPLATE_H_
  55 #define BASE_TEST_TASK_RUNNER_TEST_TEMPLATE_H_
  56
  57 #include <cstddef>
  58 #include <map>
  59
  60 #include "base/basictypes.h"
  61 #include "base/bind.h"
  62 #include "base/callback.h"
  63 #include "base/location.h"
  64 #include "base/memory/ref_counted.h"
  65 #include "base/single_thread_task_runner.h"
  66 #include "base/synchronization/condition_variable.h"
  67 #include "base/synchronization/lock.h"
  68 #include "base/task_runner.h"
  69 #include "base/threading/thread.h"
  70 #include "base/tracked_objects.h"
  71 #include "testing/gtest/include/gtest/gtest.h"
  72
  73 namespace base {
  74
  75 namespace internal {
  76
  77 // Utility class that keeps track of how many times particular tasks
  78 // are run.
  79 class TaskTracker : public RefCountedThreadSafe<TaskTracker> {
  80  public:
  81   TaskTracker();
  82
  83   // Returns a closure that runs the given task and increments the run
  84   // count of |i| by one.  |task| may be null.  It is guaranteed that
  85   // only one task wrapped by a given tracker will be run at a time.
  86   Closure WrapTask(const Closure& task, int i);
  87
  88   std::map<int, int> GetTaskRunCounts() const;
  89
  90   // Returns after the tracker observes a total of |count| task completions.
  91   void WaitForCompletedTasks(int count);
  92
  93  private:
  94   friend class RefCountedThreadSafe<TaskTracker>;
  95
  96   ~TaskTracker();
  97
  98   void RunTask(const Closure& task, int i);
  99
 100   mutable Lock lock_;
 101   std::map<int, int> task_run_counts_;
 102   int task_runs_;
 103   ConditionVariable task_runs_cv_;
 104
 105   DISALLOW_COPY_AND_ASSIGN(TaskTracker);
 106 };
 107
 108 }  // namespace internal
 109
 110 template <typename TaskRunnerTestDelegate>
 111 class TaskRunnerTest : public testing::Test {
 112  protected:
 113   TaskRunnerTest() : task_tracker_(new internal::TaskTracker()) {}
 114
 115   const scoped_refptr<internal::TaskTracker> task_tracker_;
 116   TaskRunnerTestDelegate delegate_;
 117 };
 118
 119 TYPED_TEST_CASE_P(TaskRunnerTest);
 120
 121 // We can't really test much, since TaskRunner provides very few
 122 // guarantees.
 123
 124 // Post a bunch of tasks to the task runner.  They should all
 125 // complete.
 126 TYPED_TEST_P(TaskRunnerTest, Basic) {
 127   std::map<int, int> expected_task_run_counts;
 128
 129   this->delegate_.StartTaskRunner();
 130   scoped_refptr<TaskRunner> task_runner = this->delegate_.GetTaskRunner();
 131   // Post each ith task i+1 times.
 132   for (int i = 0; i < 20; ++i) {
 133     const Closure& ith_task = this->task_tracker_->WrapTask(Closure(), i);
 134     for (int j = 0; j < i + 1; ++j) {
 135       task_runner->PostTask(FROM_HERE, ith_task);
 136       ++expected_task_run_counts[i];
 137     }
 138   }
 139   this->delegate_.StopTaskRunner();
 140
 141   EXPECT_EQ(expected_task_run_counts,
 142             this->task_tracker_->GetTaskRunCounts());
 143 }
 144
 145 // Post a bunch of delayed tasks to the task runner.  They should all
 146 // complete.
 147 TYPED_TEST_P(TaskRunnerTest, Delayed) {
 148   std::map<int, int> expected_task_run_counts;
 149   int expected_total_tasks = 0;
 150
 151   this->delegate_.StartTaskRunner();
 152   scoped_refptr<TaskRunner> task_runner = this->delegate_.GetTaskRunner();
 153   // Post each ith task i+1 times with delays from 0-i.
 154   for (int i = 0; i < 20; ++i) {
 155     const Closure& ith_task = this->task_tracker_->WrapTask(Closure(), i);
 156     for (int j = 0; j < i + 1; ++j) {
 157       task_runner->PostDelayedTask(
 158           FROM_HERE, ith_task, base::TimeDelta::FromMilliseconds(j));
 159       ++expected_task_run_counts[i];
 160       ++expected_total_tasks;
 161     }
 162   }
 163   this->task_tracker_->WaitForCompletedTasks(expected_total_tasks);
 164   this->delegate_.StopTaskRunner();
 165
 166   EXPECT_EQ(expected_task_run_counts,
 167             this->task_tracker_->GetTaskRunCounts());
 168 }
 169
 170 // The TaskRunnerTest test case verifies behaviour that is expected from a
 171 // task runner in order to be conformant.
 172 REGISTER_TYPED_TEST_CASE_P(TaskRunnerTest, Basic, Delayed);
 173
 174 namespace internal {
 175
 176 // Calls RunsTasksOnCurrentThread() on |task_runner| and expects it to
 177 // equal |expected_value|.
 178 void ExpectRunsTasksOnCurrentThread(
 179     bool expected_value,
 180     const scoped_refptr<TaskRunner>& task_runner);
 181
 182 }  // namespace internal
 183
 184 template <typename TaskRunnerTestDelegate>
 185 class TaskRunnerAffinityTest : public TaskRunnerTest<TaskRunnerTestDelegate> {};
 186
 187 TYPED_TEST_CASE_P(TaskRunnerAffinityTest);
 188
 189 // Post a bunch of tasks to the task runner as well as to a separate
 190 // thread, each checking the value of RunsTasksOnCurrentThread(),
 191 // which should return true for the tasks posted on the task runner
 192 // and false for the tasks posted on the separate thread.
 193 TYPED_TEST_P(TaskRunnerAffinityTest, RunsTasksOnCurrentThread) {
 194   std::map<int, int> expected_task_run_counts;
 195
 196   Thread thread("Non-task-runner thread");
 197   ASSERT_TRUE(thread.Start());
 198   this->delegate_.StartTaskRunner();
 199
 200   scoped_refptr<TaskRunner> task_runner = this->delegate_.GetTaskRunner();
 201   // Post each ith task i+1 times on the task runner and i+1 times on
 202   // the non-task-runner thread.
 203   for (int i = 0; i < 20; ++i) {
 204     const Closure& ith_task_runner_task =
 205         this->task_tracker_->WrapTask(
 206             Bind(&internal::ExpectRunsTasksOnCurrentThread,
 207                  true, task_runner),
 208             i);
 209     const Closure& ith_non_task_runner_task =
 210         this->task_tracker_->WrapTask(
 211             Bind(&internal::ExpectRunsTasksOnCurrentThread,
 212                  false, task_runner),
 213             i);
 214     for (int j = 0; j < i + 1; ++j) {
 215       task_runner->PostTask(FROM_HERE, ith_task_runner_task);
 216       thread.task_runner()->PostTask(FROM_HERE, ith_non_task_runner_task);
 217       expected_task_run_counts[i] += 2;
 218     }
 219   }
 220
 221   this->delegate_.StopTaskRunner();
 222   thread.Stop();
 223
 224   EXPECT_EQ(expected_task_run_counts,
 225             this->task_tracker_->GetTaskRunCounts());
 226 }
 227
 228 // TaskRunnerAffinityTest tests that the TaskRunner implementation
 229 // can determine if tasks will never be run on a specific thread.
 230 REGISTER_TYPED_TEST_CASE_P(TaskRunnerAffinityTest, RunsTasksOnCurrentThread);
 231
 232 }  // namespace base
 233
 234 #endif  // BASE_TEST_TASK_RUNNER_TEST_TEMPLATE_H_