Update TaskScheduler docs to make it more obvious how a TaskScheduler should be put in place.
In particular:
- Move mention of TaskScheduler::SetInstance() into a lower prerequisite section
(too reduce instances of people going crazy with if (!GetInstance()) SetInstance()...)
- Add DCHECKs that reference the Prerequisite section.
- Add mentions of base::test::ScopedTaskScheduler in key places
(to increase discovery of it for people new to TaskScheduler)
- Make it clear users shouldn't generally use GetInstance() to know if they need
to SetInstance() before PostTask() -- give people a generic bool, they'll use
it (e.g. TaskRunner::PostTask(), sigh..!) ;)
BUG=553459
Review-Url: https://codereview.chromium.org/2709163006
Cr-Commit-Position: refs/heads/master@{#452872}
diff --git a/base/task_scheduler/task_scheduler.h b/base/task_scheduler/task_scheduler.h
index 296e40b..da2cb79 100644
--- a/base/task_scheduler/task_scheduler.h
+++ b/base/task_scheduler/task_scheduler.h
@@ -108,25 +108,36 @@
// new TaskScheduler.
// Creates and sets a task scheduler with one worker pool that can have up to
- // |max_threads| threads. CHECKs on failure.
+ // |max_threads| threads. CHECKs on failure. For tests, prefer
+ // base::test::ScopedTaskScheduler (ensures isolation).
static void CreateAndSetSimpleTaskScheduler(int max_threads);
// Creates and sets a task scheduler with custom worker pools. CHECKs on
// failure. |worker_pool_params_vector| describes the worker pools to create.
// |worker_pool_index_for_traits_callback| returns the index in |worker_pools|
- // of the worker pool in which a task with given traits should run.
+ // of the worker pool in which a task with given traits should run. For tests,
+ // prefer base::test::ScopedTaskScheduler (ensures isolation).
static void CreateAndSetDefaultTaskScheduler(
const std::vector<SchedulerWorkerPoolParams>& worker_pool_params_vector,
const WorkerPoolIndexForTraitsCallback&
worker_pool_index_for_traits_callback);
// Registers |task_scheduler| to handle tasks posted through the post_task.h
- // API for this process.
+ // API for this process. For tests, prefer base::test::ScopedTaskScheduler
+ // (ensures isolation).
static void SetInstance(std::unique_ptr<TaskScheduler> task_scheduler);
- // Retrieve the TaskScheduler set via CreateAndSetDefaultTaskScheduler() or
- // SetInstance(). This should be used very rarely; most users of TaskScheduler
- // should use the post_task.h API.
+ // Retrieve the TaskScheduler set via SetInstance() or
+ // CreateAndSet(Simple|Default)TaskScheduler(). This should be used very
+ // rarely; most users of TaskScheduler should use the post_task.h API. In
+ // particular, refrain from doing
+ // if (!TaskScheduler::GetInstance()) {
+ // TaskScheduler::SetInstance(...);
+ // base::PostTask(...);
+ // }
+ // instead make sure to SetInstance() early in one determinstic place in the
+ // process' initialization phase.
+ // In doubt, consult with //base/task_scheduler/OWNERS.
static TaskScheduler* GetInstance();
private:
