blob: 5a7a5cf5e28cc086f222f563f01b41f249771d6e [file] [log] [blame] [view]
fdoraybacba4a22017-05-10 21:10:001# Threading and Tasks in Chrome
2
3[TOC]
4
Gabriel Charette8917f4c2018-11-22 15:50:285Note: See [Threading and Tasks FAQ](threading_and_tasks_faq.md) for more
6examples.
7
fdoraybacba4a22017-05-10 21:10:008## Overview
9
Gabriel Charette39db4c62019-04-29 19:52:3810Chrome has a [multi-process
11architecture](https://www.chromium.org/developers/design-documents/multi-process-architecture)
12and each process is heavily multi-threaded. In this document we will go over the
Charlie Harrisonbda54652023-11-17 21:20:0613basic threading system shared by each process. Our primary goal is to keep the
14browser highly responsive. Absent external requirements about latency or
15workload, Chrome attempts to be a [highly concurrent, but not necessarily
Matt Falkenhagen72a2dfc2021-08-05 22:36:1316parallel](https://stackoverflow.com/questions/1050222/what-is-the-difference-between-concurrency-and-parallelism#:~:text=Concurrency%20is%20when%20two%20or,e.g.%2C%20on%20a%20multicore%20processor.),
Jared Saulea867ab2021-07-15 17:39:0117system.
Gabriel Charette39db4c62019-04-29 19:52:3818
cfredricff6d86c2022-02-15 16:26:1119A basic intro to the way Chromium does concurrency (especially Sequences) can be
20found
21[here](https://docs.google.com/presentation/d/1ujV8LjIUyPBmULzdT2aT9Izte8PDwbJi).
22
Gabriel Charette39db4c62019-04-29 19:52:3823This documentation assumes familiarity with computer science
24[threading concepts](https://en.wikipedia.org/wiki/Thread_(computing)).
Gabriel Charette90480312018-02-16 15:10:0525
Charlie Harrisonbda54652023-11-17 21:20:0626### Quick start guide
27
28 * Do not perform expensive computation or blocking IO on the main thread
29 (a.k.a. “UI” thread in the browser process) or IO thread (each
30 process's thread for receiving IPC). A busy UI / IO thread can cause
31 user-visible latency, so prefer running that work on the
32 [thread pool](#direct-posting-to-the-thread-pool).
33 * Always avoid reading/writing to the same place in memory from separate
34 threads or sequences. This will lead to
35 [data races](https://en.wikipedia.org/wiki/Race_condition#Data_race)!
36 Prefer passing messages across sequences instead. Alternatives to message
37 passing like using locks is discouraged.
Charlie Harrisonbda54652023-11-17 21:20:0638 * If you need to orchestrate multiple objects that live on different
Erik Chen4676e2f2024-08-20 04:45:5739 sequences, be careful about object lifetimes.
40 * To prevent accidental data races, prefer for most classes to be used
41 exclusively on a single sequence. You should use utilities like
42 [SEQUENCE_CHECKER][4] or [base::SequenceBound][5] to help enforce this
43 constraint.
44 * As a rule of thumb, avoid [base::Unretained][1]. [weak pointers][2] can
45 usually be substituted.
46 * Explicit ownership via `std::unique_ptr` is preferred.
47 * [scoped_refptrs][3] can be used for objects that have multiple owners
48 across multiple sequences. This is usually the wrong design pattern and is
49 discouraged for new code.
50
51[1]: https://source.chromium.org/chromium/chromium/src/+/main:base/functional/bind.h;l=169;drc=ef1375f2c9fffa0d9cd664b43b0035c09fb70e99
52[2]: https://source.chromium.org/chromium/chromium/src/+/main:base/memory/weak_ptr.h
53[3]: https://source.chromium.org/chromium/chromium/src/+/main:base/memory/scoped_refptr.h
54[4]: https://source.chromium.org/chromium/chromium/src/+/main:base/sequence_checker.h
55[5]: https://source.chromium.org/chromium/chromium/src/+/main:base/threading/sequence_bound.h
Charlie Harrisonbda54652023-11-17 21:20:0656
Gabriel Charette364a16a2019-02-06 21:12:1557### Nomenclature
Gabriel Charette39db4c62019-04-29 19:52:3858
59## Core Concepts
60 * **Task**: A unit of work to be processed. Effectively a function pointer with
Alex St-Onge490a97a2021-02-04 02:47:1961 optionally associated state. In Chrome this is `base::OnceCallback` and
62 `base::RepeatingCallback` created via `base::BindOnce` and
63 `base::BindRepeating`, respectively.
Gabriel Charette39db4c62019-04-29 19:52:3864 ([documentation](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/callback.md)).
65 * **Task queue**: A queue of tasks to be processed.
66 * **Physical thread**: An operating system provided thread (e.g. pthread on
67 POSIX or CreateThread() on Windows). The Chrome cross-platform abstraction
68 is `base::PlatformThread`. You should pretty much never use this directly.
69 * **`base::Thread`**: A physical thread forever processing messages from a
70 dedicated task queue until Quit(). You should pretty much never be creating
71 your own `base::Thread`'s.
72 * **Thread pool**: A pool of physical threads with a shared task queue. In
Gabriel Charette0b20ee62019-09-18 14:06:1273 Chrome, this is `base::ThreadPoolInstance`. There's exactly one instance per
74 Chrome process, it serves tasks posted through
Gabriel Charette9b6c04072022-04-01 23:22:4675 [`base/task/thread_pool.h`](https://cs.chromium.org/chromium/src/base/task/thread_pool.h)
Gabriel Charette43fd3702019-05-29 16:36:5176 and as such you should rarely need to use the `base::ThreadPoolInstance` API
Gabriel Charette39db4c62019-04-29 19:52:3877 directly (more on posting tasks later).
78 * **Sequence** or **Virtual thread**: A chrome-managed thread of execution.
79 Like a physical thread, only one task can run on a given sequence / virtual
80 thread at any given moment and each task sees the side-effects of the
81 preceding tasks. Tasks are executed sequentially but may hop physical
82 threads between each one.
83 * **Task runner**: An interface through which tasks can be posted. In Chrome
84 this is `base::TaskRunner`.
85 * **Sequenced task runner**: A task runner which guarantees that tasks posted
86 to it will run sequentially, in posted order. Each such task is guaranteed to
87 see the side-effects of the task preceding it. Tasks posted to a sequenced
88 task runner are typically processed by a single thread (virtual or physical).
89 In Chrome this is `base::SequencedTaskRunner` which is-a
90 `base::TaskRunner`.
91 * **Single-thread task runner**: A sequenced task runner which guarantees that
92 all tasks will be processed by the same physical thread. In Chrome this is
93 `base::SingleThreadTaskRunner` which is-a `base::SequencedTaskRunner`. We
94 [prefer sequences to threads](#prefer-sequences-to-physical-threads) whenever
95 possible.
96
97## Threading Lexicon
98Note to the reader: the following terms are an attempt to bridge the gap between
99common threading nomenclature and the way we use them in Chrome. It might be a
100bit heavy if you're just getting started. Should this be hard to parse, consider
101skipping to the more detailed sections below and referring back to this as
102necessary.
103
104 * **Thread-unsafe**: The vast majority of types in Chrome are thread-unsafe
105 (by design). Access to such types/methods must be externally synchronized.
106 Typically thread-unsafe types require that all tasks accessing their state be
107 posted to the same `base::SequencedTaskRunner` and they verify this in debug
108 builds with a `SEQUENCE_CHECKER` member. Locks are also an option to
109 synchronize access but in Chrome we strongly
110 [prefer sequences to locks](#Using-Sequences-Instead-of-Locks).
Gabriel Charette364a16a2019-02-06 21:12:15111 * **Thread-affine**: Such types/methods need to be always accessed from the
Gabriel Charetteb984d672019-02-12 21:53:27112 same physical thread (i.e. from the same `base::SingleThreadTaskRunner`) and
Gabriel Charette39db4c62019-04-29 19:52:38113 typically have a `THREAD_CHECKER` member to verify that they are. Short of
114 using a third-party API or having a leaf dependency which is thread-affine:
115 there's pretty much no reason for a type to be thread-affine in Chrome.
116 Note that `base::SingleThreadTaskRunner` is-a `base::SequencedTaskRunner` so
Gabriel Charetteb984d672019-02-12 21:53:27117 thread-affine is a subset of thread-unsafe. Thread-affine is also sometimes
118 referred to as **thread-hostile**.
Albert J. Wongf06ff5002021-07-08 20:37:00119 * **Thread-safe**: Such types/methods can be safely accessed in parallel.
120 * **Thread-compatible**: Such types provide safe parallel access to const
Gabriel Charetteb984d672019-02-12 21:53:27121 methods but require synchronization for non-const (or mixed const/non-const
Gabriel Charette39db4c62019-04-29 19:52:38122 access). Chrome doesn't expose reader-writer locks; as such, the only use
Gabriel Charetteb984d672019-02-12 21:53:27123 case for this is objects (typically globals) which are initialized once in a
Gabriel Charette364a16a2019-02-06 21:12:15124 thread-safe manner (either in the single-threaded phase of startup or lazily
125 through a thread-safe static-local-initialization paradigm a la
Gabriel Charetteb984d672019-02-12 21:53:27126 `base::NoDestructor`) and forever after immutable.
127 * **Immutable**: A subset of thread-compatible types which cannot be modified
128 after construction.
Gabriel Charette364a16a2019-02-06 21:12:15129 * **Sequence-friendly**: Such types/methods are thread-unsafe types which
130 support being invoked from a `base::SequencedTaskRunner`. Ideally this would
131 be the case for all thread-unsafe types but legacy code sometimes has
132 overzealous checks that enforce thread-affinity in mere thread-unsafe
Gabriel Charette39db4c62019-04-29 19:52:38133 scenarios. See [Prefer Sequences to
134 Threads](#prefer-sequences-to-physical-threads) below for more details.
Gabriel Charette364a16a2019-02-06 21:12:15135
fdoraybacba4a22017-05-10 21:10:00136### Threads
137
138Every Chrome process has
139
140* a main thread
Gabriel Charette39db4c62019-04-29 19:52:38141 * in the browser process (BrowserThread::UI): updates the UI
142 * in renderer processes (Blink main thread): runs most of Blink
fdoraybacba4a22017-05-10 21:10:00143* an IO thread
Matt Falkenhagen72a2dfc2021-08-05 22:36:13144 * in all processes: all IPC messages arrive on this thread. The application
145 logic to handle the message may be in a different thread (i.e., the IO
146 thread may route the message to a [Mojo
147 interface](/docs/README.md#Mojo-Services) which is bound to a
148 different thread).
149 * more generally most async I/O happens on this thread (e.g., through
150 base::FileDescriptorWatcher).
151 * in the browser process: this is called BrowserThread::IO.
fdoraybacba4a22017-05-10 21:10:00152* a few more special-purpose threads
153* and a pool of general-purpose threads
154
155Most threads have a loop that gets tasks from a queue and runs them (the queue
156may be shared between multiple threads).
157
158### Tasks
159
160A task is a `base::OnceClosure` added to a queue for asynchronous execution.
161
162A `base::OnceClosure` stores a function pointer and arguments. It has a `Run()`
163method that invokes the function pointer using the bound arguments. It is
164created using `base::BindOnce`. (ref. [Callback<> and Bind()
165documentation](callback.md)).
166
167```
168void TaskA() {}
169void TaskB(int v) {}
170
171auto task_a = base::BindOnce(&TaskA);
172auto task_b = base::BindOnce(&TaskB, 42);
173```
174
175A group of tasks can be executed in one of the following ways:
176
177* [Parallel](#Posting-a-Parallel-Task): No task execution ordering, possibly all
178 at once on any thread
179* [Sequenced](#Posting-a-Sequenced-Task): Tasks executed in posting order, one
180 at a time on any thread.
181* [Single Threaded](#Posting-Multiple-Tasks-to-the-Same-Thread): Tasks executed
182 in posting order, one at a time on a single thread.
Drew Stonebraker653a3ba2019-07-02 19:24:23183 * [COM Single Threaded](#Posting-Tasks-to-a-COM-Single_Thread-Apartment-STA_Thread-Windows):
fdoraybacba4a22017-05-10 21:10:00184 A variant of single threaded with COM initialized.
185
Gabriel Charette39db4c62019-04-29 19:52:38186### Prefer Sequences to Physical Threads
gab2a4576052017-06-07 23:36:12187
Gabriel Charette39db4c62019-04-29 19:52:38188Sequenced execution (on virtual threads) is strongly preferred to
189single-threaded execution (on physical threads). Except for types/methods bound
190to the main thread (UI) or IO threads: thread-safety is better achieved via
191`base::SequencedTaskRunner` than through managing your own physical threads
192(ref. [Posting a Sequenced Task](#posting-a-sequenced-task) below).
gab2a4576052017-06-07 23:36:12193
Gabriel Charette39db4c62019-04-29 19:52:38194All APIs which are exposed for "current physical thread" have an equivalent for
195"current sequence"
196([mapping](threading_and_tasks_faq.md#How-to-migrate-from-SingleThreadTaskRunner-to-SequencedTaskRunner)).
gab2a4576052017-06-07 23:36:12197
Gabriel Charette39db4c62019-04-29 19:52:38198If you find yourself writing a sequence-friendly type and it fails
199thread-affinity checks (e.g., `THREAD_CHECKER`) in a leaf dependency: consider
200making that dependency sequence-friendly as well. Most core APIs in Chrome are
201sequence-friendly, but some legacy types may still over-zealously use
Sean Maher03efef12022-09-23 22:43:13202ThreadChecker/SingleThreadTaskRunner when they could instead rely on the
203"current sequence" and no longer be thread-affine.
fdoraybacba4a22017-05-10 21:10:00204
205## Posting a Parallel Task
206
Gabriel Charette52fa3ae2019-04-15 21:44:37207### Direct Posting to the Thread Pool
fdoraybacba4a22017-05-10 21:10:00208
209A task that can run on any thread and doesn’t have ordering or mutual exclusion
210requirements with other tasks should be posted using one of the
Gabriel Charette43de5c42020-01-27 22:44:45211`base::ThreadPool::PostTask*()` functions defined in
212[`base/task/thread_pool.h`](https://cs.chromium.org/chromium/src/base/task/thread_pool.h).
fdoraybacba4a22017-05-10 21:10:00213
214```cpp
Gabriel Charette43de5c42020-01-27 22:44:45215base::ThreadPool::PostTask(FROM_HERE, base::BindOnce(&Task));
fdoraybacba4a22017-05-10 21:10:00216```
217
218This posts tasks with default traits.
219
Gabriel Charette43de5c42020-01-27 22:44:45220The `base::ThreadPool::PostTask*()` functions allow the caller to provide
221additional details about the task via TaskTraits (ref. [Annotating Tasks with
222TaskTraits](#Annotating-Tasks-with-TaskTraits)).
fdoraybacba4a22017-05-10 21:10:00223
224```cpp
Gabriel Charette43de5c42020-01-27 22:44:45225base::ThreadPool::PostTask(
Gabriel Charetteb10aeeb2018-07-26 20:15:00226 FROM_HERE, {base::TaskPriority::BEST_EFFORT, MayBlock()},
fdoraybacba4a22017-05-10 21:10:00227 base::BindOnce(&Task));
228```
229
fdoray52bf5552017-05-11 12:43:59230### Posting via a TaskRunner
fdoraybacba4a22017-05-10 21:10:00231
232A parallel
Patrick Monette2d93ad902021-11-01 19:20:22233[`base::TaskRunner`](https://cs.chromium.org/chromium/src/base/task/task_runner.h) is
Gabriel Charette43de5c42020-01-27 22:44:45234an alternative to calling `base::ThreadPool::PostTask*()` directly. This is
235mainly useful when it isn’t known in advance whether tasks will be posted in
236parallel, in sequence, or to a single-thread (ref. [Posting a Sequenced
Gabriel Charette39db4c62019-04-29 19:52:38237Task](#Posting-a-Sequenced-Task), [Posting Multiple Tasks to the Same
238Thread](#Posting-Multiple-Tasks-to-the-Same-Thread)). Since `base::TaskRunner`
239is the base class of `base::SequencedTaskRunner` and
240`base::SingleThreadTaskRunner`, a `scoped_refptr<TaskRunner>` member can hold a
241`base::TaskRunner`, a `base::SequencedTaskRunner` or a
242`base::SingleThreadTaskRunner`.
fdoraybacba4a22017-05-10 21:10:00243
244```cpp
245class A {
246 public:
247 A() = default;
248
Gabriel Charette43de5c42020-01-27 22:44:45249 void PostSomething() {
250 task_runner_->PostTask(FROM_HERE, base::BindOnce(&A, &DoSomething));
251 }
252
fdoraybacba4a22017-05-10 21:10:00253 void DoSomething() {
fdoraybacba4a22017-05-10 21:10:00254 }
255
256 private:
257 scoped_refptr<base::TaskRunner> task_runner_ =
Gabriel Charette43de5c42020-01-27 22:44:45258 base::ThreadPool::CreateTaskRunner({base::TaskPriority::USER_VISIBLE});
fdoraybacba4a22017-05-10 21:10:00259};
260```
261
262Unless a test needs to control precisely how tasks are executed, it is preferred
Gabriel Charette49e3cd02020-01-28 03:45:27263to call `base::ThreadPool::PostTask*()` directly (ref. [Testing](#Testing) for
264less invasive ways of controlling tasks in tests).
fdoraybacba4a22017-05-10 21:10:00265
266## Posting a Sequenced Task
267
268A sequence is a set of tasks that run one at a time in posting order (not
269necessarily on the same thread). To post tasks as part of a sequence, use a
Patrick Monette2d93ad902021-11-01 19:20:22270[`base::SequencedTaskRunner`](https://cs.chromium.org/chromium/src/base/task/sequenced_task_runner.h).
fdoraybacba4a22017-05-10 21:10:00271
272### Posting to a New Sequence
273
Gabriel Charette39db4c62019-04-29 19:52:38274A `base::SequencedTaskRunner` can be created by
Gabriel Charette43de5c42020-01-27 22:44:45275`base::ThreadPool::CreateSequencedTaskRunner()`.
fdoraybacba4a22017-05-10 21:10:00276
277```cpp
278scoped_refptr<SequencedTaskRunner> sequenced_task_runner =
Gabriel Charette43de5c42020-01-27 22:44:45279 base::ThreadPool::CreateSequencedTaskRunner(...);
fdoraybacba4a22017-05-10 21:10:00280
281// TaskB runs after TaskA completes.
282sequenced_task_runner->PostTask(FROM_HERE, base::BindOnce(&TaskA));
283sequenced_task_runner->PostTask(FROM_HERE, base::BindOnce(&TaskB));
284```
285
Alex Clarke0dd499562019-10-18 19:45:09286### Posting to the Current (Virtual) Thread
287
Gabriel Charettefee55662019-11-20 21:06:28288The preferred way of posting to the current (virtual) thread is via
Sean Maher03efef12022-09-23 22:43:13289`base::SequencedTaskRunner::GetCurrentDefault()`.
Alex Clarke0dd499562019-10-18 19:45:09290
291```cpp
292// The task will run on the current (virtual) thread's default task queue.
Sean Maher03efef12022-09-23 22:43:13293base::SequencedTaskRunner::GetCurrentDefault()->PostTask(
Andrew Paseltinerc0bfc2d82024-03-28 18:28:11294 FROM_HERE, base::BindOnce(&Task));
Alex Clarke0dd499562019-10-18 19:45:09295```
296
Sean Maher03efef12022-09-23 22:43:13297Note that `SequencedTaskRunner::GetCurrentDefault()` returns the default queue for the
Gabriel Charettefee55662019-11-20 21:06:28298current virtual thread. On threads with multiple task queues (e.g.
299BrowserThread::UI) this can be a different queue than the one the current task
300belongs to. The "current" task runner is intentionally not exposed via a static
301getter. Either you know it already and can post to it directly or you don't and
Francois Doraya06ee172022-11-24 21:09:18302the only sensible destination is the default queue. See https://bit.ly/3JvCLsX
Sean Maher03efef12022-09-23 22:43:13303for detailed discussion.
Alex Clarke0dd499562019-10-18 19:45:09304
fdoraybacba4a22017-05-10 21:10:00305## Using Sequences Instead of Locks
306
307Usage of locks is discouraged in Chrome. Sequences inherently provide
Gabriel Charettea3ccc972018-11-13 14:43:12308thread-safety. Prefer classes that are always accessed from the same
309sequence to managing your own thread-safety with locks.
310
311**Thread-safe but not thread-affine; how so?** Tasks posted to the same sequence
312will run in sequential order. After a sequenced task completes, the next task
313may be picked up by a different worker thread, but that task is guaranteed to
314see any side-effects caused by the previous one(s) on its sequence.
fdoraybacba4a22017-05-10 21:10:00315
316```cpp
317class A {
318 public:
319 A() {
320 // Do not require accesses to be on the creation sequence.
isherman8c33b8a2017-06-27 19:18:30321 DETACH_FROM_SEQUENCE(sequence_checker_);
fdoraybacba4a22017-05-10 21:10:00322 }
323
324 void AddValue(int v) {
325 // Check that all accesses are on the same sequence.
isherman8c33b8a2017-06-27 19:18:30326 DCHECK_CALLED_ON_VALID_SEQUENCE(sequence_checker_);
fdoraybacba4a22017-05-10 21:10:00327 values_.push_back(v);
328}
329
330 private:
isherman8c33b8a2017-06-27 19:18:30331 SEQUENCE_CHECKER(sequence_checker_);
fdoraybacba4a22017-05-10 21:10:00332
333 // No lock required, because all accesses are on the
334 // same sequence.
335 std::vector<int> values_;
336};
337
338A a;
339scoped_refptr<SequencedTaskRunner> task_runner_for_a = ...;
Mike Bjorged3a09842018-05-15 18:37:28340task_runner_for_a->PostTask(FROM_HERE,
341 base::BindOnce(&A::AddValue, base::Unretained(&a), 42));
342task_runner_for_a->PostTask(FROM_HERE,
343 base::BindOnce(&A::AddValue, base::Unretained(&a), 27));
fdoraybacba4a22017-05-10 21:10:00344
345// Access from a different sequence causes a DCHECK failure.
346scoped_refptr<SequencedTaskRunner> other_task_runner = ...;
347other_task_runner->PostTask(FROM_HERE,
Mike Bjorged3a09842018-05-15 18:37:28348 base::BindOnce(&A::AddValue, base::Unretained(&a), 1));
fdoraybacba4a22017-05-10 21:10:00349```
350
Gabriel Charette90480312018-02-16 15:10:05351Locks should only be used to swap in a shared data structure that can be
352accessed on multiple threads. If one thread updates it based on expensive
353computation or through disk access, then that slow work should be done without
Gabriel Charette39db4c62019-04-29 19:52:38354holding the lock. Only when the result is available should the lock be used to
355swap in the new data. An example of this is in PluginList::LoadPlugins
356([`content/browser/plugin_list.cc`](https://cs.chromium.org/chromium/src/content/browser/plugin_list.cc).
357If you must use locks,
Gabriel Charette90480312018-02-16 15:10:05358[here](https://www.chromium.org/developers/lock-and-condition-variable) are some
359best practices and pitfalls to avoid.
360
Gabriel Charette39db4c62019-04-29 19:52:38361In order to write non-blocking code, many APIs in Chrome are asynchronous.
Gabriel Charette90480312018-02-16 15:10:05362Usually this means that they either need to be executed on a particular
363thread/sequence and will return results via a custom delegate interface, or they
Alex St-Onge490a97a2021-02-04 02:47:19364take a `base::OnceCallback<>` (or `base::RepeatingCallback<>`) object that is
365called when the requested operation is completed. Executing work on a specific
366thread/sequence is covered in the PostTask sections above.
Gabriel Charette90480312018-02-16 15:10:05367
fdoraybacba4a22017-05-10 21:10:00368## Posting Multiple Tasks to the Same Thread
369
370If multiple tasks need to run on the same thread, post them to a
Patrick Monette2d93ad902021-11-01 19:20:22371[`base::SingleThreadTaskRunner`](https://cs.chromium.org/chromium/src/base/task/single_thread_task_runner.h).
Gabriel Charette39db4c62019-04-29 19:52:38372All tasks posted to the same `base::SingleThreadTaskRunner` run on the same thread in
fdoraybacba4a22017-05-10 21:10:00373posting order.
374
375### Posting to the Main Thread or to the IO Thread in the Browser Process
376
Eric Seckler6cf08db82018-08-30 12:01:55377To post tasks to the main thread or to the IO thread, use
Olivier Li56b99d4e2020-02-11 13:51:41378`content::GetUIThreadTaskRunner({})` or `content::GetIOThreadTaskRunner({})`
Gabriel Charette49e3cd02020-01-28 03:45:27379from
380[`content/public/browser/browser_thread.h`](https://cs.chromium.org/chromium/src/content/public/browser/browser_thread.h)
381
382You may provide additional BrowserTaskTraits as a parameter to those methods
383though this is generally still uncommon in BrowserThreads and should be reserved
384for advanced use cases.
385
386There's an ongoing migration ([task APIs v3]) away from the previous
387base-API-with-traits which you may still find throughout the codebase (it's
388equivalent):
fdoraybacba4a22017-05-10 21:10:00389
390```cpp
Sami Kyostila831c60b2019-07-31 13:31:23391base::PostTask(FROM_HERE, {content::BrowserThread::UI}, ...);
fdoraybacba4a22017-05-10 21:10:00392
Sami Kyostila831c60b2019-07-31 13:31:23393base::CreateSingleThreadTaskRunner({content::BrowserThread::IO})
fdoraybacba4a22017-05-10 21:10:00394 ->PostTask(FROM_HERE, ...);
395```
396
Gabriel Charette49e3cd02020-01-28 03:45:27397Note: For the duration of the migration, you'll unfortunately need to continue
398manually including
399[`content/public/browser/browser_task_traits.h`](https://cs.chromium.org/chromium/src/content/public/browser/browser_task_traits.h).
400to use the browser_thread.h API.
Gabriel Charette43de5c42020-01-27 22:44:45401
fdoraybacba4a22017-05-10 21:10:00402The main thread and the IO thread are already super busy. Therefore, prefer
fdoray52bf5552017-05-11 12:43:59403posting to a general purpose thread when possible (ref.
404[Posting a Parallel Task](#Posting-a-Parallel-Task),
405[Posting a Sequenced task](#Posting-a-Sequenced-Task)).
406Good reasons to post to the main thread are to update the UI or access objects
407that are bound to it (e.g. `Profile`). A good reason to post to the IO thread is
408to access the internals of components that are bound to it (e.g. IPCs, network).
409Note: It is not necessary to have an explicit post task to the IO thread to
410send/receive an IPC or send/receive data on the network.
fdoraybacba4a22017-05-10 21:10:00411
412### Posting to the Main Thread in a Renderer Process
Gabriel Charette49e3cd02020-01-28 03:45:27413TODO(blink-dev)
fdoraybacba4a22017-05-10 21:10:00414
415### Posting to a Custom SingleThreadTaskRunner
416
417If multiple tasks need to run on the same thread and that thread doesn’t have to
Gabriel Charette43de5c42020-01-27 22:44:45418be the main thread or the IO thread, post them to a
Gabriel Charette49e3cd02020-01-28 03:45:27419`base::SingleThreadTaskRunner` created by
420`base::Threadpool::CreateSingleThreadTaskRunner`.
fdoraybacba4a22017-05-10 21:10:00421
422```cpp
Dominic Farolinodbe9769b2019-05-31 04:06:03423scoped_refptr<SingleThreadTaskRunner> single_thread_task_runner =
Gabriel Charette43de5c42020-01-27 22:44:45424 base::Threadpool::CreateSingleThreadTaskRunner(...);
fdoraybacba4a22017-05-10 21:10:00425
426// TaskB runs after TaskA completes. Both tasks run on the same thread.
427single_thread_task_runner->PostTask(FROM_HERE, base::BindOnce(&TaskA));
428single_thread_task_runner->PostTask(FROM_HERE, base::BindOnce(&TaskB));
429```
430
Gabriel Charette39db4c62019-04-29 19:52:38431Remember that we [prefer sequences to physical
432threads](#prefer-sequences-to-physical-threads) and that this thus should rarely
433be necessary.
fdoraybacba4a22017-05-10 21:10:00434
Alexander Timine653dfc2020-01-07 17:55:06435### Posting to the Current Thread
436
437*** note
438**IMPORTANT:** To post a task that needs mutual exclusion with the current
Gabriel Charette49e3cd02020-01-28 03:45:27439sequence of tasks but doesn’t absolutely need to run on the current physical
Sean Maher03efef12022-09-23 22:43:13440thread, use `base::SequencedTaskRunner::GetCurrentDefault()` instead of
441`base::SingleThreadTaskRunner::GetCurrentDefault()` (ref. [Posting to the Current
Gabriel Charette49e3cd02020-01-28 03:45:27442Sequence](#Posting-to-the-Current-Virtual_Thread)). That will better document
443the requirements of the posted task and will avoid unnecessarily making your API
444physical thread-affine. In a single-thread task,
Sean Maher03efef12022-09-23 22:43:13445`base::SequencedTaskRunner::GetCurrentDefault()` is equivalent to
446`base::SingleThreadTaskRunner::GetCurrentDefault()`.
Alexander Timine653dfc2020-01-07 17:55:06447***
448
449If you must post a task to the current physical thread nonetheless, use
Sean Maher03efef12022-09-23 22:43:13450[`base::SingleThreadTaskRunner::CurrentDefaultHandle`](https://source.chromium.org/chromium/chromium/src/+/main:base/task/single_thread_task_runner.h).
Alexander Timine653dfc2020-01-07 17:55:06451
452```cpp
453// The task will run on the current thread in the future.
Sean Maher03efef12022-09-23 22:43:13454base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(
Alexander Timine653dfc2020-01-07 17:55:06455 FROM_HERE, base::BindOnce(&Task));
456```
457
fdoraybacba4a22017-05-10 21:10:00458## Posting Tasks to a COM Single-Thread Apartment (STA) Thread (Windows)
459
460Tasks that need to run on a COM Single-Thread Apartment (STA) thread must be
Gabriel Charette39db4c62019-04-29 19:52:38461posted to a `base::SingleThreadTaskRunner` returned by
Gabriel Charette43de5c42020-01-27 22:44:45462`base::ThreadPool::CreateCOMSTATaskRunner()`. As mentioned in [Posting Multiple
463Tasks to the Same Thread](#Posting-Multiple-Tasks-to-the-Same-Thread), all tasks
464posted to the same `base::SingleThreadTaskRunner` run on the same thread in
465posting order.
fdoraybacba4a22017-05-10 21:10:00466
467```cpp
468// Task(A|B|C)UsingCOMSTA will run on the same COM STA thread.
469
470void TaskAUsingCOMSTA() {
471 // [ This runs on a COM STA thread. ]
472
473 // Make COM STA calls.
474 // ...
475
476 // Post another task to the current COM STA thread.
Sean Maher03efef12022-09-23 22:43:13477 base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(
fdoraybacba4a22017-05-10 21:10:00478 FROM_HERE, base::BindOnce(&TaskCUsingCOMSTA));
479}
480void TaskBUsingCOMSTA() { }
481void TaskCUsingCOMSTA() { }
482
Gabriel Charette43de5c42020-01-27 22:44:45483auto com_sta_task_runner = base::ThreadPool::CreateCOMSTATaskRunner(...);
fdoraybacba4a22017-05-10 21:10:00484com_sta_task_runner->PostTask(FROM_HERE, base::BindOnce(&TaskAUsingCOMSTA));
485com_sta_task_runner->PostTask(FROM_HERE, base::BindOnce(&TaskBUsingCOMSTA));
486```
487
Egor Pasko7f58c33b2023-02-17 13:19:56488## Memory ordering guarantees for posted Tasks
489
490This task system guarantees that all the memory effects of sequential execution
Egor Pasko049e8d352023-02-23 17:09:50491before posting a task are _visible_ to the task when it starts running. More
492formally, a call to `PostTask()` and the execution of the posted task are in the
493[happens-before
Egor Pasko7f58c33b2023-02-17 13:19:56494relationship](https://preshing.com/20130702/the-happens-before-relation/) with
Egor Pasko049e8d352023-02-23 17:09:50495each other. This is true for all variants of posting a task in `::base`,
496including `PostTaskAndReply()`. Similarly the happens-before relationship is
497present for tasks running in a sequence as part of the same SequencedTaskRunner.
Egor Pasko7f58c33b2023-02-17 13:19:56498
Egor Pasko049e8d352023-02-23 17:09:50499This guarantee is important to know about because Chrome tasks commonly access
500memory beyond the immediate data copied into the `base::OnceCallback`, and this
501happens-before relationship allows to avoid additional synchronization within
502the tasks themselves. As a very specific example, consider a callback that binds
503a pointer to memory which was just initialized in the thread posting the task.
Egor Pasko7f58c33b2023-02-17 13:19:56504
Egor Pasko049e8d352023-02-23 17:09:50505A more constrained model is also worth noting. Execution can be split into tasks
506running on different task runners, where each task _exclusively_ accesses
507certain objects in memory without explicit synchronization. Posting another task
508transfers this 'ownership' (of the objects) to the next task. With this the
509notion of object ownership can often be extended to the level of task runners,
510which provides useful invariants to reason about. This model allows to avoid
511race conditions while also avoiding locks and atomic operations. Because of its
512simplicity this model is commonly used in Chrome.
Egor Pasko7f58c33b2023-02-17 13:19:56513
fdoraybacba4a22017-05-10 21:10:00514## Annotating Tasks with TaskTraits
515
Gabriel Charette39db4c62019-04-29 19:52:38516[`base::TaskTraits`](https://cs.chromium.org/chromium/src/base/task/task_traits.h)
Gabriel Charette52fa3ae2019-04-15 21:44:37517encapsulate information about a task that helps the thread pool make better
fdoraybacba4a22017-05-10 21:10:00518scheduling decisions.
519
Gabriel Charette43de5c42020-01-27 22:44:45520Methods that take `base::TaskTraits` can be be passed `{}` when default traits
521are sufficient. Default traits are appropriate for tasks that:
Nigel Tao26ad1852023-03-23 01:14:56522
Gabriel Charettede41cad2020-03-03 18:05:06523- Don’t block (ref. MayBlock and WithBaseSyncPrimitives);
524- Pertain to user-blocking activity;
525 (explicitly or implicitly by having an ordering dependency with a component
526 that does)
Gabriel Charette52fa3ae2019-04-15 21:44:37527- Can either block shutdown or be skipped on shutdown (thread pool is free to
528 choose a fitting default).
Nigel Tao26ad1852023-03-23 01:14:56529
fdoraybacba4a22017-05-10 21:10:00530Tasks that don’t match this description must be posted with explicit TaskTraits.
531
Gabriel Charette04b138f2018-08-06 00:03:22532[`base/task/task_traits.h`](https://cs.chromium.org/chromium/src/base/task/task_traits.h)
Eric Seckler6cf08db82018-08-30 12:01:55533provides exhaustive documentation of available traits. The content layer also
534provides additional traits in
535[`content/public/browser/browser_task_traits.h`](https://cs.chromium.org/chromium/src/content/public/browser/browser_task_traits.h)
536to facilitate posting a task onto a BrowserThread.
537
Gabriel Charette39db4c62019-04-29 19:52:38538Below are some examples of how to specify `base::TaskTraits`.
fdoraybacba4a22017-05-10 21:10:00539
540```cpp
Gabriel Charettede41cad2020-03-03 18:05:06541// This task has no explicit TaskTraits. It cannot block. Its priority is
542// USER_BLOCKING. It will either block shutdown or be skipped on shutdown.
Gabriel Charette43de5c42020-01-27 22:44:45543base::ThreadPool::PostTask(FROM_HERE, base::BindOnce(...));
fdoraybacba4a22017-05-10 21:10:00544
Gabriel Charettede41cad2020-03-03 18:05:06545// This task has the highest priority. The thread pool will schedule it before
546// USER_VISIBLE and BEST_EFFORT tasks.
Gabriel Charette43de5c42020-01-27 22:44:45547base::ThreadPool::PostTask(
fdoraybacba4a22017-05-10 21:10:00548 FROM_HERE, {base::TaskPriority::USER_BLOCKING},
549 base::BindOnce(...));
550
551// This task has the lowest priority and is allowed to block (e.g. it
552// can read a file from disk).
Gabriel Charette43de5c42020-01-27 22:44:45553base::ThreadPool::PostTask(
Gabriel Charetteb10aeeb2018-07-26 20:15:00554 FROM_HERE, {base::TaskPriority::BEST_EFFORT, base::MayBlock()},
fdoraybacba4a22017-05-10 21:10:00555 base::BindOnce(...));
556
557// This task blocks shutdown. The process won't exit before its
558// execution is complete.
Gabriel Charette43de5c42020-01-27 22:44:45559base::ThreadPool::PostTask(
fdoraybacba4a22017-05-10 21:10:00560 FROM_HERE, {base::TaskShutdownBehavior::BLOCK_SHUTDOWN},
561 base::BindOnce(...));
562```
563
564## Keeping the Browser Responsive
565
566Do not perform expensive work on the main thread, the IO thread or any sequence
567that is expected to run tasks with a low latency. Instead, perform expensive
Gabriel Charette43de5c42020-01-27 22:44:45568work asynchronously using `base::ThreadPool::PostTaskAndReply*()` or
Gabriel Charette39db4c62019-04-29 19:52:38569`base::SequencedTaskRunner::PostTaskAndReply()`. Note that
570asynchronous/overlapped I/O on the IO thread are fine.
fdoraybacba4a22017-05-10 21:10:00571
572Example: Running the code below on the main thread will prevent the browser from
573responding to user input for a long time.
574
575```cpp
576// GetHistoryItemsFromDisk() may block for a long time.
577// AddHistoryItemsToOmniboxDropDown() updates the UI and therefore must
578// be called on the main thread.
579AddHistoryItemsToOmniboxDropdown(GetHistoryItemsFromDisk("keyword"));
580```
581
582The code below solves the problem by scheduling a call to
583`GetHistoryItemsFromDisk()` in a thread pool followed by a call to
584`AddHistoryItemsToOmniboxDropdown()` on the origin sequence (the main thread in
585this case). The return value of the first call is automatically provided as
586argument to the second call.
587
588```cpp
Gabriel Charette43de5c42020-01-27 22:44:45589base::ThreadPool::PostTaskAndReplyWithResult(
fdoraybacba4a22017-05-10 21:10:00590 FROM_HERE, {base::MayBlock()},
591 base::BindOnce(&GetHistoryItemsFromDisk, "keyword"),
592 base::BindOnce(&AddHistoryItemsToOmniboxDropdown));
593```
594
595## Posting a Task with a Delay
596
597### Posting a One-Off Task with a Delay
598
599To post a task that must run once after a delay expires, use
Gabriel Charette43de5c42020-01-27 22:44:45600`base::ThreadPool::PostDelayedTask*()` or `base::TaskRunner::PostDelayedTask()`.
fdoraybacba4a22017-05-10 21:10:00601
602```cpp
Gabriel Charette43de5c42020-01-27 22:44:45603base::ThreadPool::PostDelayedTask(
Gabriel Charetteb10aeeb2018-07-26 20:15:00604 FROM_HERE, {base::TaskPriority::BEST_EFFORT}, base::BindOnce(&Task),
Peter Kastinge5a38ed2021-10-02 03:06:35605 base::Hours(1));
fdoraybacba4a22017-05-10 21:10:00606
607scoped_refptr<base::SequencedTaskRunner> task_runner =
Gabriel Charette43de5c42020-01-27 22:44:45608 base::ThreadPool::CreateSequencedTaskRunner(
609 {base::TaskPriority::BEST_EFFORT});
fdoraybacba4a22017-05-10 21:10:00610task_runner->PostDelayedTask(
Peter Kastinge5a38ed2021-10-02 03:06:35611 FROM_HERE, base::BindOnce(&Task), base::Hours(1));
fdoraybacba4a22017-05-10 21:10:00612```
613
614*** note
615**NOTE:** A task that has a 1-hour delay probably doesn’t have to run right away
Gabriel Charetteb10aeeb2018-07-26 20:15:00616when its delay expires. Specify `base::TaskPriority::BEST_EFFORT` to prevent it
fdoraybacba4a22017-05-10 21:10:00617from slowing down the browser when its delay expires.
618***
619
620### Posting a Repeating Task with a Delay
621To post a task that must run at regular intervals,
622use [`base::RepeatingTimer`](https://cs.chromium.org/chromium/src/base/timer/timer.h).
623
624```cpp
625class A {
626 public:
627 ~A() {
628 // The timer is stopped automatically when it is deleted.
629 }
630 void StartDoingStuff() {
Peter Kasting53fd6ee2021-10-05 20:40:48631 timer_.Start(FROM_HERE, Seconds(1),
Erik Chen0ee26a32021-07-14 20:04:47632 this, &A::DoStuff);
fdoraybacba4a22017-05-10 21:10:00633 }
634 void StopDoingStuff() {
635 timer_.Stop();
636 }
637 private:
638 void DoStuff() {
639 // This method is called every second on the sequence that invoked
640 // StartDoingStuff().
641 }
642 base::RepeatingTimer timer_;
643};
644```
645
646## Cancelling a Task
647
648### Using base::WeakPtr
649
650[`base::WeakPtr`](https://cs.chromium.org/chromium/src/base/memory/weak_ptr.h)
651can be used to ensure that any callback bound to an object is canceled when that
652object is destroyed.
653
654```cpp
655int Compute() { … }
656
657class A {
658 public:
fdoraybacba4a22017-05-10 21:10:00659 void ComputeAndStore() {
660 // Schedule a call to Compute() in a thread pool followed by
661 // a call to A::Store() on the current sequence. The call to
662 // A::Store() is canceled when |weak_ptr_factory_| is destroyed.
663 // (guarantees that |this| will not be used-after-free).
Gabriel Charette43de5c42020-01-27 22:44:45664 base::ThreadPool::PostTaskAndReplyWithResult(
fdoraybacba4a22017-05-10 21:10:00665 FROM_HERE, base::BindOnce(&Compute),
666 base::BindOnce(&A::Store, weak_ptr_factory_.GetWeakPtr()));
667 }
668
669 private:
670 void Store(int value) { value_ = value; }
671
672 int value_;
Jeremy Roman0dd0b2f2019-07-16 21:00:43673 base::WeakPtrFactory<A> weak_ptr_factory_{this};
fdoraybacba4a22017-05-10 21:10:00674};
675```
676
Eugene Zemtsov48b30d32022-03-18 23:56:11677Note: `WeakPtr` is not thread-safe: `~WeakPtrFactory()` and
Francois Dorayf652a9d02021-07-06 13:07:52678`Store()` (bound to a `WeakPtr`) must all run on the same sequence.
fdoraybacba4a22017-05-10 21:10:00679
680### Using base::CancelableTaskTracker
681
682[`base::CancelableTaskTracker`](https://cs.chromium.org/chromium/src/base/task/cancelable_task_tracker.h)
683allows cancellation to happen on a different sequence than the one on which
684tasks run. Keep in mind that `CancelableTaskTracker` cannot cancel tasks that
685have already started to run.
686
687```cpp
Gabriel Charette43de5c42020-01-27 22:44:45688auto task_runner = base::ThreadPool::CreateTaskRunner({});
fdoraybacba4a22017-05-10 21:10:00689base::CancelableTaskTracker cancelable_task_tracker;
690cancelable_task_tracker.PostTask(task_runner.get(), FROM_HERE,
Peter Kasting341e1fb2018-02-24 00:03:01691 base::DoNothing());
fdoraybacba4a22017-05-10 21:10:00692// Cancels Task(), only if it hasn't already started running.
693cancelable_task_tracker.TryCancelAll();
694```
695
Etienne Pierre-dorayd3882992020-01-14 20:34:11696## Posting a Job to run in parallel
697
698The [`base::PostJob`](https://cs.chromium.org/chromium/src/base/task/post_job.h)
699is a power user API to be able to schedule a single base::RepeatingCallback
Albert J. Wongf06ff5002021-07-08 20:37:00700worker task and request that ThreadPool workers invoke it in parallel.
Etienne Pierre-dorayd3882992020-01-14 20:34:11701This avoids degenerate cases:
702* Calling `PostTask()` for each work item, causing significant overhead.
703* Fixed number of `PostTask()` calls that split the work and might run for a
704 long time. This is problematic when many components post “num cores” tasks and
705 all expect to use all the cores. In these cases, the scheduler lacks context
706 to be fair to multiple same-priority requests and/or ability to request lower
707 priority work to yield when high priority work comes in.
708
Etienne Pierre-doray6d3cd9192020-04-06 21:10:37709See [`base/task/job_perftest.cc`](https://cs.chromium.org/chromium/src/base/task/job_perftest.cc)
710for a complete example.
711
Etienne Pierre-dorayd3882992020-01-14 20:34:11712```cpp
713// A canonical implementation of |worker_task|.
714void WorkerTask(base::JobDelegate* job_delegate) {
715 while (!job_delegate->ShouldYield()) {
716 auto work_item = TakeWorkItem(); // Smallest unit of work.
717 if (!work_item)
718 return:
719 ProcessWork(work_item);
720 }
721}
722
723// Returns the latest thread-safe number of incomplete work items.
Etienne Pierre-Dorayf91d7a02020-09-11 15:53:27724void NumIncompleteWorkItems(size_t worker_count) {
725 // NumIncompleteWorkItems() may use |worker_count| if it needs to account for
726 // local work lists, which is easier than doing its own accounting, keeping in
727 // mind that the actual number of items may be racily overestimated and thus
728 // WorkerTask() may be called when there's no available work.
729 return GlobalQueueSize() + worker_count;
730}
Etienne Pierre-dorayd3882992020-01-14 20:34:11731
Gabriel Charette1138d602020-01-29 08:51:52732base::PostJob(FROM_HERE, {},
Etienne Pierre-dorayd3882992020-01-14 20:34:11733 base::BindRepeating(&WorkerTask),
734 base::BindRepeating(&NumIncompleteWorkItems));
735```
736
737By doing as much work as possible in a loop when invoked, the worker task avoids
738scheduling overhead. Meanwhile `base::JobDelegate::ShouldYield()` is
739periodically invoked to conditionally exit and let the scheduler prioritize
740other work. This yield-semantic allows, for example, a user-visible job to use
741all cores but get out of the way when a user-blocking task comes in.
742
Jared Saulea867ab2021-07-15 17:39:01743### Adding additional work to a running job
Etienne Pierre-dorayd3882992020-01-14 20:34:11744
745When new work items are added and the API user wants additional threads to
Albert J. Wongf06ff5002021-07-08 20:37:00746invoke the worker task in parallel,
Etienne Pierre-dorayd3882992020-01-14 20:34:11747`JobHandle/JobDelegate::NotifyConcurrencyIncrease()` *must* be invoked shortly
748after max concurrency increases.
749
fdoraybacba4a22017-05-10 21:10:00750## Testing
751
Gabriel Charette0b20ee62019-09-18 14:06:12752For more details see [Testing Components Which Post
753Tasks](threading_and_tasks_testing.md).
754
Sean Maher03efef12022-09-23 22:43:13755To test code that uses `base::SingleThreadTaskRunner::CurrentDefaultHandle`,
756`base::SequencedTaskRunner::CurrentDefaultHandle` or a function in
Gabriel Charette9b6c04072022-04-01 23:22:46757[`base/task/thread_pool.h`](https://cs.chromium.org/chromium/src/base/task/thread_pool.h),
Gabriel Charette39db4c62019-04-29 19:52:38758instantiate a
Gabriel Charette0b20ee62019-09-18 14:06:12759[`base::test::TaskEnvironment`](https://cs.chromium.org/chromium/src/base/test/task_environment.h)
Gabriel Charette39db4c62019-04-29 19:52:38760for the scope of the test. If you need BrowserThreads, use
Gabriel Charette798fde72019-08-20 22:24:04761`content::BrowserTaskEnvironment` instead of
Gabriel Charette694c3c332019-08-19 14:53:05762`base::test::TaskEnvironment`.
fdoraybacba4a22017-05-10 21:10:00763
Gabriel Charette694c3c332019-08-19 14:53:05764Tests can run the `base::test::TaskEnvironment`'s message pump using a
Gabriel Charette39db4c62019-04-29 19:52:38765`base::RunLoop`, which can be made to run until `Quit()` (explicitly or via
766`RunLoop::QuitClosure()`), or to `RunUntilIdle()` ready-to-run tasks and
767immediately return.
Wezd9e4cb772019-01-09 03:07:03768
Wez9d5dd282020-02-10 17:21:22769TaskEnvironment configures RunLoop::Run() to GTEST_FAIL() if it hasn't been
Wezd9e4cb772019-01-09 03:07:03770explicitly quit after TestTimeouts::action_timeout(). This is preferable to
771having the test hang if the code under test fails to trigger the RunLoop to
Wez9d5dd282020-02-10 17:21:22772quit. The timeout can be overridden with base::test::ScopedRunLoopTimeout.
Wezd9e4cb772019-01-09 03:07:03773
fdoraybacba4a22017-05-10 21:10:00774```cpp
775class MyTest : public testing::Test {
776 public:
777 // ...
778 protected:
Gabriel Charette694c3c332019-08-19 14:53:05779 base::test::TaskEnvironment task_environment_;
fdoraybacba4a22017-05-10 21:10:00780};
781
Xiaohan Wang5279ee02022-10-19 22:21:06782TEST_F(MyTest, FirstTest) {
Sean Maher03efef12022-09-23 22:43:13783 base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, base::BindOnce(&A));
784 base::SequencedTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE,
fdoraybacba4a22017-05-10 21:10:00785 base::BindOnce(&B));
Sean Maher03efef12022-09-23 22:43:13786 base::SingleThreadTaskRunner::GetCurrentDefault()->PostDelayedTask(
fdoraybacba4a22017-05-10 21:10:00787 FROM_HERE, base::BindOnce(&C), base::TimeDelta::Max());
788
Sean Maher03efef12022-09-23 22:43:13789 // This runs the (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue until it is empty.
fdoraybacba4a22017-05-10 21:10:00790 // Delayed tasks are not added to the queue until they are ripe for execution.
Gabriel Charettebd126bc32022-02-01 18:19:19791 // Prefer explicit exit conditions to RunUntilIdle when possible:
792 // bit.ly/run-until-idle-with-care2.
fdoraybacba4a22017-05-10 21:10:00793 base::RunLoop().RunUntilIdle();
794 // A and B have been executed. C is not ripe for execution yet.
795
796 base::RunLoop run_loop;
Sean Maher03efef12022-09-23 22:43:13797 base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, base::BindOnce(&D));
798 base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, run_loop.QuitClosure());
799 base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, base::BindOnce(&E));
fdoraybacba4a22017-05-10 21:10:00800
Sean Maher03efef12022-09-23 22:43:13801 // This runs the (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue until QuitClosure is
fdoraybacba4a22017-05-10 21:10:00802 // invoked.
803 run_loop.Run();
804 // D and run_loop.QuitClosure() have been executed. E is still in the queue.
805
Gabriel Charette52fa3ae2019-04-15 21:44:37806 // Tasks posted to thread pool run asynchronously as they are posted.
Gabriel Charette43de5c42020-01-27 22:44:45807 base::ThreadPool::PostTask(FROM_HERE, {}, base::BindOnce(&F));
fdoraybacba4a22017-05-10 21:10:00808 auto task_runner =
Gabriel Charette43de5c42020-01-27 22:44:45809 base::ThreadPool::CreateSequencedTaskRunner({});
fdoraybacba4a22017-05-10 21:10:00810 task_runner->PostTask(FROM_HERE, base::BindOnce(&G));
811
Gabriel Charette52fa3ae2019-04-15 21:44:37812 // To block until all tasks posted to thread pool are done running:
Gabriel Charette43fd3702019-05-29 16:36:51813 base::ThreadPoolInstance::Get()->FlushForTesting();
fdoraybacba4a22017-05-10 21:10:00814 // F and G have been executed.
815
Gabriel Charette43de5c42020-01-27 22:44:45816 base::ThreadPool::PostTaskAndReplyWithResult(
817 FROM_HERE, {}, base::BindOnce(&H), base::BindOnce(&I));
fdoraybacba4a22017-05-10 21:10:00818
Sean Maher03efef12022-09-23 22:43:13819 // This runs the (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue until both the
820 // (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue and the ThreadPool queue are
Gabriel Charettebd126bc32022-02-01 18:19:19821 // empty. Prefer explicit exit conditions to RunUntilIdle when possible:
822 // bit.ly/run-until-idle-with-care2.
Gabriel Charette694c3c332019-08-19 14:53:05823 task_environment_.RunUntilIdle();
fdoraybacba4a22017-05-10 21:10:00824 // E, H, I have been executed.
825}
826```
827
Gabriel Charette52fa3ae2019-04-15 21:44:37828## Using ThreadPool in a New Process
fdoraybacba4a22017-05-10 21:10:00829
Gabriel Charette43fd3702019-05-29 16:36:51830ThreadPoolInstance needs to be initialized in a process before the functions in
Gabriel Charette9b6c04072022-04-01 23:22:46831[`base/task/thread_pool.h`](https://cs.chromium.org/chromium/src/base/task/thread_pool.h)
Gabriel Charette43fd3702019-05-29 16:36:51832can be used. Initialization of ThreadPoolInstance in the Chrome browser process
833and child processes (renderer, GPU, utility) has already been taken care of. To
834use ThreadPoolInstance in another process, initialize ThreadPoolInstance early
835in the main function:
fdoraybacba4a22017-05-10 21:10:00836
837```cpp
Gabriel Charette43fd3702019-05-29 16:36:51838// This initializes and starts ThreadPoolInstance with default params.
Tommy Chiang207a9192024-01-03 16:55:46839base::ThreadPoolInstance::CreateAndStartWithDefaultParams("process_name");
Gabriel Charette9b6c04072022-04-01 23:22:46840// The base/task/thread_pool.h API can now be used with base::ThreadPool trait.
Jared Saulea867ab2021-07-15 17:39:01841// Tasks will be scheduled as they are posted.
fdoraybacba4a22017-05-10 21:10:00842
Gabriel Charette43fd3702019-05-29 16:36:51843// This initializes ThreadPoolInstance.
Tommy Chiang207a9192024-01-03 16:55:46844base::ThreadPoolInstance::Create("process_name");
Gabriel Charette9b6c04072022-04-01 23:22:46845// The base/task/thread_pool.h API can now be used with base::ThreadPool trait. No
Gabriel Charette43fd3702019-05-29 16:36:51846// threads will be created and no tasks will be scheduled until after Start() is
847// called.
848base::ThreadPoolInstance::Get()->Start(params);
Gabriel Charette52fa3ae2019-04-15 21:44:37849// ThreadPool can now create threads and schedule tasks.
fdoraybacba4a22017-05-10 21:10:00850```
851
Gabriel Charette43fd3702019-05-29 16:36:51852And shutdown ThreadPoolInstance late in the main function:
fdoraybacba4a22017-05-10 21:10:00853
854```cpp
Gabriel Charette43fd3702019-05-29 16:36:51855base::ThreadPoolInstance::Get()->Shutdown();
fdoraybacba4a22017-05-10 21:10:00856// Tasks posted with TaskShutdownBehavior::BLOCK_SHUTDOWN and
857// tasks posted with TaskShutdownBehavior::SKIP_ON_SHUTDOWN that
858// have started to run before the Shutdown() call have now completed their
859// execution. Tasks posted with
860// TaskShutdownBehavior::CONTINUE_ON_SHUTDOWN may still be
861// running.
862```
Gabriel Charetteb86e5fe62017-06-08 19:39:28863## TaskRunner ownership (encourage no dependency injection)
Sebastien Marchandc95489b2017-05-25 16:39:34864
865TaskRunners shouldn't be passed through several components. Instead, the
Jared Saulea867ab2021-07-15 17:39:01866component that uses a TaskRunner should be the one that creates it.
Sebastien Marchandc95489b2017-05-25 16:39:34867
868See [this example](https://codereview.chromium.org/2885173002/) of a
869refactoring where a TaskRunner was passed through a lot of components only to be
870used in an eventual leaf. The leaf can and should now obtain its TaskRunner
871directly from
Gabriel Charette9b6c04072022-04-01 23:22:46872[`base/task/thread_pool.h`](https://cs.chromium.org/chromium/src/base/task/thread_pool.h).
Gabriel Charetteb86e5fe62017-06-08 19:39:28873
Gabriel Charette694c3c332019-08-19 14:53:05874As mentioned above, `base::test::TaskEnvironment` allows unit tests to
Gabriel Charette39db4c62019-04-29 19:52:38875control tasks posted from underlying TaskRunners. In rare cases where a test
876needs to more precisely control task ordering: dependency injection of
877TaskRunners can be useful. For such cases the preferred approach is the
878following:
Gabriel Charetteb86e5fe62017-06-08 19:39:28879
880```cpp
Gabriel Charette39db4c62019-04-29 19:52:38881class Foo {
Gabriel Charetteb86e5fe62017-06-08 19:39:28882 public:
883
Gabriel Charette39db4c62019-04-29 19:52:38884 // Overrides |background_task_runner_| in tests.
Gabriel Charetteb86e5fe62017-06-08 19:39:28885 void SetBackgroundTaskRunnerForTesting(
Gabriel Charette39db4c62019-04-29 19:52:38886 scoped_refptr<base::SequencedTaskRunner> background_task_runner) {
887 background_task_runner_ = std::move(background_task_runner);
888 }
Gabriel Charetteb86e5fe62017-06-08 19:39:28889
890 private:
michaelpg12c04572017-06-26 23:25:06891 scoped_refptr<base::SequencedTaskRunner> background_task_runner_ =
Gabriel Charette43de5c42020-01-27 22:44:45892 base::ThreadPool::CreateSequencedTaskRunner(
Gabriel Charetteb10aeeb2018-07-26 20:15:00893 {base::MayBlock(), base::TaskPriority::BEST_EFFORT});
Gabriel Charetteb86e5fe62017-06-08 19:39:28894}
895```
896
897Note that this still allows removing all layers of plumbing between //chrome and
898that component since unit tests will use the leaf layer directly.
Gabriel Charette8917f4c2018-11-22 15:50:28899
900## FAQ
901See [Threading and Tasks FAQ](threading_and_tasks_faq.md) for more examples.
Gabriel Charette43de5c42020-01-27 22:44:45902
903[task APIs v3]: https://docs.google.com/document/d/1tssusPykvx3g0gvbvU4HxGyn3MjJlIylnsH13-Tv6s4/edit?ts=5de99a52#heading=h.ss4tw38hvh3s
Carlos Caballero40b6d042020-06-16 06:50:25904
905## Internals
906
907### SequenceManager
908
909[SequenceManager](https://cs.chromium.org/chromium/src/base/task/sequence_manager/sequence_manager.h)
910manages TaskQueues which have different properties (e.g. priority, common task
911type) multiplexing all posted tasks into a single backing sequence. This will
912usually be a MessagePump. Depending on the type of message pump used other
913events such as UI messages may be processed as well. On Windows APC calls (as
914time permits) and signals sent to a registered set of HANDLEs may also be
915processed.
916
Carlos Caballero4a050922020-07-02 11:43:38917### MessagePump
Carlos Caballero40b6d042020-06-16 06:50:25918
919[MessagePumps](https://cs.chromium.org/chromium/src/base/message_loop/message_pump.h)
920are responsible for processing native messages as well as for giving cycles to
921their delegate (SequenceManager) periodically. MessagePumps take care to mixing
922delegate callbacks with native message processing so neither type of event
923starves the other of cycles.
924
925There are different [MessagePumpTypes](https://cs.chromium.org/chromium/src/base/message_loop/message_pump_type.h),
926most common are:
927
928* DEFAULT: Supports tasks and timers only
929
930* UI: Supports native UI events (e.g. Windows messages)
931
932* IO: Supports asynchronous IO (not file I/O!)
933
934* CUSTOM: User provided implementation of MessagePump interface
935
Carlos Caballero4a050922020-07-02 11:43:38936### RunLoop
Carlos Caballero40b6d042020-06-16 06:50:25937
Jared Saulea867ab2021-07-15 17:39:01938RunLoop is a helper class to run the RunLoop::Delegate associated with the
Carlos Caballero40b6d042020-06-16 06:50:25939current thread (usually a SequenceManager). Create a RunLoop on the stack and
940call Run/Quit to run a nested RunLoop but please avoid nested loops in
941production code!
942
Carlos Caballero4a050922020-07-02 11:43:38943### Task Reentrancy
Carlos Caballero40b6d042020-06-16 06:50:25944
945SequenceManager has task reentrancy protection. This means that if a
946task is being processed, a second task cannot start until the first task is
947finished. Reentrancy can happen when processing a task, and an inner
948message pump is created. That inner pump then processes native messages
949which could implicitly start an inner task. Inner message pumps are created
950with dialogs (DialogBox), common dialogs (GetOpenFileName), OLE functions
951(DoDragDrop), printer functions (StartDoc) and *many* others.
952
953```cpp
954Sample workaround when inner task processing is needed:
955 HRESULT hr;
956 {
Francois Doraya06ee172022-11-24 21:09:18957 CurrentThread::ScopedAllowApplicationTasksInNativeNestedLoop allow;
Carlos Caballero40b6d042020-06-16 06:50:25958 hr = DoDragDrop(...); // Implicitly runs a modal message loop.
959 }
960 // Process |hr| (the result returned by DoDragDrop()).
961```
962
963Please be SURE your task is reentrant (nestable) and all global variables
Jack Hsieh6c96b72fc2024-04-18 23:10:28964are stable and accessible before using
Francois Doraya06ee172022-11-24 21:09:18965CurrentThread::ScopedAllowApplicationTasksInNativeNestedLoop.
Carlos Caballero40b6d042020-06-16 06:50:25966
967## APIs for general use
968
969User code should hardly ever need to access SequenceManager APIs directly as
970these are meant for code that deals with scheduling. Instead you should use the
971following:
972
973* base::RunLoop: Drive the SequenceManager from the thread it's bound to.
974
Sean Maher03efef12022-09-23 22:43:13975* base::Thread/SequencedTaskRunner::CurrentDefaultHandle: Post back to the SequenceManager TaskQueues from a task running on it.
Carlos Caballero40b6d042020-06-16 06:50:25976
977* SequenceLocalStorageSlot : Bind external state to a sequence.
978
Carlos Caballero4a050922020-07-02 11:43:38979* base::CurrentThread : Proxy to a subset of Task related APIs bound to the current thread
Carlos Caballero40b6d042020-06-16 06:50:25980
981* Embedders may provide their own static accessors to post tasks on specific loops (e.g. content::BrowserThreads).
982
983### SingleThreadTaskExecutor and TaskEnvironment
984
985Instead of having to deal with SequenceManager and TaskQueues code that needs a
986simple task posting environment (one default task queue) can use a
987[SingleThreadTaskExecutor](https://cs.chromium.org/chromium/src/base/task/single_thread_task_executor.h).
988
989Unit tests can use [TaskEnvironment](https://cs.chromium.org/chromium/src/base/test/task_environment.h)
990which is highly configurable.
Carlos Caballero4a050922020-07-02 11:43:38991
Wen Fane09439ca2021-03-09 16:50:41992## MessageLoop and MessageLoopCurrent
Carlos Caballero4a050922020-07-02 11:43:38993
Wen Fane09439ca2021-03-09 16:50:41994You might come across references to MessageLoop or MessageLoopCurrent in the
Carlos Caballero4a050922020-07-02 11:43:38995code or documentation. These classes no longer exist and we are in the process
Jared Saulea867ab2021-07-15 17:39:01996or getting rid of all references to them. `base::MessageLoopCurrent` was
997replaced by `base::CurrentThread` and the drop in replacements for
998`base::MessageLoop` are `base::SingleThreadTaskExecutor` and
999`base::Test::TaskEnvironment`.