Threading and tasks doc update; typo/etc. fixes
Change-Id: I733a44bf598192ffef193f9732e468147f146970 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3027543 Commit-Queue: Jared Saul <jsaul@google.com> Reviewed-by: Etienne Pierre-Doray <etiennep@chromium.org> Cr-Commit-Position: refs/heads/master@{#902021}
This commit is contained in:
Jared Saul
committed by
Chromium LUCI CQ
Chromium LUCI CQ
parent
faf6ec6c4b
commit
ea867ab3df
@ -20,8 +20,8 @@ between threads. We discourage locking and thread-safe objects. Instead, objects
|
||||
live on only one (often virtual -- we'll get to that later!) thread and we pass
|
||||
messages between those threads for communication. Absent external requirements
|
||||
about latency or workload, Chrome attempts to be a [highly concurrent, but not
|
||||
necessarily parallel](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.)
|
||||
, system.
|
||||
necessarily parallel](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.),
|
||||
system.
|
||||
|
||||
This documentation assumes familiarity with computer science
|
||||
[threading concepts](https://en.wikipedia.org/wiki/Thread_(computing)).
|
||||
@ -261,7 +261,7 @@ base::SequencedTaskRunnerHandle::Get()->PostTask(
|
||||
FROM_HERE, base::BindOnce(&Task);
|
||||
```
|
||||
|
||||
Note that SequencedTaskRunnerHandle::Get() returns the default queue for the
|
||||
Note that `SequencedTaskRunnerHandle::Get()` 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
|
||||
@ -678,7 +678,7 @@ periodically invoked to conditionally exit and let the scheduler prioritize
|
||||
other work. This yield-semantic allows, for example, a user-visible job to use
|
||||
all cores but get out of the way when a user-blocking task comes in.
|
||||
|
||||
### Adding additional work to a running job.
|
||||
### Adding additional work to a running job
|
||||
|
||||
When new work items are added and the API user wants additional threads to
|
||||
invoke the worker task in parallel,
|
||||
@ -773,7 +773,7 @@ in the main function:
|
||||
// This initializes and starts ThreadPoolInstance with default params.
|
||||
base::ThreadPoolInstance::CreateAndStartWithDefaultParams(“process_name”);
|
||||
// The base/task/post_task.h API can now be used with base::ThreadPool trait.
|
||||
// Tasks will be // scheduled as they are posted.
|
||||
// Tasks will be scheduled as they are posted.
|
||||
|
||||
// This initializes ThreadPoolInstance.
|
||||
base::ThreadPoolInstance::Create(“process_name”);
|
||||
@ -798,7 +798,7 @@ base::ThreadPoolInstance::Get()->Shutdown();
|
||||
## TaskRunner ownership (encourage no dependency injection)
|
||||
|
||||
TaskRunners shouldn't be passed through several components. Instead, the
|
||||
components that uses a TaskRunner should be the one that creates it.
|
||||
component that uses a TaskRunner should be the one that creates it.
|
||||
|
||||
See [this example](https://codereview.chromium.org/2885173002/) of a
|
||||
refactoring where a TaskRunner was passed through a lot of components only to be
|
||||
@ -870,7 +870,7 @@ most common are:
|
||||
|
||||
### RunLoop
|
||||
|
||||
RunLoop is s helper class to run the RunLoop::Delegate associated with the
|
||||
RunLoop is a helper class to run the RunLoop::Delegate associated with the
|
||||
current thread (usually a SequenceManager). Create a RunLoop on the stack and
|
||||
call Run/Quit to run a nested RunLoop but please avoid nested loops in
|
||||
production code!
|
||||
@ -928,6 +928,7 @@ which is highly configurable.
|
||||
|
||||
You might come across references to MessageLoop or MessageLoopCurrent in the
|
||||
code or documentation. These classes no longer exist and we are in the process
|
||||
or getting rid of all references to them. base::MessageLoopCurrent was replaced
|
||||
by base::CurrentThread and the drop in replacements for base::MessageLoop are
|
||||
base::SingleThreadTaskExecutor and base::Test::TaskEnvironment.
|
||||
or getting rid of all references to them. `base::MessageLoopCurrent` was
|
||||
replaced by `base::CurrentThread` and the drop in replacements for
|
||||
`base::MessageLoop` are `base::SingleThreadTaskExecutor` and
|
||||
`base::Test::TaskEnvironment`.
|
||||
|
||||
@ -21,14 +21,14 @@ A task is posted through the `base/task/post_task.h` API with `TaskTraits`.
|
||||
* If the task is posted through a `SingleThreadTaskRunner` obtained from
|
||||
`CreateSingleThreadTaskRunner(..., mode)`:
|
||||
* Where `mode` is `SingleThreadTaskRunnerThreadMode::DEDICATED`:
|
||||
* The task runs on a thread that only runs tasks from that
|
||||
SingleThreadTaskRunner. This is not the main thread nor the IO
|
||||
thread.
|
||||
* The task runs on a thread that only runs tasks from that
|
||||
SingleThreadTaskRunner. This is not the main thread nor the IO
|
||||
thread.
|
||||
|
||||
* Where `mode` is `SingleThreadTaskRunnerThreadMode::SHARED`:
|
||||
* The task runs on a thread that runs tasks from one or many
|
||||
unrelated SingleThreadTaskRunners. This is not the main thread
|
||||
nor the IO thread.
|
||||
* The task runs on a thread that runs tasks from one or many
|
||||
unrelated SingleThreadTaskRunners. This is not the main thread nor
|
||||
the IO thread.
|
||||
|
||||
* Otherwise:
|
||||
* The task runs in a thread pool.
|
||||
@ -85,7 +85,7 @@ If the task runs on a `DEDICATED SingleThreadTaskRunner`:
|
||||
returns).
|
||||
|
||||
[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h)
|
||||
explains the difference between `MAY_BLOCK ` and `WILL_BLOCK` and gives
|
||||
explains the difference between `MAY_BLOCK` and `WILL_BLOCK` and gives
|
||||
examples of blocking operations.
|
||||
|
||||
### How to make a blocking call that may never return without preventing other tasks from being scheduled?
|
||||
@ -104,15 +104,15 @@ such tasks at which point sequencing can be a useful tool to prevent flooding).
|
||||
|
||||
### Do calls to blocking //base APIs need to be annotated with ScopedBlockingCall?
|
||||
|
||||
No. All blocking //base APIs (e.g. base::ReadFileToString, base::File::Read,
|
||||
base::SysInfo::AmountOfFreeDiskSpace, base::WaitableEvent::Wait, etc.) have their
|
||||
own internal annotations. See
|
||||
No. All blocking //base APIs (e.g. `base::ReadFileToString`, `base::File::Read`,
|
||||
`base::SysInfo::AmountOfFreeDiskSpace`, `base::WaitableEvent::Wait`, etc.) have
|
||||
their own internal annotations. See
|
||||
[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h).
|
||||
|
||||
### Can multiple ScopedBlockingCall be nested for the purpose of documentation?
|
||||
|
||||
Nested `ScopedBlockingCall` are supported. Most of the time, the inner
|
||||
ScopedBlockingCalls will no-op (the exception is WILL_BLOCK nested in MAY_BLOCK).
|
||||
ScopedBlockingCalls will no-op (the exception is `WILL_BLOCK` nested in `MAY_BLOCK`).
|
||||
As such, it is permitted to add a ScopedBlockingCall in the scope where a function
|
||||
that is already annotated is called for documentation purposes.:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user