Skip to content

Latest commit

 

History

History
741 lines (540 loc) · 18 KB

c++11.md

File metadata and controls

741 lines (540 loc) · 18 KB

Modern C++ use in Chromium

This document is part of the more general Chromium C++ style guide. It summarizes the supported state of new and updated language and library features in recent C++ standards and the Abseil library. This guide applies to both Chromium and its subprojects, though subprojects can choose to be more restrictive if necessary for toolchain support.

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.

You can propose changing the status of a feature by sending an email to [email protected]. 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.

If an item remains on the TBD list two years after initial support is added, style arbiters should explicitly move it to an appropriate allowlist or blocklist, allowing it if there are no obvious reasons to ban.

The current status of existing standards and Abseil features is:

  • C++11: Default allowed; see banned features below
  • C++14: Default allowed; see banned features below
  • C++17: Not yet supported in Chromium, unlikely before mid-2021; tracking bug
  • C++20: Not yet standardized
  • Abseil: Initially supported July 31, 2020; see allowed/banned/TBD features below
    • absl::StatusOr: Initially supported September 3, 2020
    • absl::Cleanup: Initially supported February 4, 2021

[TOC]

C++11 Banned Language Features {#core-blocklist}

The following C++11 language features are not allowed in the Chromium codebase.

Inline Namespaces

inline namespace foo { ... }

Description: Allows better versioning of namespaces.

Documentation: Inline namespaces

Notes: *** promo Banned in the Google Style Guide. Unclear how it will work with components.

long long Type

long long var = value;

Description: An integer of at least 64 bits.

Documentation: Fundamental types

Notes: *** promo Use a stdint.h type if you need a 64-bit number. Discussion thread

User-Defined Literals

type var = literal_value_type;

Description: Allows user-defined literal expressions.

Documentation: User-defined literals

Notes: *** promo Banned in the Google Style Guide.

thread_local Storage Class

thread_local int foo = 1;

Description: Puts variables into thread local storage.

Documentation: Storage duration

Notes: *** promo Some surprising effects on Mac (discussion, fork). Use base::SequenceLocalStorageSlot for sequence support, and base::ThreadLocal/base::ThreadLocalStorage otherwise.

C++11 Banned Library Features {#library-blocklist}

The following C++11 library features are not allowed in the Chromium codebase.

Bind Operations

std::bind(function, args, ...)

Description: Declares a function object bound to certain arguments

Documentation: std::bind

Notes: *** promo Use base::Bind instead. Compared to std::bind, base::Bind helps prevent lifetime issues by preventing binding of capturing lambdas and by forcing callers to declare raw pointers as Unretained. Discussion thread

C Floating-Point Environment

#include <cfenv>
#include <fenv.h>

Description: Provides floating point status flags and control modes for C-compatible code

Documentation: Standard library header "cfenv"

Notes: *** promo Banned by the Google Style Guide due to concerns about compiler support.

Date and time utilities

#include <chrono>

Description: A standard date and time library

Documentation: Date and time utilities

Notes: *** promo Overlaps with Time APIs in base/. Keep using the base/ classes.

Exceptions

#include <exception>

Description: Enhancements to exception throwing and handling

Documentation: Standard library header "exception"

Notes: *** promo Exceptions are banned by the Google Style Guide and disabled in Chromium compiles. However, the noexcept specifier is explicitly allowed. Discussion thread

Function Objects

std::function

Description: Wraps a standard polymorphic function

Documentation: std::function

Notes: *** promo Use base::{Once,Repeating}Callback instead. Compared to std::function, base::{Once,Repeating}Callback directly supports Chromium's refcounting classes and weak pointers and deals with additional thread safety concerns. Discussion thread

Random Number Engines

*** aside The random number engines defined in <random> (see separate item for random number distributions), e.g.: linear_congruential_engine, mersenne_twister_engine, minstd_rand0, mt19937, ranlinux48, random_device

Description: Random number generation algorithms and utilities.

Documentation: Pseudo-random number generation

Notes: *** promo Do not use any random number engines from <random>. Instead, use base::RandomBitGenerator. Discussion thread

Ratio Template Class

std::ratio<numerator, denominator>

Description: Provides compile-time rational numbers

Documentation: std::ratio

Notes: *** promo Banned by the Google Style Guide due to concerns that this is tied to a more template-heavy interface style.

Regular Expressions

#include <regex>

Description: A standard regular expressions library

Documentation: Regular expressions library

Notes: *** promo Overlaps with many regular expression libraries in Chromium. When in doubt, use re2.

Shared Pointers

std::shared_ptr

Description: Allows shared ownership of a pointer through reference counts

Documentation: std::shared_ptr

Notes: *** promo Needs a lot more evaluation for Chromium, and there isn't enough of a push for this feature.

String-Number Conversion Functions

std::stoi()
std::stol()
std::stoul()
std::stoll
std::stoull()
std::stof()
std::stod()
std::stold()
std::to_string()

Description: Converts strings to/from numbers

Documentation:

Notes: *** promo 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 base/strings/string_number_conversions.h instead.

Thread Library

*** aside <thread> and related headers, including <future>, <mutex>, <condition_variable>

Description: Provides a standard multithreading library using std::thread and associates

Documentation: Thread support library

Notes: *** promo Overlaps with many classes in base/. Keep using the base/ classes for now. base::Thread is tightly coupled to MessageLoop which would make it hard to replace. We should investigate using standard mutexes, or unique_lock, etc. to replace our locking/synchronization classes.

Weak Pointers

std::weak_ptr

Description: Allows a weak reference to a std::shared_ptr

Documentation: std::weak_ptr

Notes: *** promo Banned because std::shared_ptr is banned. Use base::WeakPtr instead.

C++14 Banned Library Features {#library-blocklist-14}

The following C++14 library features are not allowed in the Chromium codebase.

std::chrono literals

using namespace std::chrono_literals;
auto timeout = 30s;

Description: Allows std::chrono types to be more easily constructed.

Documentation: std::literals::chrono_literals::operator""s

Notes: *** promo Banned because <chrono> is banned.

Abseil Allowed Library Features {#absl-allowlist}

The following Abseil library features are allowed in the Chromium codebase.

Optional

absl::optional

Description: Early adaptation of C++17 std::optional.

Documentation: std::optional

Notes: *** promo Replaces base::Optional. Discussion thread

Status

absl::Status

Description: Type for returning detailed errors.

Documentation: status.h

Notes: *** promo Approved for use inside a wrapper type. Use abseil_string_conversions.h to convert to and from absl::string_view so the wrapper can expose base::StringPiece. Use absl::Cord directly as minimally necessary to interface; do not expose in the wrapper type API.

Discussion thread

Variant

absl::variant

Description: Early adaptation of C++17 std::variant.

Documentation: std::variant

Notes: *** promo Discussion thread

Abseil Banned Library Features {#absl-blocklist}

The following Abseil library features are not allowed in the Chromium codebase.

Any

absl::any a = int{5};
EXPECT_THAT(absl::any_cast<int>(&a), Pointee(5));
EXPECT_EQ(absl::any_cast<size_t>(&a), nullptr);

Description: Early adaptation of C++17 std::any.

Documentation: std::any

Notes: *** promo Banned since workaround for lack of RTTI isn't compatible with the component build. (Bug)

Command line flags

ABSL_FLAG(bool, logs, false, "print logs to stderr");
app --logs=true;

Description: Allows programmatic access to flag values passed on the command-line to binaries.

Documentation: Flags Library

Notes: *** promo Banned since workaround for lack of RTTI isn't compatible with the component build. (Bug) Use base::CommandLine instead.

Span

absl::Span

Description: Early adaptation of C++20 std::span.

Documentation: Using absl::Span

Notes: *** promo Banned due to being less std::-compliant than base::span. Keep using base::span.

string_view

absl::string_view

Description: Early adaptation of C++17 std::string_view.

Documentation: absl::string_view

Notes: *** promo Banned due to only working with 8-bit characters. Keep using base::StringPiece from base/strings/.

Abseil TBD Features {#absl-review}

The following Abseil library features are not allowed in the Chromium codebase. See the top of this page on how to propose moving a feature from this list into the allowed or banned sections.

128bit integer

uint64_t a;
absl::uint128 v = a;

Description: Signed and unsigned 128-bit integer types meant to mimic intrinsic types as closely as possible.

Documentation: Numerics

Notes: *** promo None

bind_front

absl::bind_front

Description: Binds the first N arguments of an invocable object and stores them by value.

Documentation:

Notes: *** promo Overlaps with base::Bind.

Cleanup

FILE* sink_file = fopen(sink_path, "w");
auto sink_closer = absl::MakeCleanup([sink_file] { fclose(sink_file); });

Description: Implements the scope guard idiom, invoking the contained callback's operator()() && on scope exit.

Documentation: cleanup.h

Notes: *** promo Similar to defer in Golang.

Containers

absl::flat_hash_map
absl::flat_hash_set
absl::node_hash_map
absl::node_hash_set
absl::btree_map
absl::btree_set
absl::btree_multimap
absl::btree_multiset
absl::InlinedVector
absl::FixedArray

Description: Alternatives to STL containers designed to be more efficient in the general case.

Documentation:

Notes: *** promo Supplements base/containers/.

Container utilities

auto it = absl::c_find(container, value);

Description: Container-based versions of algorithmic functions within C++ standard library.

Documentation: container.h

Notes: *** promo Overlaps with base/ranges/algorithm.h.

FunctionRef

absl::FunctionRef

Description: Type for holding a non-owning reference to an object of any invocable type.

Documentation: function_ref.h

Notes: *** promo None

Random

absl::BitGen bitgen;
size_t index = absl::Uniform(bitgen, 0u, elems.size());

Description: Functions and utilities for generating pseudorandom data.

Documentation: Random library

Notes: *** promo Overlaps with base/rand_util.h.

StatusOr

absl::StatusOr<T>

Description: An object that is either a usable value, or an error Status explaining why such a value is not present.

Documentation: statusor.h

Notes: *** promo None

String Formatting

absl::StrFormat

Description: A typesafe replacement for the family of printf() string formatting routines.

Documentation: String Formatting

Notes: *** promo None

Strings Library

absl::StrSplit
absl::StrJoin
absl::StrCat
absl::StrAppend
absl::Substitute
absl::StrContains

Description: Classes and utility functions for manipulating and comparing strings.

Documentation: String Utilities

Notes: *** promo Overlaps with base/strings.

Synchronization

absl::Mutex

Description: Primitives for managing tasks across different threads.

Documentation: Synchronization

Notes: *** promo Overlaps with Lock in base/synchronization/.

Time library

absl::Duration
absl::Time
absl::TimeZone
absl::CivilDay

Description: Abstractions for holding time values, both in terms of absolute time and civil time.

Documentation: Time

Notes: *** promo Overlaps with Time APIs in base/.