PnnnnR0
__COUNTER__

1. Introduction

The __COUNTER__ pre-defined macro is a language extension for C and C++ which expands to an integer literal that starts at 0 and increments by 1 every time it expanded in a translation unit. This is a widely-used utility that is primarily useful for generating unique identifiers with preprocessor macros.

2. Motivating Examples

A brief survey of some uses of __COUNTER__ in the C and C++ community:

• Google benchmark uses __COUNTER__ for unique identifiers, falling back to __LINE__ if __COUNTER__ isn’t present or doesn’t behave as expected

• Google Orbit uses __COUNTER__ for unique identifiers

• LLVM uses __COUNTER__ for unique identifiers as well as in sanitizer code to prevent ICF

• Catch2 uses __COUNTER__ for unique identifiers, falling back to __LINE__

• Tensorflow uses __COUNTER__ extensively, primarily for unique identifiers

• Chromium uses __COUNTER__ for unique identifier generation, e.g. in crash logging code, as well as for creating unique tags for ABORT()s

• Folly uses __COUNTER__ for unique identifiers, falling back to __LINE__ if not present

• v8 uses __COUNTER__ for unique identifiers

• Metric Panda Games uses __COUNTER__ for lookup tables as part of a localization and compile-time string hashing system.

3. Implementation Support

__COUNTER__ has long been supported by all major implementations of C and C++:

*: Supported only in --microsoft mode

Comparison: https://godbolt.org/z/vM7xsPE3M

4. Design Considerations

4.1. Precompiled Headers

MSVC and GCC save the state of __COUNTER__ in precompiled headers. GCC notes that the __COUNTER__ macro must not be expanded prior to inclusion of a pre-compiled header. If it is, then the precompiled header is not used.

This paper proposes no change to the current behavior.

4.2. Modules

GCC and MSVC do not propagate __COUNTER__ across modules, including for header units. The following compiles with a linker error due to multiple definitions of x0:

// header.hpp
#define CONCAT_IMPL(x, y) x##y
#define CONCAT(x, y) CONCAT_IMPL(x, y)
#define NEW_VAR(name) CONCAT(name, __COUNTER__)
int NEW_VAR(x); // x0
int NEW_VAR(x); // x1

// main.cpp
import "header.hpp"
int NEW_VAR(x); // x0

There are similar concerns with __TIME__ and __DATE__ macros surrounding header units, though the potential for problems is less pronounced. One option would to disallow the expansion of __COUNTER__ in header units, however, no such restriction is proposed in this proposal.

This paper proposes no change to the current behavior. Other behaviors would introduce additional complexity without clear benefit.

4.3. ODR

It’s possible to accidentally violate ODR with __COUNTER__:

// foo.hpp
#define CONCAT_IMPL(x, y) x##y
#define CONCAT(x, y) CONCAT_IMPL(x, y)
#define NEW_VAR(name) CONCAT(name, __COUNTER__)
inline void foo() {
    int NEW_VAR(x) = 2;
}

// a.cpp
#include "foo.hpp"

// b.cpp
int x = __COUNTER__;
#include "foo.hpp"

Current implementations do not make any special attempt to diagnose or prevent such use of __COUNTER__ beyond existing ODR diagnostics. Similar ODR issues can occur as a result of __DATE__ and __TIME__.

4.4. Range and Overflow

__COUNTER__ is implemented with an unsigned counter in GCC and Clang and both implementations wrap around to zero when that counter overflows. This paper recommends __COUNTER__ shall be able to attain a value of at least 2³² - 1 with an overflow behavior of wrapping to zero.

5. Proposed Wording

Proposed wording relative to [N4950]:

Insert a bullet point in [cpp.predefined/1] before bullet 1:

• __COUNTER__
  An integer literal that starts at 0 and increments by 1 each time __COUNTER__ is expanded. __COUNTER__ shall have a maximum value of at least 2³² - 1. If the value of __COUNTER__ exceeds its implementation-defined maximum value it shall reset to zero.

Insert a row into Table 22 in [cpp.predefined/1] after the row for __cpp_constinit: