attribute specifier sequence(since C++11)

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

C++ language

 

Declarations

Overview declaration syntax decl-specifier-seq declarator Specifiers typedef inline virtual function specifier explicit function specifier friend constexpr (C++11) consteval (C++20) constinit (C++20) storage class specifiers classstruct union enum decltype (C++11) auto (C++11) alignas (C++11) constvolatile elaborated type specifier attributes (C++11)

Declarators reference pointer array Block declarations simple-declaration → structured binding declaration (C++17) alias declaration(C++11) namespace alias definition using-declaration using-directive static_assert declaration (C++11) asm-declaration opaque enum declaration(C++11) Other declarations namespace definition function declaration class template declaration function template declaration explicit template instantiation(C++11) explicit template specialization linkage specification attribute declaration (C++11) empty declaration

 

Attributes

noreturn‎ (C++11)

carries_dependency (C++11)

deprecated (C++14)

fallthrough (C++17)

nodiscard (C++17)

maybe_unused (C++17)

likelyunlikely (C++20)(C++20)

no_unique_address (C++20)

optimize_for_synchronized (TM TS)

 

Introduces implementation-defined attributes for types, objects, code, etc.

[[attr]] [[attr1, attr2, attr3(args)]] [[namespace::attr(args)]] alignas_specifier

Formally, the syntax is

[[ attribute-list ]]		(since C++11)
[[ using attribute-namespace : attribute-list ]]		(since C++17)

where attribute-list is a comma-separated sequence of zero or more attributes (possibly ending with an ellipsis ... indicating a pack expansion)

identifier	(1)
attribute-namespace :: identifier	(2)
identifier ( argument-list )	(3)
attribute-namespace :: identifier ( argument-list )	(4)

1) simple attribute, such as [[noreturn]]

2) attribute with a namespace, such as [[gnu::unused]]

3) attribute with arguments, such as [[deprecated("because")]]

4) attribute with both a namespace and an argument list

Explanation

Attributes provide the unified standard syntax for implementation-defined language extensions, such as the GNU and IBM language extensions __attribute__((...)), Microsoft extension __declspec(), etc.

An attribute can be used almost everywhere in the C++ program, and can be applied to almost everything: to types, to variables, to functions, to names, to code blocks, to entire translation units, although each particular attribute is only valid where it is permitted by the implementation: [[expect_true]] could be an attribute that can only be used with an if, and not with a class declaration. [[omp::parallel()]] could be an attribute that applies to a code block or to a for loop, but not to the type int, etc. (note these two attributes are fictional examples, see below for the standard and some non-standard attributes)

In declarations, attributes may appear both before the whole declaration and directly after the name of the entity that is declared, in which case they are combined. In most other situations, attributes apply to the directly preceding entity.

The alignas specifier is a part of the attribute specifier sequence, although it has different syntax. It may appear where the [[...]] attributes appear and may mix with them (provided it is used where alignas is permitted)

Two consecutive left square bracket tokens ([[) may only appear when introducing an attribute-specifier or inside an attribute argument.

void f() {
  int y[3];
  y[[] { return 0; }()] = 1;  // error
  int i [[cats::meow([[]])]]; // OK
}

Besides the standard attributes listed below, implementations may support arbitrary non-standard attributes with implementation-defined behavior. All attributes unknown to an implementation are ignored without causing an error. (since C++17)

Standard attributes

Only the following attributes are defined by the C++ standard.

If using: namespace appears in the beginning of an attribute list, no other attributes in the attribute list can specify a namespace: the namespace specified in a using applies to them all: [[using CC: opt(1), debug]] // same as [[CC::opt(1), CC::debug]] [[using CC: CC::opt(1)]] // error: cannot combine using and scoped attribute

(since C++17)

[[noreturn]]	indicates that the function does not return
[[carries_dependency]]	indicates that dependency chain in release-consume std::memory_order propagates in and out of the function
[[deprecated]](C++14) [[deprecated("reason")]](C++14)	indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some reason
[[fallthrough]](C++17)	indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fall-through
[[nodiscard]](C++17) [[nodiscard("reason")]](C++20)	encourages the compiler to issue a warning if the return value is discarded
[[maybe_unused]](C++17)	suppresses compiler warnings on unused entities, if any
[[likely]](C++20) [[unlikely]](C++20)	indicates that the compiler should optimize for the case where a path of execution through a statement is more or less likely than any other path of execution
[[no_unique_address]](C++20)	indicates that a non-static data member need not have an address distinct from all other non-static data members of its class
[[optimize_for_synchronized]](TM TS)	indicates that the function definition should be optimized for invocation from a synchronized statement

Example

Run this code

[[gnu::always_inline]] [[gnu::hot]] [[gnu::const]] [[nodiscard]]
inline int f(); // declare f with four attributes
 
[[gnu::always_inline, gnu::const, gnu::hot, nodiscard]]
int f(); // same as above, but uses a single attr specifier that contains four attributes
 
// C++17:
[[using gnu : const, always_inline, hot]] [[nodiscard]]
int f[[gnu::always_inline]](); // an attribute may appear in multiple specifiers
 
int f() { return 0; }
 
int main()
{
}

External links

C++ attributes supported by Clang