chromium/src
0
Fork 0
Code Activity

Update documentation for threading

Browse Source 
Change-Id: I8b57c8720889a9dc654798c4d45245568092ddbf
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5795356
Reviewed-by: Daniel Cheng <dcheng@chromium.org>
Commit-Queue: Erik Chen <erikchen@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1343929}
This commit is contained in:
Erik Chen
2024-08-20 04:45:57 +00:00
committed by Chromium LUCI CQ
parent 78afbdd6be
commit 4676e2f407
1 changed files with 17 additions and 12 deletions

29
docs/threading_and_tasks.md

@ -35,19 +35,24 @@ This documentation assumes familiarity with computer science
[data races](https://en.wikipedia.org/wiki/Race_condition#Data_race)!
Prefer passing messages across sequences instead. Alternatives to message
passing like using locks is discouraged.
* To prevent accidental data races, prefer for most classes to be used
exclusively on a single sequence. You should use utilities like
[SEQUENCE_CHECKER](https://source.chromium.org/chromium/chromium/src/+/main:base/sequence_checker.h)
or [base::SequenceBound](https://source.chromium.org/chromium/chromium/src/+/main:base/threading/sequence_bound.h)
to help enforce this constraint.
* If you need to orchestrate multiple objects that live on different
sequences, be careful about object lifetimes. For example,
using [base::Unretained](https://source.chromium.org/chromium/chromium/src/+/main:base/functional/bind.h;l=169;drc=ef1375f2c9fffa0d9cd664b43b0035c09fb70e99)
in posted tasks can often lead to use-after-free bugs without careful
analysis of object lifetimes. Consider whether you need to use
[weak pointers](https://source.chromium.org/chromium/chromium/src/+/main:base/memory/weak_ptr.h)
or [scoped refptrs](https://source.chromium.org/chromium/chromium/src/+/main:base/memory/scoped_refptr.h)
instead.
sequences, be careful about object lifetimes.
* To prevent accidental data races, prefer for most classes to be used
exclusively on a single sequence. You should use utilities like
[SEQUENCE_CHECKER][4] or [base::SequenceBound][5] to help enforce this
constraint.
* As a rule of thumb, avoid [base::Unretained][1]. [weak pointers][2] can
usually be substituted.
* Explicit ownership via `std::unique_ptr` is preferred.
* [scoped_refptrs][3] can be used for objects that have multiple owners
across multiple sequences. This is usually the wrong design pattern and is
discouraged for new code.
[1]: https://source.chromium.org/chromium/chromium/src/+/main:base/functional/bind.h;l=169;drc=ef1375f2c9fffa0d9cd664b43b0035c09fb70e99
[2]: https://source.chromium.org/chromium/chromium/src/+/main:base/memory/weak_ptr.h
[3]: https://source.chromium.org/chromium/chromium/src/+/main:base/memory/scoped_refptr.h
[4]: https://source.chromium.org/chromium/chromium/src/+/main:base/sequence_checker.h
[5]: https://source.chromium.org/chromium/chromium/src/+/main:base/threading/sequence_bound.h
### Nomenclature