1*6777b538SAndroid Build Coastguard Worker // Copyright 2019 The Chromium Authors 2*6777b538SAndroid Build Coastguard Worker // Use of this source code is governed by a BSD-style license that can be 3*6777b538SAndroid Build Coastguard Worker // found in the LICENSE file. 4*6777b538SAndroid Build Coastguard Worker 5*6777b538SAndroid Build Coastguard Worker #ifndef BASE_TASK_THREAD_POOL_H_ 6*6777b538SAndroid Build Coastguard Worker #define BASE_TASK_THREAD_POOL_H_ 7*6777b538SAndroid Build Coastguard Worker 8*6777b538SAndroid Build Coastguard Worker #include <memory> 9*6777b538SAndroid Build Coastguard Worker #include <utility> 10*6777b538SAndroid Build Coastguard Worker 11*6777b538SAndroid Build Coastguard Worker #include "base/base_export.h" 12*6777b538SAndroid Build Coastguard Worker #include "base/functional/bind.h" 13*6777b538SAndroid Build Coastguard Worker #include "base/functional/callback.h" 14*6777b538SAndroid Build Coastguard Worker #include "base/functional/callback_helpers.h" 15*6777b538SAndroid Build Coastguard Worker #include "base/location.h" 16*6777b538SAndroid Build Coastguard Worker #include "base/memory/scoped_refptr.h" 17*6777b538SAndroid Build Coastguard Worker #include "base/task/post_task_and_reply_with_result_internal.h" 18*6777b538SAndroid Build Coastguard Worker #include "base/task/sequenced_task_runner.h" 19*6777b538SAndroid Build Coastguard Worker #include "base/task/single_thread_task_runner.h" 20*6777b538SAndroid Build Coastguard Worker #include "base/task/single_thread_task_runner_thread_mode.h" 21*6777b538SAndroid Build Coastguard Worker #include "base/task/task_runner.h" 22*6777b538SAndroid Build Coastguard Worker #include "base/task/task_traits.h" 23*6777b538SAndroid Build Coastguard Worker #include "base/task/updateable_sequenced_task_runner.h" 24*6777b538SAndroid Build Coastguard Worker #include "base/time/time.h" 25*6777b538SAndroid Build Coastguard Worker #include "build/build_config.h" 26*6777b538SAndroid Build Coastguard Worker 27*6777b538SAndroid Build Coastguard Worker namespace base { 28*6777b538SAndroid Build Coastguard Worker 29*6777b538SAndroid Build Coastguard Worker // This is the interface to post tasks to base's thread pool. 30*6777b538SAndroid Build Coastguard Worker // 31*6777b538SAndroid Build Coastguard Worker // To post a simple one-off task with default traits: 32*6777b538SAndroid Build Coastguard Worker // base::ThreadPool::PostTask(FROM_HERE, base::BindOnce(...)); 33*6777b538SAndroid Build Coastguard Worker // 34*6777b538SAndroid Build Coastguard Worker // To post a high priority one-off task to respond to a user interaction: 35*6777b538SAndroid Build Coastguard Worker // base::ThreadPool::PostTask( 36*6777b538SAndroid Build Coastguard Worker // FROM_HERE, 37*6777b538SAndroid Build Coastguard Worker // {base::TaskPriority::USER_BLOCKING}, 38*6777b538SAndroid Build Coastguard Worker // base::BindOnce(...)); 39*6777b538SAndroid Build Coastguard Worker // 40*6777b538SAndroid Build Coastguard Worker // To post tasks that must run in sequence with default traits: 41*6777b538SAndroid Build Coastguard Worker // scoped_refptr<SequencedTaskRunner> task_runner = 42*6777b538SAndroid Build Coastguard Worker // base::ThreadPool::CreateSequencedTaskRunner(); 43*6777b538SAndroid Build Coastguard Worker // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); 44*6777b538SAndroid Build Coastguard Worker // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); 45*6777b538SAndroid Build Coastguard Worker // 46*6777b538SAndroid Build Coastguard Worker // To post tasks that may block, must run in sequence and can be skipped on 47*6777b538SAndroid Build Coastguard Worker // shutdown: 48*6777b538SAndroid Build Coastguard Worker // scoped_refptr<SequencedTaskRunner> task_runner = 49*6777b538SAndroid Build Coastguard Worker // base::ThreadPool::CreateSequencedTaskRunner( 50*6777b538SAndroid Build Coastguard Worker // {MayBlock(), TaskShutdownBehavior::SKIP_ON_SHUTDOWN}); 51*6777b538SAndroid Build Coastguard Worker // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); 52*6777b538SAndroid Build Coastguard Worker // task_runner->PostTask(FROM_HERE, base::BindOnce(...)); 53*6777b538SAndroid Build Coastguard Worker // 54*6777b538SAndroid Build Coastguard Worker // The default traits apply to tasks that: 55*6777b538SAndroid Build Coastguard Worker // (1) don't block (ref. MayBlock() and WithBaseSyncPrimitives()), 56*6777b538SAndroid Build Coastguard Worker // (2) prefer inheriting the current priority to specifying their own, and 57*6777b538SAndroid Build Coastguard Worker // (3) can either block shutdown or be skipped on shutdown 58*6777b538SAndroid Build Coastguard Worker // (implementation is free to choose a fitting default). 59*6777b538SAndroid Build Coastguard Worker // Explicit traits must be specified for tasks for which these loose 60*6777b538SAndroid Build Coastguard Worker // requirements are not sufficient. 61*6777b538SAndroid Build Coastguard Worker // 62*6777b538SAndroid Build Coastguard Worker // Prerequisite: A ThreadPoolInstance must have been registered for the current 63*6777b538SAndroid Build Coastguard Worker // process via ThreadPoolInstance::Set() before the API below can be invoked. 64*6777b538SAndroid Build Coastguard Worker // This is typically done during the initialization phase in each process. If 65*6777b538SAndroid Build Coastguard Worker // your code is not running in that phase, you most likely don't have to worry 66*6777b538SAndroid Build Coastguard Worker // about this. You will encounter DCHECKs or nullptr dereferences if this is 67*6777b538SAndroid Build Coastguard Worker // violated. For tests, use base::test::TaskEnvironment. 68*6777b538SAndroid Build Coastguard Worker class BASE_EXPORT ThreadPool { 69*6777b538SAndroid Build Coastguard Worker public: 70*6777b538SAndroid Build Coastguard Worker // base::ThreadPool is a static API. See base::ThreadPoolInstance for the 71*6777b538SAndroid Build Coastguard Worker // actual instance. 72*6777b538SAndroid Build Coastguard Worker ThreadPool() = delete; 73*6777b538SAndroid Build Coastguard Worker 74*6777b538SAndroid Build Coastguard Worker // Equivalent to calling PostTask with default TaskTraits. 75*6777b538SAndroid Build Coastguard Worker static bool PostTask(const Location& from_here, OnceClosure task); 76*6777b538SAndroid Build Coastguard Worker inline static bool PostTask(OnceClosure task, 77*6777b538SAndroid Build Coastguard Worker const Location& from_here = Location::Current()) { 78*6777b538SAndroid Build Coastguard Worker return PostTask(from_here, std::move(task)); 79*6777b538SAndroid Build Coastguard Worker } 80*6777b538SAndroid Build Coastguard Worker 81*6777b538SAndroid Build Coastguard Worker // Equivalent to calling PostDelayedTask with default TaskTraits. 82*6777b538SAndroid Build Coastguard Worker // 83*6777b538SAndroid Build Coastguard Worker // Use PostDelayedTask to specify a BEST_EFFORT priority if the task doesn't 84*6777b538SAndroid Build Coastguard Worker // have to run as soon as |delay| expires. 85*6777b538SAndroid Build Coastguard Worker static bool PostDelayedTask(const Location& from_here, 86*6777b538SAndroid Build Coastguard Worker OnceClosure task, 87*6777b538SAndroid Build Coastguard Worker TimeDelta delay); 88*6777b538SAndroid Build Coastguard Worker 89*6777b538SAndroid Build Coastguard Worker // Equivalent to calling PostTaskAndReply with default TaskTraits. 90*6777b538SAndroid Build Coastguard Worker static bool PostTaskAndReply(const Location& from_here, 91*6777b538SAndroid Build Coastguard Worker OnceClosure task, 92*6777b538SAndroid Build Coastguard Worker OnceClosure reply); 93*6777b538SAndroid Build Coastguard Worker 94*6777b538SAndroid Build Coastguard Worker // Equivalent to calling PostTaskAndReplyWithResult with default TaskTraits. 95*6777b538SAndroid Build Coastguard Worker // 96*6777b538SAndroid Build Coastguard Worker // Though RepeatingCallback is convertible to OnceCallback, we need a 97*6777b538SAndroid Build Coastguard Worker // CallbackType template since we can not use template deduction and object 98*6777b538SAndroid Build Coastguard Worker // conversion at once on the overload resolution. 99*6777b538SAndroid Build Coastguard Worker // TODO(crbug.com/714018): Update all callers of the RepeatingCallback version 100*6777b538SAndroid Build Coastguard Worker // to use OnceCallback and remove the CallbackType template. 101*6777b538SAndroid Build Coastguard Worker template <template <typename> class CallbackType, 102*6777b538SAndroid Build Coastguard Worker typename TaskReturnType, 103*6777b538SAndroid Build Coastguard Worker typename ReplyArgType> 104*6777b538SAndroid Build Coastguard Worker requires(IsBaseCallback<CallbackType<void()>>) 105*6777b538SAndroid Build Coastguard Worker static bool PostTaskAndReplyWithResult( 106*6777b538SAndroid Build Coastguard Worker const Location& from_here, 107*6777b538SAndroid Build Coastguard Worker CallbackType<TaskReturnType()> task, 108*6777b538SAndroid Build Coastguard Worker CallbackType<void(ReplyArgType)> reply) { 109*6777b538SAndroid Build Coastguard Worker return ThreadPool::PostTaskAndReplyWithResult( 110*6777b538SAndroid Build Coastguard Worker from_here, {}, std::move(task), std::move(reply)); 111*6777b538SAndroid Build Coastguard Worker } 112*6777b538SAndroid Build Coastguard Worker 113*6777b538SAndroid Build Coastguard Worker // Posts |task| with specific |traits|. Returns false if the task definitely 114*6777b538SAndroid Build Coastguard Worker // won't run because of current shutdown state. 115*6777b538SAndroid Build Coastguard Worker static bool PostTask(const Location& from_here, 116*6777b538SAndroid Build Coastguard Worker const TaskTraits& traits, 117*6777b538SAndroid Build Coastguard Worker OnceClosure task); 118*6777b538SAndroid Build Coastguard Worker 119*6777b538SAndroid Build Coastguard Worker // Posts |task| with specific |traits|. |task| will not run before |delay| 120*6777b538SAndroid Build Coastguard Worker // expires. Returns false if the task definitely won't run because of current 121*6777b538SAndroid Build Coastguard Worker // shutdown state. 122*6777b538SAndroid Build Coastguard Worker // 123*6777b538SAndroid Build Coastguard Worker // Specify a BEST_EFFORT priority via |traits| if the task doesn't have to run 124*6777b538SAndroid Build Coastguard Worker // as soon as |delay| expires. 125*6777b538SAndroid Build Coastguard Worker static bool PostDelayedTask(const Location& from_here, 126*6777b538SAndroid Build Coastguard Worker const TaskTraits& traits, 127*6777b538SAndroid Build Coastguard Worker OnceClosure task, 128*6777b538SAndroid Build Coastguard Worker TimeDelta delay); 129*6777b538SAndroid Build Coastguard Worker 130*6777b538SAndroid Build Coastguard Worker // Posts |task| with specific |traits| and posts |reply| on the caller's 131*6777b538SAndroid Build Coastguard Worker // execution context (i.e. same sequence or thread and same TaskTraits if 132*6777b538SAndroid Build Coastguard Worker // applicable) when |task| completes. Returns false if the task definitely 133*6777b538SAndroid Build Coastguard Worker // won't run because of current shutdown state. Can only be called when 134*6777b538SAndroid Build Coastguard Worker // SequencedTaskRunner::HasCurrentDefault(). 135*6777b538SAndroid Build Coastguard Worker static bool PostTaskAndReply(const Location& from_here, 136*6777b538SAndroid Build Coastguard Worker const TaskTraits& traits, 137*6777b538SAndroid Build Coastguard Worker OnceClosure task, 138*6777b538SAndroid Build Coastguard Worker OnceClosure reply); 139*6777b538SAndroid Build Coastguard Worker 140*6777b538SAndroid Build Coastguard Worker // Posts |task| with specific |traits| and posts |reply| with the return value 141*6777b538SAndroid Build Coastguard Worker // of |task| as argument on the caller's execution context (i.e. same sequence 142*6777b538SAndroid Build Coastguard Worker // or thread and same TaskTraits if applicable) when |task| completes. Returns 143*6777b538SAndroid Build Coastguard Worker // false if the task definitely won't run because of current shutdown state. 144*6777b538SAndroid Build Coastguard Worker // Can only be called when SequencedTaskRunner::HasCurrentDefault(). 145*6777b538SAndroid Build Coastguard Worker // 146*6777b538SAndroid Build Coastguard Worker // Though RepeatingCallback is convertible to OnceCallback, we need a 147*6777b538SAndroid Build Coastguard Worker // CallbackType template since we can not use template deduction and object 148*6777b538SAndroid Build Coastguard Worker // conversion at once on the overload resolution. 149*6777b538SAndroid Build Coastguard Worker // TODO(crbug.com/714018): Update all callers of the RepeatingCallback version 150*6777b538SAndroid Build Coastguard Worker // to use OnceCallback and remove the CallbackType template. 151*6777b538SAndroid Build Coastguard Worker template <template <typename> class CallbackType, 152*6777b538SAndroid Build Coastguard Worker typename TaskReturnType, 153*6777b538SAndroid Build Coastguard Worker typename ReplyArgType> 154*6777b538SAndroid Build Coastguard Worker requires(IsBaseCallback<CallbackType<void()>>) 155*6777b538SAndroid Build Coastguard Worker static bool PostTaskAndReplyWithResult( 156*6777b538SAndroid Build Coastguard Worker const Location& from_here, 157*6777b538SAndroid Build Coastguard Worker const TaskTraits& traits, 158*6777b538SAndroid Build Coastguard Worker CallbackType<TaskReturnType()> task, 159*6777b538SAndroid Build Coastguard Worker CallbackType<void(ReplyArgType)> reply) { 160*6777b538SAndroid Build Coastguard Worker auto* result = new std::unique_ptr<TaskReturnType>(); 161*6777b538SAndroid Build Coastguard Worker return PostTaskAndReply( 162*6777b538SAndroid Build Coastguard Worker from_here, traits, 163*6777b538SAndroid Build Coastguard Worker BindOnce(&internal::ReturnAsParamAdapter<TaskReturnType>, 164*6777b538SAndroid Build Coastguard Worker std::move(task), result), 165*6777b538SAndroid Build Coastguard Worker BindOnce(&internal::ReplyAdapter<TaskReturnType, ReplyArgType>, 166*6777b538SAndroid Build Coastguard Worker std::move(reply), Owned(result))); 167*6777b538SAndroid Build Coastguard Worker } 168*6777b538SAndroid Build Coastguard Worker 169*6777b538SAndroid Build Coastguard Worker // Returns a TaskRunner whose PostTask invocations result in scheduling tasks 170*6777b538SAndroid Build Coastguard Worker // using |traits|. Tasks may run in any order and in parallel. 171*6777b538SAndroid Build Coastguard Worker static scoped_refptr<TaskRunner> CreateTaskRunner(const TaskTraits& traits); 172*6777b538SAndroid Build Coastguard Worker 173*6777b538SAndroid Build Coastguard Worker // Returns a SequencedTaskRunner whose PostTask invocations result in 174*6777b538SAndroid Build Coastguard Worker // scheduling tasks using |traits|. Tasks run one at a time in posting order. 175*6777b538SAndroid Build Coastguard Worker static scoped_refptr<SequencedTaskRunner> CreateSequencedTaskRunner( 176*6777b538SAndroid Build Coastguard Worker const TaskTraits& traits); 177*6777b538SAndroid Build Coastguard Worker 178*6777b538SAndroid Build Coastguard Worker // Returns a task runner whose PostTask invocations result in scheduling tasks 179*6777b538SAndroid Build Coastguard Worker // using |traits|. The priority in |traits| can be updated at any time via 180*6777b538SAndroid Build Coastguard Worker // UpdateableSequencedTaskRunner::UpdatePriority(). An update affects all 181*6777b538SAndroid Build Coastguard Worker // tasks posted to the task runner that aren't running yet. Tasks run one at a 182*6777b538SAndroid Build Coastguard Worker // time in posting order. 183*6777b538SAndroid Build Coastguard Worker // 184*6777b538SAndroid Build Coastguard Worker // |traits| requirements: 185*6777b538SAndroid Build Coastguard Worker // - base::ThreadPolicy must be specified if the priority of the task runner 186*6777b538SAndroid Build Coastguard Worker // will ever be increased from BEST_EFFORT. 187*6777b538SAndroid Build Coastguard Worker static scoped_refptr<UpdateableSequencedTaskRunner> 188*6777b538SAndroid Build Coastguard Worker CreateUpdateableSequencedTaskRunner(const TaskTraits& traits); 189*6777b538SAndroid Build Coastguard Worker 190*6777b538SAndroid Build Coastguard Worker // Returns a SingleThreadTaskRunner whose PostTask invocations result in 191*6777b538SAndroid Build Coastguard Worker // scheduling tasks using |traits| on a thread determined by |thread_mode|. 192*6777b538SAndroid Build Coastguard Worker // See base/task/single_thread_task_runner_thread_mode.h for |thread_mode| 193*6777b538SAndroid Build Coastguard Worker // details. If |traits| identifies an existing thread, 194*6777b538SAndroid Build Coastguard Worker // SingleThreadTaskRunnerThreadMode::SHARED must be used. Tasks run on a 195*6777b538SAndroid Build Coastguard Worker // single thread in posting order. 196*6777b538SAndroid Build Coastguard Worker // 197*6777b538SAndroid Build Coastguard Worker // If all you need is to make sure that tasks don't run concurrently (e.g. 198*6777b538SAndroid Build Coastguard Worker // because they access a data structure which is not thread-safe), use 199*6777b538SAndroid Build Coastguard Worker // CreateSequencedTaskRunner(). Only use this if you rely on a thread-affine 200*6777b538SAndroid Build Coastguard Worker // API (it might be safer to assume thread-affinity when dealing with 201*6777b538SAndroid Build Coastguard Worker // under-documented third-party APIs, e.g. other OS') or share data across 202*6777b538SAndroid Build Coastguard Worker // tasks using thread-local storage. 203*6777b538SAndroid Build Coastguard Worker static scoped_refptr<SingleThreadTaskRunner> CreateSingleThreadTaskRunner( 204*6777b538SAndroid Build Coastguard Worker const TaskTraits& traits, 205*6777b538SAndroid Build Coastguard Worker SingleThreadTaskRunnerThreadMode thread_mode = 206*6777b538SAndroid Build Coastguard Worker SingleThreadTaskRunnerThreadMode::SHARED); 207*6777b538SAndroid Build Coastguard Worker 208*6777b538SAndroid Build Coastguard Worker #if BUILDFLAG(IS_WIN) 209*6777b538SAndroid Build Coastguard Worker // Returns a SingleThreadTaskRunner whose PostTask invocations result in 210*6777b538SAndroid Build Coastguard Worker // scheduling tasks using |traits| in a COM Single-Threaded Apartment on a 211*6777b538SAndroid Build Coastguard Worker // thread determined by |thread_mode|. See 212*6777b538SAndroid Build Coastguard Worker // base/task/single_thread_task_runner_thread_mode.h for |thread_mode| 213*6777b538SAndroid Build Coastguard Worker // details. If |traits| identifies an existing thread, 214*6777b538SAndroid Build Coastguard Worker // SingleThreadTaskRunnerThreadMode::SHARED must be used. Tasks run in the 215*6777b538SAndroid Build Coastguard Worker // same Single-Threaded Apartment in posting order for the returned 216*6777b538SAndroid Build Coastguard Worker // SingleThreadTaskRunner. There is not necessarily a one-to-one 217*6777b538SAndroid Build Coastguard Worker // correspondence between SingleThreadTaskRunners and Single-Threaded 218*6777b538SAndroid Build Coastguard Worker // Apartments. The implementation is free to share apartments or create new 219*6777b538SAndroid Build Coastguard Worker // apartments as necessary. In either case, care should be taken to make sure 220*6777b538SAndroid Build Coastguard Worker // COM pointers are not smuggled across apartments. 221*6777b538SAndroid Build Coastguard Worker static scoped_refptr<SingleThreadTaskRunner> CreateCOMSTATaskRunner( 222*6777b538SAndroid Build Coastguard Worker const TaskTraits& traits, 223*6777b538SAndroid Build Coastguard Worker SingleThreadTaskRunnerThreadMode thread_mode = 224*6777b538SAndroid Build Coastguard Worker SingleThreadTaskRunnerThreadMode::SHARED); 225*6777b538SAndroid Build Coastguard Worker #endif // BUILDFLAG(IS_WIN) 226*6777b538SAndroid Build Coastguard Worker }; 227*6777b538SAndroid Build Coastguard Worker 228*6777b538SAndroid Build Coastguard Worker } // namespace base 229*6777b538SAndroid Build Coastguard Worker 230*6777b538SAndroid Build Coastguard Worker #endif // BASE_TASK_THREAD_POOL_H_ 231