Google Git
Sign in
chromium / chromium / src / 0e0f72bf9c5aaecd3256d339c369a815be7f19fb / . / styleguide / c++ / c++11.html
blob: 619d1af88bfa883e0d5f6ff3bdca5c0e31a13199 [file] [log] [blame]
Peter Kastinga9cf1c52020-07-31 17:42:46[diff] [blame]1<!DOCTYPE html>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]2<!--
3Copyright 2014 The Chromium Authors. All rights reserved.
4Use of this source code is governed by a BSD-style license that can be
5found in the LICENSE file.
6-->
7<html>
8<head>
9<meta charset="utf-8">
Jeremy Roman1bebbea2019-06-20 19:17:14[diff] [blame]10<title>Modern C++ use in Chromium</title>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]11<link rel="stylesheet" href="c++11.css">
12<style>
13table tbody tr td:first-child {
14 font-weight: bold;
15 font-size: 110%;
16}
17</style>
18</head>
19<body>
20<div id="content">
Peter Kasting777e1302020-06-02 21:44:40[diff] [blame]21<h1>Modern C++ use in Chromium</h1>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]22
Jan Wilken Dörrieb09e7052021-02-05 18:55:05[diff] [blame]23<p><i>This document lives at
John Palmerbe051302021-05-19 11:48:35[diff] [blame]24<a href="https://source.chromium.org/chromium/chromium/src/+/main:styleguide/c++/c++11.html">
Jan Wilken Dörrieb09e7052021-02-05 18:55:05[diff] [blame]25src/styleguide/c++/c++11.html</a> in a Chromium checkout and is part of the more general
John Palmerbe051302021-05-19 11:48:35[diff] [blame]26<a href="https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md">
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]27Chromium C++ style guide</a>. It summarizes the supported state of new and
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]28updated language and library features in recent C++ standards and the
29<a href="https://abseil.io/about/">Abseil</a> library. This guide
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]30applies to both Chromium and its subprojects, though subprojects can choose to
31be more restrictive if necessary for toolchain support.</i></p>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]32
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]33<p>The C++ language has in recent years received an updated standard every three
34years (C++11, C++14, C++17). For various reasons, Chromium does not immediately
35allow new features on the publication of such a standard. Instead, once
36toolchain support is sufficient, a standard is declared "initially supported",
37with new language/library features banned pending discussion.</p>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]38
pkastingfc30cf42016-11-04 00:49:03[diff] [blame]39<p>You can propose changing the status of a feature by sending an email to
40<a href="https://groups.google.com/a/chromium.org/forum/#!forum/cxx">
41[email protected]</a>. Include a short blurb on what the feature is and why you
42think it should or should not be allowed, along with links to any relevant
43previous discussion. If the list arrives at some consensus, send a codereview to
44change this file accordingly, linking to your discussion thread.</p>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]45
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]46<p>If an item remains on the TBD list two years after initial support is added,
47style arbiters should explicitly move it to an appropriate allowlist or blocklist,
48allowing it if there are no obvious reasons to ban.
49The current status of existing standards and Abseil features is:
50
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]51<ul><li><b>C++11:</b> <i>Default allowed; see banned features below</i></li>
Peter Kastingb6a3e582019-08-28 14:31:54[diff] [blame]52<li><b>C++14:</b> <i>Default allowed; see banned features below</i></li>
Peter Kasting777e1302020-06-02 21:44:40[diff] [blame]53<li><b>C++17:</b> <i>Not yet supported in Chromium, unlikely before mid-2021; <a href="http://crbug.com/752720">tracking bug</a></i></li>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]54<li><b>C++20:</b> <i>Not yet standardized</i></li>
Danil Chapovalov3b6356a2020-09-03 14:46:20[diff] [blame]55<li><b>Abseil:</b> Initially supported July 31, 2020; see allowed/banned/TBD features below
56<ul>
57<li>absl::StatusOr: Initially supported September 3, 2020</li>
Danil Chapovalov5a12137e2021-02-04 14:51:24[diff] [blame]58<li>absl::Cleanup: Initially supported February 4, 2021</li>
Danil Chapovalov3b6356a2020-09-03 14:46:20[diff] [blame]59</ul></li>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]60</ul></p>
61
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]62
danakj4fd49fe42015-11-18 20:54:16[diff] [blame]63<h2>Table of Contents</h2>
64<ol class="toc">
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]65<li>Allowed Features<ol>
66 <li>Library
67 <a href="#absl-allowlist">Abseil</a>
68 </li>
69</ol></li>
danakj4fd49fe42015-11-18 20:54:16[diff] [blame]70<li>Banned Features<ol>
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]71 <li>Language
Peter Kastinga814ed52019-03-01 18:48:07[diff] [blame]72 <a href="#core-blocklist">C++11</a>
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]73 </li>
74 <li>Library
Peter Kastinga814ed52019-03-01 18:48:07[diff] [blame]75 <a href="#library-blocklist">C++11</a>
76 <a href="#library-blocklist-14">C++14</a>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]77 <a href="#absl-blocklist">Abseil</a>
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]78 </li>
danakj4fd49fe42015-11-18 20:54:16[diff] [blame]79</ol></li>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]80<li>To Be Discussed<ol>
81 <li>Library
82 <a href="#absl-review">Abseil</a>
83 </li>
84</ol></li>
85</li>
danakj4fd49fe42015-11-18 20:54:16[diff] [blame]86</ol>
87
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]88<h2 id="blocklist_banned"><a name="core-blocklist"></a>C++11 Banned Language Features</h2>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]89
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]90<p>The following C++11 language features are not allowed in the Chromium codebase.</p>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]91
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]92<table id="banned_list" class="unlined striped">
93<tbody>
94
95<tr>
96<th style='width:240px;'>Feature or Library</th>
97<th style='width:240px;'>Snippet</th>
98<th style='width:240px;'>Description</th>
99<th style='width:240px;'>Documentation Link</th>
pkasting0cb5bd42016-11-02 20:55:58[diff] [blame]100<th style='width:240px;'>Notes and Discussion Thread</th>
Nico Webercea20a82014-09-25 17:46:51[diff] [blame]101</tr>
102
103<tr>
pkastingfb8e7fe2016-10-31 21:34:45[diff] [blame]104<td>Inline Namespaces</td>
105<td><code>inline namespace foo { ... }</code></td>
106<td>Allows better versioning of namespaces</td>
107<td><a href="http://en.cppreference.com/w/cpp/language/namespace#Inline_namespaces">Inline namespaces</a></td>
108<td>Banned in the <a href="https://google.github.io/styleguide/cppguide.html#Namespaces">Google Style Guide</a>. Unclear how it will work with components.</td>
mdempsky33bafda2014-10-30 23:14:52[diff] [blame]109</tr>
110
111<tr>
thakis12bfc742014-10-28 04:37:49[diff] [blame]112<td><code>long long</code> Type</td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]113<td><code>long long <i>var</i> = <i>value</i>;</code></td>
thakis12bfc742014-10-28 04:37:49[diff] [blame]114<td>An integer of at least 64 bits</td>
pkasting07c0959a2016-04-14 22:16:43[diff] [blame]115<td><a href="http://en.cppreference.com/w/cpp/language/types">Fundamental types</a></td>
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]116<td>Use a stdint.h type if you need a 64-bit number. <a href="https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/RxugZ-pIDxk">Discussion thread</a></td>
thakis12bfc742014-10-28 04:37:49[diff] [blame]117</tr>
118
119<tr>
pkastingfb8e7fe2016-10-31 21:34:45[diff] [blame]120<td>User-Defined Literals</td>
121<td><code><i>type</i> <i>var</i> = <i>literal_value</i>_<i>type</i></code></td>
122<td>Allows user-defined literal expressions</td>
123<td><a href="http://en.cppreference.com/w/cpp/language/user_literal">User-defined literals</a></td>
124<td>Banned in the <a href="https://google.github.io/styleguide/cppguide.html#Operator_Overloading">Google Style Guide</a>.</td>
125</tr>
126
Thomas Guilbert91dff482019-02-01 02:35:19[diff] [blame]127<tr>
128<td>thread_local storage class</td>
129<td><code>thread_local int foo = 1;</code></td>
130<td>Puts variables into thread local storage.</td>
131<td><a href="http://en.cppreference.com/w/cpp/language/storage_duration">Storage duration</a></td>
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]132<td>Some surprising effects on Mac (<a href="https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/2msN8k3Xzgs">discussion</a>, <a href="https://groups.google.com/a/chromium.org/forum/#!topic/cxx/h7O5BdtWCZw">fork</a>). Use <code>base::SequenceLocalStorageSlot</code> for sequence support, and <code>base::ThreadLocal</code>/<code>base::ThreadLocalStorage</code> otherwise.</td>
Thomas Guilbert91dff482019-02-01 02:35:19[diff] [blame]133</tr>
134
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]135</tbody>
136</table>
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]137
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]138<h2 id="blocklist_stdlib"><a name="library-blocklist"></a>C++11 Banned Library Features</h2>
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]139
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]140<p>The following C++11 library features are not allowed in the Chromium codebase.</p>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]141
Peter Kastinga814ed52019-03-01 18:48:07[diff] [blame]142<table id="blocklist_lib_list" class="unlined striped">
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]143<tbody>
144
145<tr>
146<th style='width:240px;'>Feature</th>
147<th style='width:240px;'>Snippet</th>
148<th style='width:240px;'>Description</th>
149<th style='width:240px;'>Documentation Link</th>
pkasting0cb5bd42016-11-02 20:55:58[diff] [blame]150<th style='width:240px;'>Notes and Discussion Thread</th>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]151</tr>
152
pkastingfc30cf42016-11-04 00:49:03[diff] [blame]153<td>Bind Operations</td>
154<td><code>std::bind(<i>function</i>, <i>args</i>, ...)</code></td>
155<td>Declares a function object bound to certain arguments</td>
156<td><a href="http://en.cppreference.com/w/cpp/utility/functional/bind">std::bind</a></td>
157<td>Use <code>base::Bind</code> instead. Compared to <code>std::bind</code>, <code>base::Bind</code> helps prevent lifetime issues by preventing binding of capturing lambdas and by forcing callers to declare raw pointers as <code>Unretained</code>. <a href="https://groups.google.com/a/chromium.org/forum/#!topic/cxx/SoEj7oIDNuA">Discussion thread</a></td>
158</tr>
159
160<tr>
161<td>C Floating-Point Environment</td>
162<td><code>&lt;cfenv&gt;</code>, <code>&lt;fenv.h&gt;</code></td>
163<td>Provides floating point status flags and control modes for C-compatible code</td>
164<td><a href="http://en.cppreference.com/w/cpp/header/cfenv">Standard library header &lt;cfenv&gt;</a></td>
165<td>Banned by the <a href="https://google.github.io/styleguide/cppguide.html#C++11">Google Style Guide</a> due to concerns about compiler support.</td>
166</tr>
167
168<tr>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]169<td>Date and time utilities</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]170<td><code>&lt;chrono&gt;</code></td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]171<td>A standard date and time library</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]172<td><a href="http://en.cppreference.com/w/cpp/chrono">Date and time utilities</a></td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]173<td>Overlaps with <code>Time</code> APIs in <code>base/</code>. Keep using the <code>base/</code> classes.</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]174</tr>
175
176<tr>
pkastingc6a6ebf12016-10-31 20:38:40[diff] [blame]177<td>Exceptions</td>
178<td><code>&lt;exception&gt;</code></td>
179<td>Enhancements to exception throwing and handling</td>
180<td><a href="http://en.cppreference.com/w/cpp/header/exception">Standard library header &lt;exception&gt;</a></td>
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]181<td>Exceptions are banned by the <a href="https://google.github.io/styleguide/cppguide.html#Exceptions">Google Style Guide</a> and disabled in Chromium compiles. However, the <code>noexcept</code> specifier is explicitly allowed. <a href="https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/8i4tMqNpHhg">Discussion thread</a></td>
pkastingc6a6ebf12016-10-31 20:38:40[diff] [blame]182</tr>
183
184<tr>
pkastingfc30cf42016-11-04 00:49:03[diff] [blame]185<td>Function Objects</td>
186<td><code>std::function</code></td>
187<td>Wraps a standard polymorphic function</td>
188<td><a href="http://en.cppreference.com/w/cpp/utility/functional/function">std::function</a></td>
Alexander Cooperb3f1af662021-02-01 19:47:26[diff] [blame]189<td>Use <code>base::&lcub;Once,Repeating&rcub;Callback</code> instead. Compared to <code>std::function</code>, <code>base::&lcub;Once,Repeating&rcub;Callback</code> directly supports Chromium's refcounting classes and weak pointers and deals with additional thread safety concerns. <a href="https://groups.google.com/a/chromium.org/forum/#!topic/cxx/SoEj7oIDNuA">Discussion thread</a></td>
pkastingfc30cf42016-11-04 00:49:03[diff] [blame]190</tr>
191
192<tr>
Daniel Cheng66345dd2018-09-13 03:14:01[diff] [blame]193<td>Random Number Engines</td>
194<td>The random number engines defined in <code>&lt;random&gt;</code> (see separate item for random number distributions), e.g.:<br/>
195<code>linear_congruential_engine</code>, <code>mersenne_twister_engine</code><br/>
196<code>minstd_rand0</code>, <code>mt19937</code>, <code>ranlinux48</code><br/>
197<code>random_device</code>
198</td>
199<td>Random number generation algorithms and utilities.</td>
200<td><a href="http://en.cppreference.com/w/cpp/numeric/random">Pseudo-random number generation</a></td>
Peter Kastinga814ed52019-03-01 18:48:07[diff] [blame]201<td>Do not use any random number engines from <code>&lt;random&gt;</code>. Instead, use <code>base::RandomBitGenerator</code>. <a href="https://groups.google.com/a/chromium.org/forum/#!topic/cxx/16Xmw05C-Y0">Discussion thread</a></td>
Daniel Cheng66345dd2018-09-13 03:14:01[diff] [blame]202</tr>
203
204<tr>
pkastingfc30cf42016-11-04 00:49:03[diff] [blame]205<td>Ratio Template Class</td>
206<td><code>std::ratio&lt;<i>numerator</i>, <i>denominator</i>&gt;</code></td>
207<td>Provides compile-time rational numbers</td>
208<td><a href="http://en.cppreference.com/w/cpp/numeric/ratio/ratio">std::ratio</a></td>
209<td>Banned by the <a href="https://google.github.io/styleguide/cppguide.html#C++11">Google Style Guide</a> due to concerns that this is tied to a more template-heavy interface style.</td>
210</tr>
211
212<tr>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]213<td>Regular Expressions</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]214<td><code>&lt;regex&gt;</code></td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]215<td>A standard regular expressions library</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]216<td><a href="http://en.cppreference.com/w/cpp/regex">Regular expressions library</a></td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]217<td>Overlaps with many regular expression libraries in Chromium. When in doubt, use re2.</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]218</tr>
219
220<tr>
pkastingfb8e7fe2016-10-31 21:34:45[diff] [blame]221<td>Shared Pointers</td>
222<td><code>std::shared_ptr</code></td>
223<td>Allows shared ownership of a pointer through reference counts</td>
224<td><a href="http://en.cppreference.com/w/cpp/memory/shared_ptr">std::shared_ptr</a></td>
pkasting0cb5bd42016-11-02 20:55:58[diff] [blame]225<td>Needs a lot more evaluation for Chromium, and there isn't enough of a push for this feature. <a href="https://google.github.io/styleguide/cppguide.html#Ownership_and_Smart_Pointers">Google Style Guide</a>. <a href="https://groups.google.com/a/chromium.org/forum/#!topic/cxx/aT2wsBLKvzI">Discussion Thread</a></td>
pkastingfb8e7fe2016-10-31 21:34:45[diff] [blame]226</tr>
227
228<tr>
Peter Kasting991618a62019-06-17 22:00:09[diff] [blame]229<td>String-Number Conversion Functions</td>
230<td><code>std::stoi()</code>, <code>std::stol()</code>, <code>std::stoul()</code>, <code>std::stoll</code>, <code>std::stoull()</code>, <code>std::stof()</code>, <code>std::stod()</code>, <code>std::stold()</code>, <code>std::to_string()</code></td>
231<td>Converts strings to/from numbers</td>
232<td><a href="http://en.cppreference.com/w/cpp/string/basic_string/stol">std::stoi, std::stol, std::stoll</a>, <a href="http://en.cppreference.com/w/cpp/string/basic_string/stoul">std::stoul, std::stoull</a>, <a href="http://en.cppreference.com/w/cpp/string/basic_string/stof">std::stof, std::stod, std::stold</a>, <a href="http://en.cppreference.com/w/cpp/string/basic_string/to_string">std::to_string</a></td>
233<td>The string-to-number conversions rely on exceptions to communicate failure, while the number-to-string conversions have performance concerns and depend on the locale. Use the routines in <code>base/strings/string_number_conversions.h</code> instead.</td>
234</tr>
235
236<tr>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]237<td>Thread Library</td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]238<td><code>&lt;thread&gt;</code> and related headers, including<br />
pkasting07c0959a2016-04-14 22:16:43[diff] [blame]239<code>&lt;future&gt;</code>, <code>&lt;mutex&gt;</code>, <code>&lt;condition_variable&gt;</code></td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]240<td>Provides a standard multithreading library using <code>std::thread</code> and associates</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]241<td><a href="http://en.cppreference.com/w/cpp/thread">Thread support library</a></td>
pkasting7f0693b32016-10-31 20:27:50[diff] [blame]242<td>Overlaps with many classes in <code>base/</code>. Keep using the <code>base/</code> classes for now. <code>base::Thread</code> is tightly coupled to <code>MessageLoop</code> which would make it hard to replace. We should investigate using standard mutexes, or unique_lock, etc. to replace our locking/synchronization classes.</td>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]243</tr>
244
Peter Kasting991618a62019-06-17 22:00:09[diff] [blame]245<tr>
246<td>Weak Pointers</td>
247<td><code>std::weak_ptr</code></td>
248<td>Allows a weak reference to a <code>std::shared_ptr</code></td>
249<td><a href="http://en.cppreference.com/w/cpp/memory/weak_ptr">std::weak_ptr</a></td>
250<td>Banned because <code>std::shared_ptr</code> is banned. Use <code>base::WeakPtr</code> instead.</td>
251</tr>
252
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]253</tbody>
254</table>
255
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]256<h2 id="blocklist_stdlib"><a name="library-blocklist-14"></a>C++14 Banned Library Features</h2>
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]257
Peter Kasting48c380a22019-06-17 22:22:38[diff] [blame]258<p>The following C++14 library features are not allowed in the Chromium codebase.</p>
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]259
Peter Kastinga814ed52019-03-01 18:48:07[diff] [blame]260<table id="blocklist_lib_list" class="unlined striped">
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]261<tbody>
262
263<tr>
264<th style='width:240px;'>Feature</th>
265<th style='width:240px;'>Snippet</th>
266<th style='width:240px;'>Description</th>
267<th style='width:240px;'>Documentation Link</th>
268<th style='width:240px;'>Notes and Discussion Thread</th>
269</tr>
270
Jeremy Romanabd27842017-08-04 18:27:55[diff] [blame]271<tr>
272<td><code>std::chrono</code> literals</td>
273<td><code>using namespace std::chrono_literals;<br>auto timeout = 30s;</code></td>
274<td>Allows <code>std::chrono</code> types to be more easily constructed.</td>
275<td><a href="http://en.cppreference.com/w/cpp/chrono/operator%22%22s">std::literals::chrono_literals::operator""s</a></td>
276<td>Banned because <code>&lt;chrono&gt;</code> is banned.</td>
277</tr>
278
Nico Weber81c1feb2017-07-31 03:25:13[diff] [blame]279</tbody>
280</table>
Nico Weberc8eb8ca2015-11-11 00:23:34[diff] [blame]281
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]282<h2 id="allowlist_abseil"><a name="absl-allowlist"></a>Abseil Allowed Library Features</h2>
283
284<p>The following Abseil library features are allowed in the Chromium codebase.</p>
285
286<table id="allowlist_abseil_list" class="unlined striped">
287<tbody>
288
289<tr>
290<th style='width:240px;'>Feature</th>
291<th style='width:240px;'>Snippet</th>
292<th style='width:240px;'>Description</th>
293<th style='width:240px;'>Documentation Link</th>
294<th style='width:240px;'>Notes and Discussion Thread</th>
295</tr>
296
297<tr>
Peter Kastinga55a2b202021-05-13 16:22:56[diff] [blame]298<td>Optional</td>
299<td><code>absl::optional</code></td>
300<td>Early adaptation of C++17 std::optional.</td>
301<td><a href="https://en.cppreference.com/w/cpp/utility/optional">std::optional</a></td>
302<td>Replaces <code>base::Optional</code>. <a href="https://groups.google.com/a/chromium.org/g/cxx/c/zUGqagX1NFU">Discussion thread</a></td>
303</tr>
304
305<tr>
Alan Cutterf4b12dce2020-11-26 23:38:28[diff] [blame]306<td>Status</td>
307<td><code>absl::Status</code></td>
308<td>Type for returning detailed errors.</td>
John Palmerbe051302021-05-19 11:48:35[diff] [blame]309<td><a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/status/status.h">status.h</a></td>
John Palmer0e0f72bf2021-06-07 09:10:20[diff] [blame^]310<td>Approved for use inside a wrapper type. Use <a href="https://source.chromium.org/chromium/chromium/src/+/main:base/strings/abseil_string_conversions.h">abseil_string_conversions.h</a> to convert to and from <a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/strings/string_view.h">absl::string_view</a> so the wrapper can expose <a href="https://source.chromium.org/chromium/chromium/src/+/main:base/strings/string_piece.h">base::StringPiece</a>. Use <a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/strings/cord.h">absl::Cord</a> directly as minimally necessary to interface; do not expose in the wrapper type API.<br>
Alan Cutterf4b12dce2020-11-26 23:38:28[diff] [blame]311<a href="https://groups.google.com/a/chromium.org/g/cxx/c/ImdFCSZ-NMA">Discussion thread</a></td>
312</tr>
313
314<tr>
Peter Kastinga9cf1c52020-07-31 17:42:46[diff] [blame]315<td>Variant</td>
316<td><code>absl::variant</code></td>
317<td>Early adaptation of C++17 std::variant.</td>
318<td><a href="https://en.cppreference.com/w/cpp/utility/variant">std::variant</a></td>
319<td><a href="https://groups.google.com/a/chromium.org/g/cxx/c/DqvG-TpvMyU">Discussion thread</a></td>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]320</tr>
321
322</tbody>
323</table>
324
325<h2 id="blocklist_absl"><a name="absl-blocklist"></a>Abseil Banned Library Features</h2>
326
327<p>The following Abseil library features are not allowed in the Chromium codebase.</p>
328
329<table id="blocklist_absl_list" class="unlined striped">
330<tbody>
331
332<tr>
333<th style='width:240px;'>Feature</th>
334<th style='width:240px;'>Snippet</th>
335<th style='width:240px;'>Description</th>
336<th style='width:240px;'>Documentation Link</th>
337<th style='width:240px;'>Notes and Discussion Thread</th>
338</tr>
339
340<tr>
341<td>Any</td>
342<td><code>absl::any a = int{5};
343<br>EXPECT_THAT(absl::any_cast&lt;int&gt;(&a), Pointee(5));
344<br>EXPECT_EQ(absl::any_cast&lt;size_t&gt;(&a), nullptr);</code></td>
345<td>Early adaptation of C++17 std::any.</td>
346<td><a href="https://en.cppreference.com/w/cpp/utility/any">std::any</a></td>
347<td>Banned since workaround for lack of RTTI isn't compatible with the component build. <a href="http://crbug.com/1096380">Bug</a></td>
348</tr>
349
350<tr>
351<td>Command line flags</td>
352<td><code>ABSL_FLAG(bool, logs, false, "print logs to stderr");<br>app --logs=true;</code></td>
353<td>Allows programmatic access to flag values passed on the command-line to binaries.</td>
354<td><a href="https://abseil.io/docs/cpp/guides/flags">Flags Library</a></td>
355<td>Banned since workaround for lack of RTTI isn't compatible with the component build. <a href="http://crbug.com/1096380">Bug</a><br>
356Use <code>base::CommandLine</code> instead.</td>
357</tr>
358
359<tr>
360<td>Span</td>
361<td><code>absl::Span</code></td>
362<td>Early adaptation of C++20 std::span.</td>
363<td><a href="https://abseil.io/tips/93">Using absl::Span</a></td>
364<td>Banned due to being less std::-compliant than <code>base::span</code>.
365<br>Keep using <code>base::span</code>.</td>
366</tr>
367
368<tr>
369<td>string_view</td>
370<td><code>absl::string_view</code></td>
371<td>Early adaptation of C++17 std::string_view.</td>
372<td><a href="https://abseil.io/tips/1">absl::string_view</a></td>
373<td>Banned due to only working with 8-bit characters.
374Keep using <code>base::StringPiece</code> from <code>base/strings/</code>.</td>
375</tr>
376
377</tbody>
378</table>
379
380<h2 id="review_abseil"><a name="absl-review"></a>Abseil TBD Features</h2>
381
382<p>The following Abseil library features are not allowed in the Chromium codebase.
383See the top of this page on how to propose moving a feature from this list into
384the allowed or banned sections.</p>
385
386<table id="absl_review_list" class="unlined striped">
387<tbody>
388
389<tr>
390<th style='width:240px;'>Feature</th>
391<th style='width:240px;'>Snippet</th>
392<th style='width:240px;'>Description</th>
393<th style='width:240px;'>Documentation Link</th>
394<th style='width:240px;'>Notes and Discussion Thread</th>
395</tr>
396
397<tr>
398<td>128bit integer</td>
399<td><code>uint64_t a;<br>absl::uint128 v = a;</code></td>
400<td>Signed and unsigned 128-bit integer types meant to mimic intrinsic types as closely as possible.</td>
401<td><a href="https://abseil.io/docs/cpp/guides/numeric">Numerics</a></td>
402<td></td>
403</tr>
404
405<tr>
406<td>bind_front</td>
407<td><code>absl::bind_front</code></td>
408<td>Binds the first N arguments of an invocable object and stores them by value.</td>
John Palmerbe051302021-05-19 11:48:35[diff] [blame]409<td><a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/functional/bind_front.h">bind_front.h</a>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]410<br><a href="https://abseil.io/tips/108">Avoid std::bind</a></td>
411<td>Overlaps with <code>base::Bind</code>.</td>
412</tr>
413
414<tr>
Danil Chapovalov5a12137e2021-02-04 14:51:24[diff] [blame]415<td>Cleanup</td>
416<td><code>FILE* sink_file = fopen(sink_path, "w");<br>auto sink_closer = absl::MakeCleanup([sink_file] { fclose(sink_file); });</code></td>
417<td>Implements the scope guard idiom, invoking the contained callback's `operator()() &&` on scope exit.</td>
John Palmerbe051302021-05-19 11:48:35[diff] [blame]418<td><a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/cleanup/cleanup.h">cleanup.h</a></td>
Danil Chapovalov5a12137e2021-02-04 14:51:24[diff] [blame]419<td>Similar to `defer` in Golang.</td>
420</tr>
421
422<tr>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]423<td>Containers</td>
424<td><code>absl::flat_hash_map, absl::flat_hash_set,<br>absl::node_hash_map, absl::node_hash_set,<br>
425absl::btree_map, absl::btree_set,<br>absl::btree_multimap, absl::btree_multiset,<br>
426absl::InlinedVector, absl::FixedArray</code></td>
427<td>Alternatives to STL containers designed to be more efficient in the general case.</td>
428<td><a href="https://abseil.io/docs/cpp/guides/container">Containers</a><br>
429<a href="https://abseil.io/docs/cpp/guides/hash">Hash</a></td>
430<td>Supplements <code>base/containers/</code>.</td>
431</tr>
432
433<tr>
434<td>Container utilities</td>
435<td><code>auto it = absl::c_find(container, value);</code></td>
436<td>Container-based versions of algorithmic functions within C++ standard library.</td>
John Palmerbe051302021-05-19 11:48:35[diff] [blame]437<td><a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/algorithm/container.h">container.h</a></td>
Jan Wilken Dörriea94154612020-09-11 09:12:46[diff] [blame]438<td>Overlaps with <code>base/ranges/algorithm.h</code>.</td>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]439</tr>
440
441<tr>
442<td>FunctionRef</td>
443<td><code>absl::FunctionRef</code></td>
444<td>Type for holding a non-owning reference to an object of any invocable type.</td>
John Palmerbe051302021-05-19 11:48:35[diff] [blame]445<td><a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/functional/function_ref.h">function_ref.h</a></td>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]446<td></td>
447</tr>
448
449<tr>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]450<td>Random</td>
451<td><code>absl::BitGen bitgen;<br>
452size_t index = absl::Uniform(bitgen, 0u, elems.size());</code></td>
453<td>Functions and utilities for generating pseudorandom data.</td>
454<td><a href="https://abseil.io/docs/cpp/guides/random">Random library</a></td>
455<td>Overlaps with <code>base/rand_util.h</code>.</td>
456</tr>
457
458<tr>
Danil Chapovalov3b6356a2020-09-03 14:46:20[diff] [blame]459<td>StatusOr</td>
460<td><code>absl::StatusOr&lt;T&gt;</td>
461<td>An object that is either a usable value, or an error Status explaining why such a value is not present.</td>
John Palmerbe051302021-05-19 11:48:35[diff] [blame]462<td><a href="https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/status/statusor.h">statusor.h</a></td>
Danil Chapovalov3b6356a2020-09-03 14:46:20[diff] [blame]463<td></td>
464</tr>
465
466<tr>
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]467<td>String Formatting</td>
468<td><code>absl::StrFormat</code>
469<td>A typesafe replacement for the family of printf() string formatting routines.</td>
470<td><a href="https://abseil.io/docs/cpp/guides/format">String Formatting</a>
471<td></td>
472</tr>
473
474<tr>
475<td>Strings Library</td>
476<td><code>absl::StrSplit, absl::StrJoin,<br> absl::StrCat, absl::StrAppend,<br> absl::Substitute, absl::StrContains</code></td>
477<td>Classes and utility functions for manipulating and comparing strings.</td>
478<td><a href="https://abseil.io/docs/cpp/guides/strings">String Utilities</a>
479<td>Overlaps with <code>base/strings</code>.</td>
480</tr>
481
482<tr>
483<td>Synchronization</td>
484<td><code>absl::Mutex</code></td>
485<td>Primitives for managing tasks across different threads.</td>
486<td><a href="https://abseil.io/docs/cpp/guides/synchronization">Synchronization</a></td>
487<td>Overlaps with <code>Lock</code> in <code>base/synchronization/</code>.</td>
488</tr>
489
490<tr>
491<td>Time library</td>
492<td><code>absl::Duration, absl::Time,<br> absl::TimeZone, absl::CivilDay</code></td>
493<td>Abstractions for holding time values, both in terms of absolute time and civil time.</td>
494<td><a href="https://abseil.io/docs/cpp/guides/time">Time</a></td>
495<td>Overlaps with <code>Time</code> APIs in <code>base/</code>.</td>
496</tr>
497
Danil Chapovalovd98d7092020-07-29 11:04:40[diff] [blame]498</tbody>
499</table>
500
Nico Weber019d40f2014-09-23 20:21:59[diff] [blame]501</div>
502</body>
503</html>