// Copyright 2019 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_TASK_THREAD_POOL_H_ #define BASE_TASK_THREAD_POOL_H_ #include #include #include "base/base_export.h" #include "base/bind.h" #include "base/callback.h" #include "base/callback_helpers.h" #include "base/location.h" #include "base/memory/scoped_refptr.h" #include "base/task/post_task_and_reply_with_result_internal.h" #include "base/task/sequenced_task_runner.h" #include "base/task/single_thread_task_runner.h" #include "base/task/single_thread_task_runner_thread_mode.h" #include "base/task/task_runner.h" #include "base/task/task_traits.h" #include "base/task/updateable_sequenced_task_runner.h" #include "base/time/time.h" #include "build/build_config.h" namespace base { // This is the interface to post tasks to base's thread pool. // // To post a simple one-off task with default traits: // base::ThreadPool::PostTask(FROM_HERE, base::BindOnce(...)); // // To post a high priority one-off task to respond to a user interaction: // base::ThreadPool::PostTask( // FROM_HERE, // {base::TaskPriority::USER_BLOCKING}, // base::BindOnce(...)); // // To post tasks that must run in sequence with default traits: // scoped_refptr task_runner = // base::ThreadPool::CreateSequencedTaskRunner(); // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); // // To post tasks that may block, must run in sequence and can be skipped on // shutdown: // scoped_refptr task_runner = // base::ThreadPool::CreateSequencedTaskRunner( // {MayBlock(), TaskShutdownBehavior::SKIP_ON_SHUTDOWN}); // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); // // The default traits apply to tasks that: // (1) don't block (ref. MayBlock() and WithBaseSyncPrimitives()), // (2) prefer inheriting the current priority to specifying their own, and // (3) can either block shutdown or be skipped on shutdown // (implementation is free to choose a fitting default). // Explicit traits must be specified for tasks for which these loose // requirements are not sufficient. // // Prerequisite: A ThreadPoolInstance must have been registered for the current // process via ThreadPoolInstance::Set() before the API below can be invoked. // This is typically done during the initialization phase in each process. If // your code is not running in that phase, you most likely don't have to worry // about this. You will encounter DCHECKs or nullptr dereferences if this is // violated. For tests, use base::test::TaskEnvironment. class BASE_EXPORT ThreadPool { public: // base::ThreadPool is a static API. See base::ThreadPoolInstance for the // actual instance. ThreadPool() = delete; // Equivalent to calling PostTask with default TaskTraits. static bool PostTask(const Location& from_here, OnceClosure task); inline static bool PostTask(OnceClosure task, const Location& from_here = Location::Current()) { return PostTask(from_here, std::move(task)); } // Equivalent to calling PostDelayedTask with default TaskTraits. // // Use PostDelayedTask to specify a BEST_EFFORT priority if the task doesn't // have to run as soon as |delay| expires. static bool PostDelayedTask(const Location& from_here, OnceClosure task, TimeDelta delay); // Equivalent to calling PostTaskAndReply with default TaskTraits. static bool PostTaskAndReply(const Location& from_here, OnceClosure task, OnceClosure reply); // Equivalent to calling PostTaskAndReplyWithResult with default TaskTraits. // // Though RepeatingCallback is convertible to OnceCallback, we need a // CallbackType template since we can not use template deduction and object // conversion at once on the overload resolution. // TODO(crbug.com/714018): Update all callers of the RepeatingCallback version // to use OnceCallback and remove the CallbackType template. template