Run ScopedTaskScheduler tasks synchronously.

base/test/scoped_task_scheduler.h

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_TEST_SCOPED_TASK_SCHEDULER_H_
 #define BASE_TEST_SCOPED_TASK_SCHEDULER_H_
 
 #include "base/macros.h"
+#include "base/threading/thread_checker.h"
 
 namespace base {
 
+class MessageLoop;
 class TaskScheduler;
 
 namespace test {
 
-// Initializes a TaskScheduler and allows usage of the
-// base/task_scheduler/post_task.h API within its scope.
+// Allows usage of the base/task_scheduler/post_task.h API within its scope.
+//
+// To run pending tasks synchronously, call RunLoop::Run/RunUntilIdle() on the
+// thread where the ScopedTaskScheduler lives. The destructor runs remaining
+// BLOCK_SHUTDOWN tasks synchronously.
+//
+// Example usage:
+//
+// In the following snippet, RunUntilIdle() returns after "A" is run.
+// base::test::ScopedTaskScheduler scoped_task_scheduler;
+// base::PostTask(FROM_HERE, base::Bind(&A));
+// base::RunLoop::RunUntilIdle(); // Returns after running A.
+//
+// In this snippet, run_loop.Run() returns after running "B" and
+// "RunLoop::Quit".
+// base::RunLoop run_loop;
+// base::PostTask(FROM_HERE, base::Bind(&B));
+// base::PostTask(FROM_HERE, base::Bind(&RunLoop::Quit, &run_loop));
+// base::PostTask(FROM_HERE, base::Bind(&C));
+// base::PostTaskWithTraits(
+//     base::TaskTraits().WithShutdownBehavior(
+//         base::TaskShutdownBehavior::BLOCK_SHUTDOWN),
+//     base::Bind(&D));
+// run_loop.Run();  // Returns after running B and RunLoop::Quit.
+//
+// When |scoped_task_scheduler| is destroyed, it runs "D" since it's

[robliao, 2016/12/13 03:27:42]

It's not immediately clear that the entire code sample above is to be taken
together. To establish flow...
s/In this snippet/Continuing here,/

s/When |scoped_task_scheduler| is destroyed/At this point,
|scoped_task_scheduler| will be destroyed. After that, /

[fdoray, 2016/12/13 19:14:14]

Done.

[fdoray, 2016/12/13 20:38:31]

The 2 first blocks of code don't have to be taken together. The last paragraph
("At this point, ...") has to be taken together with the last block of code.

+// BLOCK_SHUTDOWN. "C" is skipped.
 class ScopedTaskScheduler {
  public:
-  // Initializes a TaskScheduler with default arguments.
+  // Registers a TaskScheduler that instantiates a MessageLoop on the current
+  // thread and runs its tasks on it.
   ScopedTaskScheduler();
 
-  // Waits until all TaskScheduler tasks blocking shutdown complete their
-  // execution (see TaskShutdownBehavior). Then, joins all TaskScheduler threads
-  // and deletes the TaskScheduler.
-  //
-  // Note that joining TaskScheduler threads may involve waiting for
-  // CONTINUE_ON_SHUTDOWN tasks to complete their execution. Normally, in
-  // production, the process exits without joining TaskScheduler threads.
+  // Registers a TaskScheduler that runs its tasks on |external_message_loop|.
+  // |external_message_loop| must be bound to the current thread.
+  ScopedTaskScheduler(MessageLoop* external_message_loop);
+
+  // Runs all pending BLOCK_SHUTDOWN tasks and unregisters the TaskScheduler.
   ~ScopedTaskScheduler();
 
  private:
   const TaskScheduler* task_scheduler_ = nullptr;
+  ThreadChecker thread_checker_;
 
   DISALLOW_COPY_AND_ASSIGN(ScopedTaskScheduler);
 };
 
 }  // namespace test
 }  // namespace base
 
 #endif  // BASE_TEST_SCOPED_TASK_SCHEDULER_H_