Task Posting v3: migrate (Sequenced|Thread)TaskRunnerHandle
To migrate to v3 task posting API, this CL moves moves
(Sequenced|Thread)TaskRunnerHandle::Get() to
(Sequenced|SingleThread)TaskRunner::GetCurrentDefault()
and related classes. For more detail on this migration, refer to
https://docs.google.com/document/d/1tssusPykvx3g0gvbvU4HxGyn3MjJlIylnsH13-Tv6s4/edit#bookmark=id.1umyn7v5a4p
The blink codebase's presubmits were substantially changed. This was
done because the presubmit did not parse in-class identifiers, and so
there was no way of banning inner classes/methods/identifiers of a
class which is allowed.
The reason this was needed for this CL is that
base::(Sequenced|SingleThread)TaskRunners are permitted in blink, but
we need to ban (Sequenced|SingleThread)TaskRunner::GetCurrentDefault()
and [...]::CurrentDefaultHandle to ensure that tasks in blink remain
properly labeled.
To this end, a new type of identifier (in-class identifiers, such as
nested::namespace::ClassName::EnumClassName) is parsed by the
presubmit, and a new kind of rule can be added to the _CONFIG file to
allow/deny them. They are parsed very similarly to the existing
identifiers, but crucially, they are allowed by default, whereas
ClassNames are denied by default.
In addition, the tests for the presubmit were mostly rewritten to
properly test whether the identifiers in the test are actually
allowed/disallowed. Instead of simply testing to see whether an
identifier is present in _CONFIG in the presubmit file, the
presubmit's functions are called in the same way as happens during the
presubmit to make sure the code being run actually works.
Finally, it also tests that the identifiers tested are fully parsed
(a handful of them weren't because they were either preceded by '::'
or in-class) by the presubmit.
The task runner handle classes still exist in the codebase, and no
existing Chromium code has been modified, as semantics have been
preserved despite the implementation change.
The implementation migration will then take place in future CLs.
Because the two APIs expose the same functionality, the codebase
can be incrementally migrated.
Bug: 1026641
Change-Id: I7ea7bb36f30ecd3cdefedcffd8bae16118b0f3d2
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3804911
Reviewed-by: Francois Pierre Doray <[email protected]>
Commit-Queue: Sean Maher <[email protected]>
Reviewed-by: Daniel Cheng <[email protected]>
Reviewed-by: Gabriel Charette <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1050813}
diff --git a/docs/threading_and_tasks.md b/docs/threading_and_tasks.md
index 0871f5c..71f75eb 100644
--- a/docs/threading_and_tasks.md
+++ b/docs/threading_and_tasks.md
@@ -176,8 +176,8 @@
thread-affinity checks (e.g., `THREAD_CHECKER`) in a leaf dependency: consider
making that dependency sequence-friendly as well. Most core APIs in Chrome are
sequence-friendly, but some legacy types may still over-zealously use
-ThreadChecker/ThreadTaskRunnerHandle/SingleThreadTaskRunner when they could
-instead rely on the "current sequence" and no longer be thread-affine.
+ThreadChecker/SingleThreadTaskRunner when they could instead rely on the
+"current sequence" and no longer be thread-affine.
## Posting a Parallel Task
@@ -263,20 +263,21 @@
### Posting to the Current (Virtual) Thread
The preferred way of posting to the current (virtual) thread is via
-`base::SequencedTaskRunnerHandle::Get()`.
+`base::SequencedTaskRunner::GetCurrentDefault()`.
```cpp
// The task will run on the current (virtual) thread's default task queue.
-base::SequencedTaskRunnerHandle::Get()->PostTask(
+base::SequencedTaskRunner::GetCurrentDefault()->PostTask(
FROM_HERE, base::BindOnce(&Task);
```
-Note that `SequencedTaskRunnerHandle::Get()` returns the default queue for the
+Note that `SequencedTaskRunner::GetCurrentDefault()` returns the default queue for the
current virtual thread. On threads with multiple task queues (e.g.
BrowserThread::UI) this can be a different queue than the one the current task
belongs to. The "current" task runner is intentionally not exposed via a static
getter. Either you know it already and can post to it directly or you don't and
-the only sensible destination is the default queue.
+the only sensible destination is the default queue. See https://bit.ly/3JvCLsX
+for detailed discussion.
## Using Sequences Instead of Locks
@@ -413,21 +414,21 @@
*** note
**IMPORTANT:** To post a task that needs mutual exclusion with the current
sequence of tasks but doesn’t absolutely need to run on the current physical
-thread, use `base::SequencedTaskRunnerHandle::Get()` instead of
-`base::ThreadTaskRunnerHandle::Get()` (ref. [Posting to the Current
+thread, use `base::SequencedTaskRunner::GetCurrentDefault()` instead of
+`base::SingleThreadTaskRunner::GetCurrentDefault()` (ref. [Posting to the Current
Sequence](#Posting-to-the-Current-Virtual_Thread)). That will better document
the requirements of the posted task and will avoid unnecessarily making your API
physical thread-affine. In a single-thread task,
-`base::SequencedTaskRunnerHandle::Get()` is equivalent to
-`base::ThreadTaskRunnerHandle::Get()`.
+`base::SequencedTaskRunner::GetCurrentDefault()` is equivalent to
+`base::SingleThreadTaskRunner::GetCurrentDefault()`.
***
If you must post a task to the current physical thread nonetheless, use
-[`base::ThreadTaskRunnerHandle`](https://cs.chromium.org/chromium/src/base/threading/thread_task_runner_handle.h).
+[`base::SingleThreadTaskRunner::CurrentDefaultHandle`](https://source.chromium.org/chromium/chromium/src/+/main:base/task/single_thread_task_runner.h).
```cpp
// The task will run on the current thread in the future.
-base::ThreadTaskRunnerHandle::Get()->PostTask(
+base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(
FROM_HERE, base::BindOnce(&Task));
```
@@ -450,7 +451,7 @@
// ...
// Post another task to the current COM STA thread.
- base::ThreadTaskRunnerHandle::Get()->PostTask(
+ base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(
FROM_HERE, base::BindOnce(&TaskCUsingCOMSTA));
}
void TaskBUsingCOMSTA() { }
@@ -700,8 +701,8 @@
For more details see [Testing Components Which Post
Tasks](threading_and_tasks_testing.md).
-To test code that uses `base::ThreadTaskRunnerHandle`,
-`base::SequencedTaskRunnerHandle` or a function in
+To test code that uses `base::SingleThreadTaskRunner::CurrentDefaultHandle`,
+`base::SequencedTaskRunner::CurrentDefaultHandle` or a function in
[`base/task/thread_pool.h`](https://cs.chromium.org/chromium/src/base/task/thread_pool.h),
instantiate a
[`base::test::TaskEnvironment`](https://cs.chromium.org/chromium/src/base/test/task_environment.h)
@@ -728,13 +729,13 @@
};
TEST(MyTest, MyTest) {
- base::ThreadTaskRunnerHandle::Get()->PostTask(FROM_HERE, base::BindOnce(&A));
- base::SequencedTaskRunnerHandle::Get()->PostTask(FROM_HERE,
+ base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, base::BindOnce(&A));
+ base::SequencedTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE,
base::BindOnce(&B));
- base::ThreadTaskRunnerHandle::Get()->PostDelayedTask(
+ base::SingleThreadTaskRunner::GetCurrentDefault()->PostDelayedTask(
FROM_HERE, base::BindOnce(&C), base::TimeDelta::Max());
- // This runs the (Thread|Sequenced)TaskRunnerHandle queue until it is empty.
+ // This runs the (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue until it is empty.
// Delayed tasks are not added to the queue until they are ripe for execution.
// Prefer explicit exit conditions to RunUntilIdle when possible:
// bit.ly/run-until-idle-with-care2.
@@ -742,11 +743,11 @@
// A and B have been executed. C is not ripe for execution yet.
base::RunLoop run_loop;
- base::ThreadTaskRunnerHandle::Get()->PostTask(FROM_HERE, base::BindOnce(&D));
- base::ThreadTaskRunnerHandle::Get()->PostTask(FROM_HERE, run_loop.QuitClosure());
- base::ThreadTaskRunnerHandle::Get()->PostTask(FROM_HERE, base::BindOnce(&E));
+ base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, base::BindOnce(&D));
+ base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, run_loop.QuitClosure());
+ base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE, base::BindOnce(&E));
- // This runs the (Thread|Sequenced)TaskRunnerHandle queue until QuitClosure is
+ // This runs the (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue until QuitClosure is
// invoked.
run_loop.Run();
// D and run_loop.QuitClosure() have been executed. E is still in the queue.
@@ -764,8 +765,8 @@
base::ThreadPool::PostTaskAndReplyWithResult(
FROM_HERE, {}, base::BindOnce(&H), base::BindOnce(&I));
- // This runs the (Thread|Sequenced)TaskRunnerHandle queue until both the
- // (Thread|Sequenced)TaskRunnerHandle queue and the ThreadPool queue are
+ // This runs the (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue until both the
+ // (SingleThread|Sequenced)TaskRunner::CurrentDefaultHandle queue and the ThreadPool queue are
// empty. Prefer explicit exit conditions to RunUntilIdle when possible:
// bit.ly/run-until-idle-with-care2.
task_environment_.RunUntilIdle();
@@ -920,7 +921,7 @@
* base::RunLoop: Drive the SequenceManager from the thread it's bound to.
-* base::Thread/SequencedTaskRunnerHandle: Post back to the SequenceManager TaskQueues from a task running on it.
+* base::Thread/SequencedTaskRunner::CurrentDefaultHandle: Post back to the SequenceManager TaskQueues from a task running on it.
* SequenceLocalStorageSlot : Bind external state to a sequence.
diff --git a/docs/threading_and_tasks_testing.md b/docs/threading_and_tasks_testing.md
index d66722ff..537c0879 100644
--- a/docs/threading_and_tasks_testing.md
+++ b/docs/threading_and_tasks_testing.md
@@ -40,10 +40,10 @@
### base::test::SingleThreadTaskEnvironment
-Your component uses `base::ThreadTaskRunnerHandle::Get()` or
-`base::SequencedTaskRunnerHandle::Get()` to post tasks to the thread it was
-created on? You'll need at least a `base::test::SingleThreadTaskEnvironment` in
-order for these APIs to be functional and `base::RunLoop` to run the posted
+Your component uses `base::SingleThreadTaskRunner::GetCurrentDefault()` or
+`base::SequencedTaskRunner::GetCurrentDefault()` to post tasks to the thread it
+was created on? You'll need at least a `base::test::SingleThreadTaskEnvironment`
+in order for these APIs to be functional and `base::RunLoop` to run the posted
tasks.
Typically this will look something like this:
@@ -52,7 +52,7 @@
```c++
class Foo {
public:
- Foo() : owning_sequence_(base::SequencedTaskRunnerHandle::Get()) {}
+ Foo() : owning_sequence_(base::SequencedTaskRunner::GetCurrentDefault()) {}
DoSomethingAndReply(base::OnceClosure on_done) {
DCHECK(owning_sequence_->RunsTasksInCurrentSequence());
