Artem Titov | a617867 | 2023-01-30 10:51:01 | [diff] [blame] | 1 | <!-- go/cmark --> |
Danil Chapovalov | 04ab497 | 2024-09-02 16:23:21 | [diff] [blame] | 2 | <!--* freshness: {owner: 'danilchap' reviewed: '2024-09-02'} *--> |
Danil Chapovalov | 46f5c11 | 2021-05-12 12:05:48 | [diff] [blame] | 3 | |
Artem Titov | a617867 | 2023-01-30 10:51:01 | [diff] [blame] | 4 | # Using Abseil in WebRTC |
Artem Titov | 0f2ce5c | 2023-01-26 20:18:46 | [diff] [blame] | 5 | |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 6 | You may use a subset of the utilities provided by the [Abseil][abseil] |
| 7 | library when writing WebRTC C++ code. Below, we list the explicitly |
| 8 | *allowed* and the explicitly *disallowed* subsets of Abseil; if you |
| 9 | find yourself in need of something that isn’t in either subset, |
| 10 | please add it to the *allowed* subset in this doc in the same CL that |
| 11 | adds the first use. |
| 12 | |
| 13 | [abseil]: https://abseil.io/about/ |
| 14 | |
Karl Wiberg | a667f87 | 2020-10-15 23:02:37 | [diff] [blame] | 15 | |
| 16 | ## How to depend on Abseil |
| 17 | |
| 18 | For build targets of type `rtc_library`, `rtc_source_set` and |
Florent Castelli | ae5d503 | 2024-05-27 10:19:05 | [diff] [blame] | 19 | `rtc_static_library`, dependencies on Abseil need to be listed in `deps`. |
Karl Wiberg | a667f87 | 2020-10-15 23:02:37 | [diff] [blame] | 20 | |
Florent Castelli | ae5d503 | 2024-05-27 10:19:05 | [diff] [blame] | 21 | The GN templates will take care of generating the proper dependency when |
| 22 | used within Chromium or standalone. In that build mode, WebRTC will depend |
| 23 | on a monolithic Abseil build target that will generate a shared library. |
| 24 | |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 25 | ## **Allowed** |
| 26 | |
Danil Chapovalov | 4b97928 | 2022-06-30 08:08:47 | [diff] [blame] | 27 | * `absl::AnyInvocable` |
Per Kjellander | fe2063e | 2021-05-12 07:02:43 | [diff] [blame] | 28 | * `absl::bind_front` |
Danil Chapovalov | e610610 | 2022-02-16 11:29:02 | [diff] [blame] | 29 | * `absl::Cleanup` |
Danil Chapovalov | d004aee | 2024-12-09 17:09:53 | [diff] [blame] | 30 | * [Hash tables, and B-tree ordered][abseil-containers] containers |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 31 | * `absl::InlinedVector` |
Tommi | fd3b346 | 2023-10-27 20:38:33 | [diff] [blame] | 32 | * `absl::Nonnull` and `absl::Nullable` |
Mirko Bonadei | c128df1 | 2019-09-18 05:59:07 | [diff] [blame] | 33 | * `absl::WrapUnique` |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 34 | * `absl::string_view` |
Steve Anton | 1c9c9fc | 2019-02-14 23:13:09 | [diff] [blame] | 35 | * The functions in `absl/strings/ascii.h`, `absl/strings/match.h`, |
| 36 | and `absl/strings/str_replace.h`. |
Harald Alvestrand | 666c333 | 2022-10-18 12:32:40 | [diff] [blame] | 37 | * The functions in `absl/strings/escaping.h`. |
Jiawei Ou | a6e034a | 2018-11-25 04:59:41 | [diff] [blame] | 38 | * `absl::is_trivially_copy_constructible`, |
| 39 | `absl::is_trivially_copy_assignable`, and |
| 40 | `absl::is_trivially_destructible` from `absl/meta/type_traits.h`. |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 41 | * `absl::variant` and related stuff from `absl/types/variant.h`. |
Steve Anton | e76ca61 | 2019-01-25 20:49:14 | [diff] [blame] | 42 | * The functions in `absl/algorithm/algorithm.h` and |
Elad Alon | e86af2c | 2019-06-03 12:37:50 | [diff] [blame] | 43 | `absl/algorithm/container.h`. |
Markus Handell | f70fbc8 | 2020-06-03 22:41:20 | [diff] [blame] | 44 | * `absl/base/const_init.h` for mutex initialization. |
Elad Alon | e86af2c | 2019-06-03 12:37:50 | [diff] [blame] | 45 | * The macros in `absl/base/attributes.h`, `absl/base/config.h` and |
| 46 | `absl/base/macros.h`. |
Danil Chapovalov | 09fb787 | 2021-08-20 10:46:14 | [diff] [blame] | 47 | * `absl/numeric/bits.h` |
Harald Alvestrand | aaaeb29 | 2024-10-31 13:49:39 | [diff] [blame] | 48 | * Single argument absl::StrCat |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 49 | |
Danil Chapovalov | 04ab497 | 2024-09-02 16:23:21 | [diff] [blame] | 50 | * ABSL_FLAG is allowed in tests and tools, but disallowed in in non-test code. |
| 51 | |
Danil Chapovalov | d004aee | 2024-12-09 17:09:53 | [diff] [blame] | 52 | [abseil-containers]: https://abseil.io/docs/cpp/guides/container |
Markus Handell | f70fbc8 | 2020-06-03 22:41:20 | [diff] [blame] | 53 | |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 54 | ## **Disallowed** |
| 55 | |
Mirko Bonadei | c128df1 | 2019-09-18 05:59:07 | [diff] [blame] | 56 | ### `absl::make_unique` |
| 57 | |
| 58 | *Use `std::make_unique` instead.* |
| 59 | |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 60 | ### `absl::Mutex` |
| 61 | |
Markus Handell | f70fbc8 | 2020-06-03 22:41:20 | [diff] [blame] | 62 | *Use `webrtc::Mutex` instead.* |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 63 | |
Florent Castelli | 9212f09 | 2024-08-29 13:42:57 | [diff] [blame] | 64 | ### `absl::optional` |
| 65 | |
| 66 | *Use `std::optional` instead.* |
| 67 | |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 68 | ### `absl::Span` |
| 69 | |
| 70 | *Use `rtc::ArrayView` instead.* |
| 71 | |
| 72 | `absl::Span` differs from `rtc::ArrayView` on several points, and both |
Danil Chapovalov | 04ab497 | 2024-09-02 16:23:21 | [diff] [blame] | 73 | of them differ from the `std::span` introduced in C++20. We should just keep |
| 74 | using `rtc::ArrayView` and avoid `absl::Span`. When WebRTC switches to C++20, |
| 75 | we will consider replacing `rtc::ArrayView` with `std::span`. |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 76 | |
Karl Wiberg | bd0deca | 2019-02-26 00:42:26 | [diff] [blame] | 77 | ### `absl::StrCat`, `absl::StrAppend`, `absl::StrJoin`, `absl::StrSplit` |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 78 | |
Karl Wiberg | bd0deca | 2019-02-26 00:42:26 | [diff] [blame] | 79 | *Use `rtc::SimpleStringBuilder` to build strings.* |
Karl Wiberg | c3af97d | 2018-08-27 02:26:18 | [diff] [blame] | 80 | |
| 81 | These are optimized for speed, not binary size. Even `StrCat` calls |
| 82 | with a modest number of arguments can easily add several hundred bytes |
| 83 | to the binary. |
Harald Alvestrand | aaaeb29 | 2024-10-31 13:49:39 | [diff] [blame] | 84 | |
| 85 | Exception: Single-argument absl::StrCat is allowed in order to make it |
Danil Chapovalov | d004aee | 2024-12-09 17:09:53 | [diff] [blame] | 86 | easy to use AbslStringify. See [TOTW #215](https://abseil.io/tips/215) for |
Harald Alvestrand | aaaeb29 | 2024-10-31 13:49:39 | [diff] [blame] | 87 | details on AbslStringify. |