attribute specifier sequence(since C++11)

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

C++ language

 

Declarations

Overview declaration syntax decl-specifier-seq declarator Specifiers typedef inline function specifier virtual function specifier explicit function specifier friend constexpr (C++11) storage class specifiers class union enum decltype (C++11) auto (C++11) alignas (C++11) const/volatile elaborated type specifier attributes (C++11) Declarators reference pointer array

Block declarations simple-declaration alias declaration(C++11) namespace alias definition using-declaration using-directive static_assert declaration (C++11) asm-definition 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

 

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
attribute-namespace :: identifier
identifier ( argument-list )
attribute-namespace :: identifier ( argument-list )

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

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)

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: [[likely]] 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 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.

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.

[[noreturn]]	Indicates that the function does not return. This attribute applies to function declarations only. The behavior is undefined if the function with this attribute actually returns. The following standard functions have this attribute: std::_Exit, std::abort, std::exit, std::quick_exit, std::unexpected, std::terminate, std::rethrow_exception, std::throw_with_nested, std::nested_exception::rethrow_nested
[[carries_dependency]]	Indicates that dependency chain in release-consume std::memory_order propagates in and out of the function, which allows the compiler to skip unnecessary memory fence instructions. This attribute may appear in two situations: 1) it may apply to the parameter declarations of a function or lambda-expressions, in which case it indicates that initialization of the parameter carries dependency into lvalue-to-rvalue conversion of that object. 2) It may apply to the function declaration as a whole, in which case it indicates that the return value carries dependency to the evaluation of the function call expression. This attribute must appear on the first declaration of a function or one of its parameters in any translation unit. If it is not used on the first declaration of a function or one of its parameters in another translation unit, the program is ill-formed; no diagnostic required. See std::kill_dependency for example usage
[[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. This attribute is allowed in declarations of classes, typedef-names, variables, non-static data members, functions, enumerations, and template specializations. A name declared non-deprecated may be redeclared deprecated. A name declared deprecated cannot be un-deprecated by redeclaring it without this attribute.
[[fallthrough]](C++17)	Appears in a switch statement on a line of its own (technically as an attribute of a null statement), immediately before a case label. Indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fallthrough.
[[nodiscard]](C++17)	Appears in a function declaration, enumeration declaration, or class declaration. If a function declared nodiscard or a function returning an enumeration or class declared nodiscard by value is called from a discarded-value expression other than a cast to void, the compiler is encouraged to issue a warning.
[[maybe_unused]](C++17)	Appears in the declaration of a class, a typedef­, a variable, a non­static data member, a function, an enumeration, or an enumerator. If the compiler issues warnings on unused entities, that warning is suppressed for any entity declared maybe_unused.
[[optimize_for_synchronized]](TM TS)	Appears on a declarator of a function declaration, which must be the first declaration of the function. indicates that the function definition should be optimized for invocation from a synchronized statement. In particular, it avoids serializing synchronized blocks that make a call to a function that is transaction-safe for the majority of calls, but not for all calls.

Example

Run this code

#include <cassert>
[[ noreturn ]] void f() {
  throw "error";
  // OK
}
 
[[ noreturn ]] void q(int i) {
  // behavior is undefined if called with an argument <= 0
  if (i > 0) {
    throw "positive";
  }
}
 
void f(int n) {
  void g(), h(), i();
  switch (n) {
    case 1:
    case 2:
      g();
     [[fallthrough]];
    case 3: // no warning on fallthrough
      h();
    case 4: // compiler may warn on fallthrough
      i();
      [[fallthrough]]; // ill­formed, not before a case label
  }
}
 
struct [[nodiscard]] error_info { };
error_info enable_missile_safety_mode();
void launch_missiles();
void test_missiles() {
   enable_missile_safety_mode(); // compiler may warn on discarding a nodiscard value
   launch_missiles();
}
error_info& foo();
void f1() {
    foo(); // nodiscard type is not returned by value, no warning
} 
 
 
[[maybe_unused]] void f([[maybe_unused]] bool thing1,
                        [[maybe_unused]] bool thing2)
{
   [[maybe_unused]] bool b = thing1 && thing2;
   assert(b); // in release mode, assert is compiled out, and b is unused
              // no warning because it is declared [[maybe_unused]]
} // parameters thing1 and thing2 are not used, no warning

External links

C++ attributes supported by Clang

See also

C documentation for _Noreturn