| <!DOCTYPE html> |
| <!-- |
| Copyright 2014 The Chromium Authors. All rights reserved. |
| Use of this source code is governed by a BSD-style license that can be |
| found in the LICENSE file. |
| --> |
| <html> |
| <head> |
| <meta charset="utf-8"> |
| <title>Modern C++ use in Chromium</title> |
| <link rel="stylesheet" href="c++11.css"> |
| <style> |
| table tbody tr td:first-child { |
| font-weight: bold; |
| font-size: 110%; |
| } |
| </style> |
| </head> |
| <body> |
| <div id="content"> |
| <h1>C++ use in Chromium</h1> |
| |
| <p><i>This document lives at src/styleguide/c++/c++11.html in a Chromium |
| checkout and is part of the more general |
| <a href="https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md"> |
| Chromium C++ style guide</a>. It summarizes the supported state of new and |
| updated language and library features in recent C++ standards. This guide |
| applies to both Chromium and its subprojects, though subprojects can choose to |
| be more restrictive if necessary for toolchain support.</i></p> |
| |
| <p>The C++ language has in recent years received an updated standard every three |
| years (C++11, C++14, C++17). For various reasons, Chromium does not immediately |
| allow new features on the publication of such a standard. Instead, once |
| toolchain support is sufficient, a standard is declared "initially supported", |
| with new language/library features banned pending discussion.</p> |
| |
| <p>You can propose changing the status of a feature by sending an email to |
| <a href="https://groups.google.com/a/chromium.org/forum/#!forum/cxx"> |
| cxx@chromium.org</a>. Include a short blurb on what the feature is and why you |
| think it should or should not be allowed, along with links to any relevant |
| previous discussion. If the list arrives at some consensus, send a codereview to |
| change this file accordingly, linking to your discussion thread.</p> |
| |
| <p>Two years after a standard is initially supported in Chromium, style arbiters |
| should make a final decision on any remaining TBD features to be banned, then |
| default-allow all non-banned portions of the standard. The current status of |
| existing standards is: |
| <ul><li><b>C++11:</b> <i>Default allowed; see banned features below</i></li> |
| <li><b>C++14:</b> <i>Default allowed; see banned features below</i></li> |
| <li><b>C++17:</b> <i>Not yet supported in Chromium</i></li> |
| <li><b>C++20:</b> <i>Not yet standardized</i></li></ul></p> |
| |
| <h2>Table of Contents</h2> |
| <ol class="toc"> |
| <li>Banned Features<ol> |
| <li>Language |
| <a href="#core-blocklist">C++11</a> |
| </li> |
| <li>Library |
| <a href="#library-blocklist">C++11</a> |
| <a href="#library-blocklist-14">C++14</a> |
| </li> |
| </ol></li> |
| </ol> |
| |
| <h2 id="blocklist_banned"><a name="core-blocklist"></a>C++11 Banned Language Features</h2> |
| |
| <p>The following C++11 language features are not allowed in the Chromium codebase.</p> |
| |
| <table id="banned_list" class="unlined striped"> |
| <tbody> |
| |
| <tr> |
| <th style='width:240px;'>Feature or Library</th> |
| <th style='width:240px;'>Snippet</th> |
| <th style='width:240px;'>Description</th> |
| <th style='width:240px;'>Documentation Link</th> |
| <th style='width:240px;'>Notes and Discussion Thread</th> |
| </tr> |
| |
| <tr> |
| <td>Inline Namespaces</td> |
| <td><code>inline namespace foo { ... }</code></td> |
| <td>Allows better versioning of namespaces</td> |
| <td><a href="http://en.cppreference.com/w/cpp/language/namespace#Inline_namespaces">Inline namespaces</a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td><code>long long</code> Type</td> |
| <td><code>long long <i>var</i> = <i>value</i>;</code></td> |
| <td>An integer of at least 64 bits</td> |
| <td><a href="http://en.cppreference.com/w/cpp/language/types">Fundamental types</a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>User-Defined Literals</td> |
| <td><code><i>type</i> <i>var</i> = <i>literal_value</i>_<i>type</i></code></td> |
| <td>Allows user-defined literal expressions</td> |
| <td><a href="http://en.cppreference.com/w/cpp/language/user_literal">User-defined literals</a></td> |
| <td>Banned in the <a href="https://google.github.io/styleguide/cppguide.html#Operator_Overloading">Google Style Guide</a>.</td> |
| </tr> |
| |
| <tr> |
| <td>thread_local storage class</td> |
| <td><code>thread_local int foo = 1;</code></td> |
| <td>Puts variables into thread local storage.</td> |
| <td><a href="http://en.cppreference.com/w/cpp/language/storage_duration">Storage duration</a></td> |
| <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> |
| </tr> |
| |
| </tbody> |
| </table> |
| |
| <h2 id="blocklist_stdlib"><a name="library-blocklist"></a>C++11 Banned Library Features</h2> |
| |
| <p>The following C++11 library features are not allowed in the Chromium codebase.</p> |
| |
| <table id="blocklist_lib_list" class="unlined striped"> |
| <tbody> |
| |
| <tr> |
| <th style='width:240px;'>Feature</th> |
| <th style='width:240px;'>Snippet</th> |
| <th style='width:240px;'>Description</th> |
| <th style='width:240px;'>Documentation Link</th> |
| <th style='width:240px;'>Notes and Discussion Thread</th> |
| </tr> |
| |
| <td>Bind Operations</td> |
| <td><code>std::bind(<i>function</i>, <i>args</i>, ...)</code></td> |
| <td>Declares a function object bound to certain arguments</td> |
| <td><a href="http://en.cppreference.com/w/cpp/utility/functional/bind">std::bind</a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>C Floating-Point Environment</td> |
| <td><code><cfenv></code>, <code><fenv.h></code></td> |
| <td>Provides floating point status flags and control modes for C-compatible code</td> |
| <td><a href="http://en.cppreference.com/w/cpp/header/cfenv">Standard library header <cfenv></a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>Date and time utilities</td> |
| <td><code><chrono></code></td> |
| <td>A standard date and time library</td> |
| <td><a href="http://en.cppreference.com/w/cpp/chrono">Date and time utilities</a></td> |
| <td>Overlaps with <code>Time</code> APIs in <code>base/</code>. Keep using the <code>base/</code> classes.</td> |
| </tr> |
| |
| <tr> |
| <td>Exceptions</td> |
| <td><code><exception></code></td> |
| <td>Enhancements to exception throwing and handling</td> |
| <td><a href="http://en.cppreference.com/w/cpp/header/exception">Standard library header <exception></a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>Function Objects</td> |
| <td><code>std::function</code></td> |
| <td>Wraps a standard polymorphic function</td> |
| <td><a href="http://en.cppreference.com/w/cpp/utility/functional/function">std::function</a></td> |
| <td>Use <code>base::Callback</code> instead. Compared to <code>std::function</code>, <code>base::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> |
| </tr> |
| |
| <tr> |
| <td>Random Number Engines</td> |
| <td>The random number engines defined in <code><random></code> (see separate item for random number distributions), e.g.:<br/> |
| <code>linear_congruential_engine</code>, <code>mersenne_twister_engine</code><br/> |
| <code>minstd_rand0</code>, <code>mt19937</code>, <code>ranlinux48</code><br/> |
| <code>random_device</code> |
| </td> |
| <td>Random number generation algorithms and utilities.</td> |
| <td><a href="http://en.cppreference.com/w/cpp/numeric/random">Pseudo-random number generation</a></td> |
| <td>Do not use any random number engines from <code><random></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> |
| </tr> |
| |
| <tr> |
| <td>Ratio Template Class</td> |
| <td><code>std::ratio<<i>numerator</i>, <i>denominator</i>></code></td> |
| <td>Provides compile-time rational numbers</td> |
| <td><a href="http://en.cppreference.com/w/cpp/numeric/ratio/ratio">std::ratio</a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>Regular Expressions</td> |
| <td><code><regex></code></td> |
| <td>A standard regular expressions library</td> |
| <td><a href="http://en.cppreference.com/w/cpp/regex">Regular expressions library</a></td> |
| <td>Overlaps with many regular expression libraries in Chromium. When in doubt, use re2.</td> |
| </tr> |
| |
| <tr> |
| <td>Shared Pointers</td> |
| <td><code>std::shared_ptr</code></td> |
| <td>Allows shared ownership of a pointer through reference counts</td> |
| <td><a href="http://en.cppreference.com/w/cpp/memory/shared_ptr">std::shared_ptr</a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>String-Number Conversion Functions</td> |
| <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> |
| <td>Converts strings to/from numbers</td> |
| <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> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>Thread Library</td> |
| <td><code><thread></code> and related headers, including<br /> |
| <code><future></code>, <code><mutex></code>, <code><condition_variable></code></td> |
| <td>Provides a standard multithreading library using <code>std::thread</code> and associates</td> |
| <td><a href="http://en.cppreference.com/w/cpp/thread">Thread support library</a></td> |
| <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> |
| </tr> |
| |
| <tr> |
| <td>Weak Pointers</td> |
| <td><code>std::weak_ptr</code></td> |
| <td>Allows a weak reference to a <code>std::shared_ptr</code></td> |
| <td><a href="http://en.cppreference.com/w/cpp/memory/weak_ptr">std::weak_ptr</a></td> |
| <td>Banned because <code>std::shared_ptr</code> is banned. Use <code>base::WeakPtr</code> instead.</td> |
| </tr> |
| |
| </tbody> |
| </table> |
| |
| <h2 id="blocklist_stdlib"><a name="library-blocklist-14"></a>C++14 Banned Library Features</h2> |
| |
| <p>The following C++14 library features are not allowed in the Chromium codebase.</p> |
| |
| <table id="blocklist_lib_list" class="unlined striped"> |
| <tbody> |
| |
| <tr> |
| <th style='width:240px;'>Feature</th> |
| <th style='width:240px;'>Snippet</th> |
| <th style='width:240px;'>Description</th> |
| <th style='width:240px;'>Documentation Link</th> |
| <th style='width:240px;'>Notes and Discussion Thread</th> |
| </tr> |
| |
| <tr> |
| <td><code>std::chrono</code> literals</td> |
| <td><code>using namespace std::chrono_literals;<br>auto timeout = 30s;</code></td> |
| <td>Allows <code>std::chrono</code> types to be more easily constructed.</td> |
| <td><a href="http://en.cppreference.com/w/cpp/chrono/operator%22%22s">std::literals::chrono_literals::operator""s</a></td> |
| <td>Banned because <code><chrono></code> is banned.</td> |
| </tr> |
| |
| </tbody> |
| </table> |
| |
| </div> |
| </body> |
| </html> |
