blob: beaa5cc45bd117ca23e2f3b955eb08374048572a [file] [log] [blame] [view]
Artem Titova6178672023-01-30 10:51:011<!-- go/cmark -->
Danil Chapovalov04ab4972024-09-02 16:23:212<!--* freshness: {owner: 'danilchap' reviewed: '2024-09-02'} *-->
Danil Chapovalov46f5c112021-05-12 12:05:483
Artem Titova6178672023-01-30 10:51:014# Using Abseil in WebRTC
Artem Titov0f2ce5c2023-01-26 20:18:465
Karl Wibergc3af97d2018-08-27 02:26:186You may use a subset of the utilities provided by the [Abseil][abseil]
7library when writing WebRTC C++ code. Below, we list the explicitly
8*allowed* and the explicitly *disallowed* subsets of Abseil; if you
9find yourself in need of something that isn&rsquo;t in either subset,
10please add it to the *allowed* subset in this doc in the same CL that
11adds the first use.
12
13[abseil]: https://abseil.io/about/
14
Karl Wiberga667f872020-10-15 23:02:3715
16## How to depend on Abseil
17
18For build targets of type `rtc_library`, `rtc_source_set` and
Florent Castelliae5d5032024-05-27 10:19:0519`rtc_static_library`, dependencies on Abseil need to be listed in `deps`.
Karl Wiberga667f872020-10-15 23:02:3720
Florent Castelliae5d5032024-05-27 10:19:0521The GN templates will take care of generating the proper dependency when
22used within Chromium or standalone. In that build mode, WebRTC will depend
23on a monolithic Abseil build target that will generate a shared library.
24
Karl Wibergc3af97d2018-08-27 02:26:1825## **Allowed**
26
Danil Chapovalov4b979282022-06-30 08:08:4727* `absl::AnyInvocable`
Per Kjellanderfe2063e2021-05-12 07:02:4328* `absl::bind_front`
Danil Chapovalove6106102022-02-16 11:29:0229* `absl::Cleanup`
Danil Chapovalovd004aee2024-12-09 17:09:5330* [Hash tables, and B-tree ordered][abseil-containers] containers
Karl Wibergc3af97d2018-08-27 02:26:1831* `absl::InlinedVector`
Tommifd3b3462023-10-27 20:38:3332* `absl::Nonnull` and `absl::Nullable`
Mirko Bonadeic128df12019-09-18 05:59:0733* `absl::WrapUnique`
Karl Wibergc3af97d2018-08-27 02:26:1834* `absl::string_view`
Steve Anton1c9c9fc2019-02-14 23:13:0935* The functions in `absl/strings/ascii.h`, `absl/strings/match.h`,
36 and `absl/strings/str_replace.h`.
Harald Alvestrand666c3332022-10-18 12:32:4037* The functions in `absl/strings/escaping.h`.
Jiawei Oua6e034a2018-11-25 04:59:4138* `absl::is_trivially_copy_constructible`,
39 `absl::is_trivially_copy_assignable`, and
40 `absl::is_trivially_destructible` from `absl/meta/type_traits.h`.
Karl Wibergc3af97d2018-08-27 02:26:1841* `absl::variant` and related stuff from `absl/types/variant.h`.
Steve Antone76ca612019-01-25 20:49:1442* The functions in `absl/algorithm/algorithm.h` and
Elad Alone86af2c2019-06-03 12:37:5043 `absl/algorithm/container.h`.
Markus Handellf70fbc82020-06-03 22:41:2044* `absl/base/const_init.h` for mutex initialization.
Elad Alone86af2c2019-06-03 12:37:5045* The macros in `absl/base/attributes.h`, `absl/base/config.h` and
46 `absl/base/macros.h`.
Danil Chapovalov09fb7872021-08-20 10:46:1447* `absl/numeric/bits.h`
Harald Alvestrandaaaeb292024-10-31 13:49:3948* Single argument absl::StrCat
Karl Wibergc3af97d2018-08-27 02:26:1849
Danil Chapovalov04ab4972024-09-02 16:23:2150* ABSL_FLAG is allowed in tests and tools, but disallowed in in non-test code.
51
Danil Chapovalovd004aee2024-12-09 17:09:5352[abseil-containers]: https://abseil.io/docs/cpp/guides/container
Markus Handellf70fbc82020-06-03 22:41:2053
Karl Wibergc3af97d2018-08-27 02:26:1854## **Disallowed**
55
Mirko Bonadeic128df12019-09-18 05:59:0756### `absl::make_unique`
57
58*Use `std::make_unique` instead.*
59
Karl Wibergc3af97d2018-08-27 02:26:1860### `absl::Mutex`
61
Markus Handellf70fbc82020-06-03 22:41:2062*Use `webrtc::Mutex` instead.*
Karl Wibergc3af97d2018-08-27 02:26:1863
Florent Castelli9212f092024-08-29 13:42:5764### `absl::optional`
65
66*Use `std::optional` instead.*
67
Karl Wibergc3af97d2018-08-27 02:26:1868### `absl::Span`
69
70*Use `rtc::ArrayView` instead.*
71
72`absl::Span` differs from `rtc::ArrayView` on several points, and both
Danil Chapovalov04ab4972024-09-02 16:23:2173of them differ from the `std::span` introduced in C++20. We should just keep
74using `rtc::ArrayView` and avoid `absl::Span`. When WebRTC switches to C++20,
75we will consider replacing `rtc::ArrayView` with `std::span`.
Karl Wibergc3af97d2018-08-27 02:26:1876
Karl Wibergbd0deca2019-02-26 00:42:2677### `absl::StrCat`, `absl::StrAppend`, `absl::StrJoin`, `absl::StrSplit`
Karl Wibergc3af97d2018-08-27 02:26:1878
Karl Wibergbd0deca2019-02-26 00:42:2679*Use `rtc::SimpleStringBuilder` to build strings.*
Karl Wibergc3af97d2018-08-27 02:26:1880
81These are optimized for speed, not binary size. Even `StrCat` calls
82with a modest number of arguments can easily add several hundred bytes
83to the binary.
Harald Alvestrandaaaeb292024-10-31 13:49:3984
85Exception: Single-argument absl::StrCat is allowed in order to make it
Danil Chapovalovd004aee2024-12-09 17:09:5386easy to use AbslStringify. See [TOTW #215](https://abseil.io/tips/215) for
Harald Alvestrandaaaeb292024-10-31 13:49:3987details on AbslStringify.