Update documentation for threading
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:

committed by
Chromium LUCI CQ

parent
78afbdd6be
commit
4676e2f407
@ -35,19 +35,24 @@ This documentation assumes familiarity with computer science
|
|||||||
[data races](https://en.wikipedia.org/wiki/Race_condition#Data_race)!
|
[data races](https://en.wikipedia.org/wiki/Race_condition#Data_race)!
|
||||||
Prefer passing messages across sequences instead. Alternatives to message
|
Prefer passing messages across sequences instead. Alternatives to message
|
||||||
passing like using locks is discouraged.
|
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
|
* If you need to orchestrate multiple objects that live on different
|
||||||
sequences, be careful about object lifetimes. For example,
|
sequences, be careful about object lifetimes.
|
||||||
using [base::Unretained](https://source.chromium.org/chromium/chromium/src/+/main:base/functional/bind.h;l=169;drc=ef1375f2c9fffa0d9cd664b43b0035c09fb70e99)
|
* To prevent accidental data races, prefer for most classes to be used
|
||||||
in posted tasks can often lead to use-after-free bugs without careful
|
exclusively on a single sequence. You should use utilities like
|
||||||
analysis of object lifetimes. Consider whether you need to use
|
[SEQUENCE_CHECKER][4] or [base::SequenceBound][5] to help enforce this
|
||||||
[weak pointers](https://source.chromium.org/chromium/chromium/src/+/main:base/memory/weak_ptr.h)
|
constraint.
|
||||||
or [scoped refptrs](https://source.chromium.org/chromium/chromium/src/+/main:base/memory/scoped_refptr.h)
|
* As a rule of thumb, avoid [base::Unretained][1]. [weak pointers][2] can
|
||||||
instead.
|
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
|
### Nomenclature
|
||||||
|
|
||||||
|
Reference in New Issue
Block a user