Commit 338d61c1 authored by Etienne Pierre-doray's avatar Etienne Pierre-doray Committed by Commit Bot

Reland "[TaskScheduler]: Add section to faq: when to annotate with ScopedBlockingCall."

This is a reland of 8aeb9cc9

Original change's description:
> [TaskScheduler]: Add section to faq: when to annotate with ScopedBlockingCall.
> 
> Developpers are often wondering whether or not ScopedBlockingCall is redundant.
> 
> Change-Id: Ic7936ef805f43f7fc02d0ad3020c31d8364b099d
> Reviewed-on: https://chromium-review.googlesource.com/c/1271878
> Commit-Queue: Etienne Pierre-Doray <etiennep@chromium.org>
> Reviewed-by: François Doray <fdoray@chromium.org>
> Cr-Commit-Position: refs/heads/master@{#599626}

Change-Id: I0850821994e3b4a1b0c3bb238725bc28867d18f5
Reviewed-on: https://chromium-review.googlesource.com/c/1280281
Commit-Queue: Etienne Pierre-Doray <etiennep@chromium.org>
Reviewed-by: default avatarGabriel Charette <gab@chromium.org>
Cr-Commit-Position: refs/heads/master@{#599952}
parent f3dc8923
...@@ -70,10 +70,49 @@ If the task runs on a `DEDICATED SingleThreadTaskRunner`: ...@@ -70,10 +70,49 @@ If the task runs on a `DEDICATED SingleThreadTaskRunner`:
`DEDICATED SingleThreadTaskRunner` won't run until your blocking task returns `DEDICATED SingleThreadTaskRunner` won't run until your blocking task returns
(they will never run if the blocking task never returns). (they will never run if the blocking task never returns).
`[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h)` [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 off-CPU blocking operations. examples of off-CPU blocking operations.
### 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
[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).
As such, it is permitted to add a ScopedBlockingCall in the scope where a function
that is already annotated is called for documentation purposes.:
```cpp
Data GetDataFromNetwork() {
ScopedBlockingCall scoped_blocking_call(BlockingType::MAY_BLOCK);
// Fetch data from network.
...
return data;
}
void ProcessDataFromNetwork() {
Data data;
{
// Document the blocking behavior with a ScopedBlockingCall.
// Permitted, but not required since GetDataFromNetwork() is itself annotated.
ScopedBlockingCall scoped_blocking_call(BlockingType::MAY_BLOCK);
data = GetDataFromNetwork();
}
CPUIntensiveProcessing(data);
}
```
However, CPU usage should always be minimal within the scope of
`ScopedBlockingCall`. See
[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h).
## Sequences ## Sequences
### How to migrate from SingleThreadTaskRunner to SequencedTaskRunner? ### How to migrate from SingleThreadTaskRunner to SequencedTaskRunner?
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment