diff --git a/DEPS b/DEPS index 8c878ca673..70c38642e3 100644 --- a/DEPS +++ b/DEPS @@ -1043,7 +1043,7 @@ include_rules = [ "+test", "+rtc_tools", - # Abseil whitelist. + # Abseil whitelist. Keep this in sync with abseil-in-webrtc-md. "+absl/container/inlined_vector.h", "+absl/memory/memory.h", "+absl/strings/string_view.h", diff --git a/OWNERS b/OWNERS index 587f727e4d..bfa7801bd8 100644 --- a/OWNERS +++ b/OWNERS @@ -18,6 +18,9 @@ per-file pylintrc=phoglund@webrtc.org per-file THIRD_PARTY_DEPS=phoglund@webrtc.org per-file THIRD_PARTY_DEPS=titovartem@webrtc.org per-file WATCHLISTS=* +per-file abseil-in-webrtc.md=danilchap@webrtc.org +per-file abseil-in-webrtc.md=kwiberg@webrtc.org +per-file abseil-in-webrtc.md=mbonadei@webrtc.org per-file style-guide.md=danilchap@webrtc.org per-file style-guide.md=kwiberg@webrtc.org per-file native-api.md=kwiberg@webrtc.org diff --git a/abseil-in-webrtc.md b/abseil-in-webrtc.md new file mode 100644 index 0000000000..04ae8d28de --- /dev/null +++ b/abseil-in-webrtc.md @@ -0,0 +1,50 @@ +# Using Abseil in WebRTC + +You may use a subset of the utilities provided by the [Abseil][abseil] +library when writing WebRTC C++ code. Below, we list the explicitly +*allowed* and the explicitly *disallowed* subsets of Abseil; if you +find yourself in need of something that isn’t in either subset, +please add it to the *allowed* subset in this doc in the same CL that +adds the first use. + +[abseil]: https://abseil.io/about/ + +## **Allowed** + +* `absl::InlinedVector` +* `absl::make_unique` and `absl::WrapUnique` +* `absl::optional` and related stuff from `absl/types/optional.h`. +* `absl::string_view` +* `absl::variant` and related stuff from `absl/types/variant.h`. + +## **Disallowed** + +### `absl::Mutex` + +*Use `rtc::CriticalSection` instead.* + +Chromium has a ban on new static initializers, and `absl::Mutex` uses +one. To make `absl::Mutex` available, we would need to nicely ask the +Abseil team to remove that initializer (like they already did for a +spinlock initializer). Additionally, `absl::Mutex` handles time in a +way that may not be compaible with the rest of WebRTC. + +### `absl::Span` + +*Use `rtc::ArrayView` instead.* + +`absl::Span` differs from `rtc::ArrayView` on several points, and both +of them differ from the `std::span` that was voted into +C++20—and `std::span` is likely to undergo further changes +before C++20 is finalized. We should just keep using `rtc::ArrayView` +and avoid `absl::Span` until C++20 is finalized and the Abseil team +has decided if they will change `absl::Span` to match. +[Bug](https://bugs.webrtc.org/9214). + +### `absl::StrCat` and `absl::StrAppend` + +*Use `rtc::SimpleStringBuilder` instead.* + +These are optimized for speed, not binary size. Even `StrCat` calls +with a modest number of arguments can easily add several hundred bytes +to the binary. diff --git a/style-guide.md b/style-guide.md index 50f45fc6e8..2a35fdc5d1 100644 --- a/style-guide.md +++ b/style-guide.md @@ -31,6 +31,13 @@ WebRTC is written in C++11, but with some restrictions: [chromium-cpp11]: https://chromium-cpp.appspot.com/ +### Abseil + +You may use a subset of the utilities provided by the [Abseil][abseil] +library when writing WebRTC C++ code. [Details](abseil-in-webrtc.md). + +[abseil]: https://abseil.io/about/ + ### `.h` and `.cc` files come in pairs `.h` and `.cc` files should come in pairs, with the same name (except