diff options
Diffstat (limited to 'docs/LanguageExtensions.rst')
| -rw-r--r-- | docs/LanguageExtensions.rst | 2000 |
1 files changed, 2000 insertions, 0 deletions
diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst new file mode 100644 index 000000000000..c870d20b8763 --- /dev/null +++ b/docs/LanguageExtensions.rst @@ -0,0 +1,2000 @@ +========================= +Clang Language Extensions +========================= + +.. contents:: + :local: + :depth: 1 + +.. toctree:: + :hidden: + + ObjectiveCLiterals + BlockLanguageSpec + Block-ABI-Apple + AutomaticReferenceCounting + +Introduction +============ + +This document describes the language extensions provided by Clang. In addition +to the language extensions listed here, Clang aims to support a broad range of +GCC extensions. Please see the `GCC manual +<http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on +these extensions. + +.. _langext-feature_check: + +Feature Checking Macros +======================= + +Language extensions can be very useful, but only if you know you can depend on +them. In order to allow fine-grain features checks, we support three builtin +function-like macros. This allows you to directly test for a feature in your +code without having to resort to something like autoconf or fragile "compiler +version checks". + +``__has_builtin`` +----------------- + +This function-like macro takes a single identifier argument that is the name of +a builtin function. It evaluates to 1 if the builtin is supported or 0 if not. +It can be used like this: + +.. code-block:: c++ + + #ifndef __has_builtin // Optional of course. + #define __has_builtin(x) 0 // Compatibility with non-clang compilers. + #endif + + ... + #if __has_builtin(__builtin_trap) + __builtin_trap(); + #else + abort(); + #endif + ... + +.. _langext-__has_feature-__has_extension: + +``__has_feature`` and ``__has_extension`` +----------------------------------------- + +These function-like macros take a single identifier argument that is the name +of a feature. ``__has_feature`` evaluates to 1 if the feature is both +supported by Clang and standardized in the current language standard or 0 if +not (but see :ref:`below <langext-has-feature-back-compat>`), while +``__has_extension`` evaluates to 1 if the feature is supported by Clang in the +current language (either as a language extension or a standard language +feature) or 0 if not. They can be used like this: + +.. code-block:: c++ + + #ifndef __has_feature // Optional of course. + #define __has_feature(x) 0 // Compatibility with non-clang compilers. + #endif + #ifndef __has_extension + #define __has_extension __has_feature // Compatibility with pre-3.0 compilers. + #endif + + ... + #if __has_feature(cxx_rvalue_references) + // This code will only be compiled with the -std=c++11 and -std=gnu++11 + // options, because rvalue references are only standardized in C++11. + #endif + + #if __has_extension(cxx_rvalue_references) + // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 + // and -std=gnu++98 options, because rvalue references are supported as a + // language extension in C++98. + #endif + +.. _langext-has-feature-back-compat: + +For backwards compatibility reasons, ``__has_feature`` can also be used to test +for support for non-standardized features, i.e. features not prefixed ``c_``, +``cxx_`` or ``objc_``. + +Another use of ``__has_feature`` is to check for compiler features not related +to the language standard, such as e.g. :doc:`AddressSanitizer +<AddressSanitizer>`. + +If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent +to ``__has_feature``. + +The feature tag is described along with the language feature below. + +The feature name or extension name can also be specified with a preceding and +following ``__`` (double underscore) to avoid interference from a macro with +the same name. For instance, ``__cxx_rvalue_references__`` can be used instead +of ``cxx_rvalue_references``. + +``__has_attribute`` +------------------- + +This function-like macro takes a single identifier argument that is the name of +an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It +can be used like this: + +.. code-block:: c++ + + #ifndef __has_attribute // Optional of course. + #define __has_attribute(x) 0 // Compatibility with non-clang compilers. + #endif + + ... + #if __has_attribute(always_inline) + #define ALWAYS_INLINE __attribute__((always_inline)) + #else + #define ALWAYS_INLINE + #endif + ... + +The attribute name can also be specified with a preceding and following ``__`` +(double underscore) to avoid interference from a macro with the same name. For +instance, ``__always_inline__`` can be used instead of ``always_inline``. + +Include File Checking Macros +============================ + +Not all developments systems have the same include files. The +:ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow +you to check for the existence of an include file before doing a possibly +failing ``#include`` directive. Include file checking macros must be used +as expressions in ``#if`` or ``#elif`` preprocessing directives. + +.. _langext-__has_include: + +``__has_include`` +----------------- + +This function-like macro takes a single file name string argument that is the +name of an include file. It evaluates to 1 if the file can be found using the +include paths, or 0 otherwise: + +.. code-block:: c++ + + // Note the two possible file name string formats. + #if __has_include("myinclude.h") && __has_include(<stdint.h>) + # include "myinclude.h" + #endif + + // To avoid problem with non-clang compilers not having this macro. + #if defined(__has_include) && __has_include("myinclude.h") + # include "myinclude.h" + #endif + +To test for this feature, use ``#if defined(__has_include)``. + +.. _langext-__has_include_next: + +``__has_include_next`` +---------------------- + +This function-like macro takes a single file name string argument that is the +name of an include file. It is like ``__has_include`` except that it looks for +the second instance of the given file found in the include paths. It evaluates +to 1 if the second instance of the file can be found using the include paths, +or 0 otherwise: + +.. code-block:: c++ + + // Note the two possible file name string formats. + #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>) + # include_next "myinclude.h" + #endif + + // To avoid problem with non-clang compilers not having this macro. + #if defined(__has_include_next) && __has_include_next("myinclude.h") + # include_next "myinclude.h" + #endif + +Note that ``__has_include_next``, like the GNU extension ``#include_next`` +directive, is intended for use in headers only, and will issue a warning if +used in the top-level compilation file. A warning will also be issued if an +absolute path is used in the file argument. + +``__has_warning`` +----------------- + +This function-like macro takes a string literal that represents a command line +option for a warning and returns true if that is a valid warning option. + +.. code-block:: c++ + + #if __has_warning("-Wformat") + ... + #endif + +Builtin Macros +============== + +``__BASE_FILE__`` + Defined to a string that contains the name of the main input file passed to + Clang. + +``__COUNTER__`` + Defined to an integer value that starts at zero and is incremented each time + the ``__COUNTER__`` macro is expanded. + +``__INCLUDE_LEVEL__`` + Defined to an integral value that is the include depth of the file currently + being translated. For the main file, this value is zero. + +``__TIMESTAMP__`` + Defined to the date and time of the last modification of the current source + file. + +``__clang__`` + Defined when compiling with Clang + +``__clang_major__`` + Defined to the major marketing version number of Clang (e.g., the 2 in + 2.0.1). Note that marketing version numbers should not be used to check for + language features, as different vendors use different numbering schemes. + Instead, use the :ref:`langext-feature_check`. + +``__clang_minor__`` + Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note + that marketing version numbers should not be used to check for language + features, as different vendors use different numbering schemes. Instead, use + the :ref:`langext-feature_check`. + +``__clang_patchlevel__`` + Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1). + +``__clang_version__`` + Defined to a string that captures the Clang marketing version, including the + Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``". + +.. _langext-vectors: + +Vectors and Extended Vectors +============================ + +Supports the GCC, OpenCL, AltiVec and NEON vector extensions. + +OpenCL vector types are created using ``ext_vector_type`` attribute. It +support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example +is: + +.. code-block:: c++ + + typedef float float4 __attribute__((ext_vector_type(4))); + typedef float float2 __attribute__((ext_vector_type(2))); + + float4 foo(float2 a, float2 b) { + float4 c; + c.xz = a; + c.yw = b; + return c; + } + +Query for this feature with ``__has_extension(attribute_ext_vector_type)``. + +Giving ``-faltivec`` option to clang enables support for AltiVec vector syntax +and functions. For example: + +.. code-block:: c++ + + vector float foo(vector int a) { + vector int b; + b = vec_add(a, a) + a; + return (vector float)b; + } + +NEON vector types are created using ``neon_vector_type`` and +``neon_polyvector_type`` attributes. For example: + +.. code-block:: c++ + + typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t; + typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t; + + int8x8_t foo(int8x8_t a) { + int8x8_t v; + v = a; + return v; + } + +Vector Literals +--------------- + +Vector literals can be used to create vectors from a set of scalars, or +vectors. Either parentheses or braces form can be used. In the parentheses +form the number of literal values specified must be one, i.e. referring to a +scalar value, or must match the size of the vector type being created. If a +single scalar literal value is specified, the scalar literal value will be +replicated to all the components of the vector type. In the brackets form any +number of literals can be specified. For example: + +.. code-block:: c++ + + typedef int v4si __attribute__((__vector_size__(16))); + typedef float float4 __attribute__((ext_vector_type(4))); + typedef float float2 __attribute__((ext_vector_type(2))); + + v4si vsi = (v4si){1, 2, 3, 4}; + float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); + vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). + vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). + vector int vi3 = (vector int)(1, 2); // error + vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). + vector int vi5 = (vector int)(1, 2, 3, 4); + float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); + +Vector Operations +----------------- + +The table below shows the support for each operation by vector extension. A +dash indicates that an operation is not accepted according to a corresponding +specification. + +============================== ====== ======= === ==== + Opeator OpenCL AltiVec GCC NEON +============================== ====== ======= === ==== +[] yes yes yes -- +unary operators +, -- yes yes yes -- +++, -- -- yes yes yes -- ++,--,*,/,% yes yes yes -- +bitwise operators &,|,^,~ yes yes yes -- +>>,<< yes yes yes -- +!, &&, || no -- -- -- +==, !=, >, <, >=, <= yes yes -- -- += yes yes yes yes +:? yes -- -- -- +sizeof yes yes yes yes +============================== ====== ======= === ==== + +See also :ref:`langext-__builtin_shufflevector`. + +Messages on ``deprecated`` and ``unavailable`` Attributes +========================================================= + +An optional string message can be added to the ``deprecated`` and +``unavailable`` attributes. For example: + +.. code-block:: c++ + + void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!"))); + +If the deprecated or unavailable declaration is used, the message will be +incorporated into the appropriate diagnostic: + +.. code-block:: c++ + + harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! + [-Wdeprecated-declarations] + explode(); + ^ + +Query for this feature with +``__has_extension(attribute_deprecated_with_message)`` and +``__has_extension(attribute_unavailable_with_message)``. + +Attributes on Enumerators +========================= + +Clang allows attributes to be written on individual enumerators. This allows +enumerators to be deprecated, made unavailable, etc. The attribute must appear +after the enumerator name and before any initializer, like so: + +.. code-block:: c++ + + enum OperationMode { + OM_Invalid, + OM_Normal, + OM_Terrified __attribute__((deprecated)), + OM_AbortOnError __attribute__((deprecated)) = 4 + }; + +Attributes on the ``enum`` declaration do not apply to individual enumerators. + +Query for this feature with ``__has_extension(enumerator_attributes)``. + +'User-Specified' System Frameworks +================================== + +Clang provides a mechanism by which frameworks can be built in such a way that +they will always be treated as being "system frameworks", even if they are not +present in a system framework directory. This can be useful to system +framework developers who want to be able to test building other applications +with development builds of their framework, including the manner in which the +compiler changes warning behavior for system headers. + +Framework developers can opt-in to this mechanism by creating a +"``.system_framework``" file at the top-level of their framework. That is, the +framework should have contents like: + +.. code-block:: none + + .../TestFramework.framework + .../TestFramework.framework/.system_framework + .../TestFramework.framework/Headers + .../TestFramework.framework/Headers/TestFramework.h + ... + +Clang will treat the presence of this file as an indicator that the framework +should be treated as a system framework, regardless of how it was found in the +framework search path. For consistency, we recommend that such files never be +included in installed versions of the framework. + +Availability attribute +====================== + +Clang introduces the ``availability`` attribute, which can be placed on +declarations to describe the lifecycle of that declaration relative to +operating system versions. Consider the function declaration for a +hypothetical function ``f``: + +.. code-block:: c++ + + void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); + +The availability attribute states that ``f`` was introduced in Mac OS X 10.4, +deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information +is used by Clang to determine when it is safe to use ``f``: for example, if +Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()`` +succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call +succeeds but Clang emits a warning specifying that the function is deprecated. +Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call +fails because ``f()`` is no longer available. + +The availability attribute is a comma-separated list starting with the +platform name and then including clauses specifying important milestones in the +declaration's lifetime (in any order) along with additional information. Those +clauses can be: + +introduced=\ *version* + The first version in which this declaration was introduced. + +deprecated=\ *version* + The first version in which this declaration was deprecated, meaning that + users should migrate away from this API. + +obsoleted=\ *version* + The first version in which this declaration was obsoleted, meaning that it + was removed completely and can no longer be used. + +unavailable + This declaration is never available on this platform. + +message=\ *string-literal* + Additional message text that Clang will provide when emitting a warning or + error about use of a deprecated or obsoleted declaration. Useful to direct + users to replacement APIs. + +Multiple availability attributes can be placed on a declaration, which may +correspond to different platforms. Only the availability attribute with the +platform corresponding to the target platform will be used; any others will be +ignored. If no availability attribute specifies availability for the current +target platform, the availability attributes are ignored. Supported platforms +are: + +``ios`` + Apple's iOS operating system. The minimum deployment target is specified by + the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` + command-line arguments. + +``macosx`` + Apple's Mac OS X operating system. The minimum deployment target is + specified by the ``-mmacosx-version-min=*version*`` command-line argument. + +A declaration can be used even when deploying back to a platform version prior +to when the declaration was introduced. When this happens, the declaration is +`weakly linked +<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_, +as if the ``weak_import`` attribute were added to the declaration. A +weakly-linked declaration may or may not be present a run-time, and a program +can determine whether the declaration is present by checking whether the +address of that declaration is non-NULL. + +If there are multiple declarations of the same entity, the availability +attributes must either match on a per-platform basis or later +declarations must not have availability attributes for that +platform. For example: + +.. code-block:: c + + void g(void) __attribute__((availability(macosx,introduced=10.4))); + void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches + void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform + void g(void); // okay, inherits both macosx and ios availability from above. + void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch + +When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: + +.. code-block:: objc + + @interface A + - (id)method __attribute__((availability(macosx,introduced=10.4))); + - (id)method2 __attribute__((availability(macosx,introduced=10.4))); + @end + + @interface B : A + - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later + - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4 + @end + +Checks for Standard Language Features +===================================== + +The ``__has_feature`` macro can be used to query if certain standard language +features are enabled. The ``__has_extension`` macro can be used to query if +language features are available as an extension when compiling for a standard +which does not provide them. The features which can be tested are listed here. + +C++98 +----- + +The features listed below are part of the C++98 standard. These features are +enabled by default when compiling C++ code. + +C++ exceptions +^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been +enabled. For example, compiling code with ``-fno-exceptions`` disables C++ +exceptions. + +C++ RTTI +^^^^^^^^ + +Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For +example, compiling code with ``-fno-rtti`` disables the use of RTTI. + +C++11 +----- + +The features listed below are part of the C++11 standard. As a result, all +these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option +when compiling C++ code. + +C++11 SFINAE includes access control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_access_control_sfinae)`` or +``__has_extension(cxx_access_control_sfinae)`` to determine whether +access-control errors (e.g., calling a private constructor) are considered to +be template argument deduction errors (aka SFINAE errors), per `C++ DR1170 +<http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_. + +C++11 alias templates +^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_alias_templates)`` or +``__has_extension(cxx_alias_templates)`` to determine if support for C++11's +alias declarations and alias templates is enabled. + +C++11 alignment specifiers +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to +determine if support for alignment specifiers using ``alignas`` is enabled. + +C++11 attributes +^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to +determine if support for attribute parsing with C++11's square bracket notation +is enabled. + +C++11 generalized constant expressions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized +constant expressions (e.g., ``constexpr``) is enabled. + +C++11 ``decltype()`` +^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to +determine if support for the ``decltype()`` specifier is enabled. C++11's +``decltype`` does not require type-completeness of a function call expression. +Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or +``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if +support for this feature is enabled. + +C++11 default template arguments in function templates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_default_function_template_args)`` or +``__has_extension(cxx_default_function_template_args)`` to determine if support +for default template arguments in function templates is enabled. + +C++11 ``default``\ ed functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_defaulted_functions)`` or +``__has_extension(cxx_defaulted_functions)`` to determine if support for +defaulted function definitions (with ``= default``) is enabled. + +C++11 delegating constructors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for +delegating constructors is enabled. + +C++11 ``deleted`` functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_deleted_functions)`` or +``__has_extension(cxx_deleted_functions)`` to determine if support for deleted +function definitions (with ``= delete``) is enabled. + +C++11 explicit conversion functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for +``explicit`` conversion functions is enabled. + +C++11 generalized initializers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for +generalized initializers (using braced lists and ``std::initializer_list``) is +enabled. + +C++11 implicit move constructors/assignment operators +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly +generate move constructors and move assignment operators where needed. + +C++11 inheriting constructors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for +inheriting constructors is enabled. Clang does not currently implement this +feature. + +C++11 inline namespaces +^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_inline_namespaces)`` or +``__has_extension(cxx_inline_namespaces)`` to determine if support for inline +namespaces is enabled. + +C++11 lambdas +^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to +determine if support for lambdas is enabled. + +C++11 local and unnamed types as template arguments +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_local_type_template_args)`` or +``__has_extension(cxx_local_type_template_args)`` to determine if support for +local and unnamed types as template arguments is enabled. + +C++11 noexcept +^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to +determine if support for noexcept exception specifications is enabled. + +C++11 in-class non-static data member initialization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class +initialization of non-static data members is enabled. + +C++11 ``nullptr`` +^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to +determine if support for ``nullptr`` is enabled. + +C++11 ``override control`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_override_control)`` or +``__has_extension(cxx_override_control)`` to determine if support for the +override control keywords is enabled. + +C++11 reference-qualified functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_reference_qualified_functions)`` or +``__has_extension(cxx_reference_qualified_functions)`` to determine if support +for reference-qualified functions (e.g., member functions with ``&`` or ``&&`` +applied to ``*this``) is enabled. + +C++11 range-based ``for`` loop +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to +determine if support for the range-based for loop is enabled. + +C++11 raw string literals +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw +string literals (e.g., ``R"x(foo\bar)x"``) is enabled. + +C++11 rvalue references +^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_rvalue_references)`` or +``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue +references is enabled. + +C++11 ``static_assert()`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_static_assert)`` or +``__has_extension(cxx_static_assert)`` to determine if support for compile-time +assertions using ``static_assert`` is enabled. + +C++11 type inference +^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to +determine C++11 type inference is supported using the ``auto`` specifier. If +this is disabled, ``auto`` will instead be a storage class specifier, as in C +or C++98. + +C++11 strongly typed enumerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_strong_enums)`` or +``__has_extension(cxx_strong_enums)`` to determine if support for strongly +typed, scoped enumerations is enabled. + +C++11 trailing return type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_trailing_return)`` or +``__has_extension(cxx_trailing_return)`` to determine if support for the +alternate function declaration syntax with trailing return type is enabled. + +C++11 Unicode string literals +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode +string literals is enabled. + +C++11 unrestricted unions +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for +unrestricted unions is enabled. + +C++11 user-defined literals +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_user_literals)`` to determine if support for +user-defined literals is enabled. + +C++11 variadic templates +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(cxx_variadic_templates)`` or +``__has_extension(cxx_variadic_templates)`` to determine if support for +variadic templates is enabled. + +C11 +--- + +The features listed below are part of the C11 standard. As a result, all these +features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when +compiling C code. Additionally, because these features are all +backward-compatible, they are available as extensions in all language modes. + +C11 alignment specifiers +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine +if support for alignment specifiers using ``_Alignas`` is enabled. + +C11 atomic operations +^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine +if support for atomic types using ``_Atomic`` is enabled. Clang also provides +:ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement +the ``<stdatomic.h>`` operations on ``_Atomic`` types. + +C11 generic selections +^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(c_generic_selections)`` or +``__has_extension(c_generic_selections)`` to determine if support for generic +selections is enabled. + +As an extension, the C11 generic selection expression is available in all +languages supported by Clang. The syntax is the same as that given in the C11 +standard. + +In C, type compatibility is decided according to the rules given in the +appropriate standard, but in C++, which lacks the type compatibility rules used +in C, types are considered compatible only if they are equivalent. + +C11 ``_Static_assert()`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)`` +to determine if support for compile-time assertions using ``_Static_assert`` is +enabled. + +Checks for Type Traits +====================== + +Clang supports the `GNU C++ type traits +<http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the +`Microsoft Visual C++ Type traits +<http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_. For each +supported type trait ``__X``, ``__has_extension(X)`` indicates the presence of +the type trait. For example: + +.. code-block:: c++ + + #if __has_extension(is_convertible_to) + template<typename From, typename To> + struct is_convertible_to { + static const bool value = __is_convertible_to(From, To); + }; + #else + // Emulate type trait + #endif + +The following type traits are supported by Clang: + +* ``__has_nothrow_assign`` (GNU, Microsoft) +* ``__has_nothrow_copy`` (GNU, Microsoft) +* ``__has_nothrow_constructor`` (GNU, Microsoft) +* ``__has_trivial_assign`` (GNU, Microsoft) +* ``__has_trivial_copy`` (GNU, Microsoft) +* ``__has_trivial_constructor`` (GNU, Microsoft) +* ``__has_trivial_destructor`` (GNU, Microsoft) +* ``__has_virtual_destructor`` (GNU, Microsoft) +* ``__is_abstract`` (GNU, Microsoft) +* ``__is_base_of`` (GNU, Microsoft) +* ``__is_class`` (GNU, Microsoft) +* ``__is_convertible_to`` (Microsoft) +* ``__is_empty`` (GNU, Microsoft) +* ``__is_enum`` (GNU, Microsoft) +* ``__is_interface_class`` (Microsoft) +* ``__is_pod`` (GNU, Microsoft) +* ``__is_polymorphic`` (GNU, Microsoft) +* ``__is_union`` (GNU, Microsoft) +* ``__is_literal(type)``: Determines whether the given type is a literal type +* ``__is_final``: Determines whether the given type is declared with a + ``final`` class-virt-specifier. +* ``__underlying_type(type)``: Retrieves the underlying type for a given + ``enum`` type. This trait is required to implement the C++11 standard + library. +* ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value + of type ``totype`` can be assigned to from a value of type ``fromtype`` such + that no non-trivial functions are called as part of that assignment. This + trait is required to implement the C++11 standard library. +* ``__is_trivially_constructible(type, argtypes...)``: Determines whether a + value of type ``type`` can be direct-initialized with arguments of types + ``argtypes...`` such that no non-trivial functions are called as part of + that initialization. This trait is required to implement the C++11 standard + library. + +Blocks +====== + +The syntax and high level language feature description is in +:doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for +the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`. + +Query for this feature with ``__has_extension(blocks)``. + +Objective-C Features +==================== + +Related result types +-------------------- + +According to Cocoa conventions, Objective-C methods with certain names +("``init``", "``alloc``", etc.) always return objects that are an instance of +the receiving class's type. Such methods are said to have a "related result +type", meaning that a message send to one of these methods will have the same +static type as an instance of the receiver class. For example, given the +following classes: + +.. code-block:: objc + + @interface NSObject + + (id)alloc; + - (id)init; + @end + + @interface NSArray : NSObject + @end + +and this common initialization pattern + +.. code-block:: objc + + NSArray *array = [[NSArray alloc] init]; + +the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because +``alloc`` implicitly has a related result type. Similarly, the type of the +expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a +related result type and its receiver is known to have the type ``NSArray *``. +If neither ``alloc`` nor ``init`` had a related result type, the expressions +would have had type ``id``, as declared in the method signature. + +A method with a related result type can be declared by using the type +``instancetype`` as its result type. ``instancetype`` is a contextual keyword +that is only permitted in the result type of an Objective-C method, e.g. + +.. code-block:: objc + + @interface A + + (instancetype)constructAnA; + @end + +The related result type can also be inferred for some methods. To determine +whether a method has an inferred related result type, the first word in the +camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered, +and the method will have a related result type if its return type is compatible +with the type of its class and if: + +* the first word is "``alloc``" or "``new``", and the method is a class method, + or + +* the first word is "``autorelease``", "``init``", "``retain``", or "``self``", + and the method is an instance method. + +If a method with a related result type is overridden by a subclass method, the +subclass method must also return a type that is compatible with the subclass +type. For example: + +.. code-block:: objc + + @interface NSString : NSObject + - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString + @end + +Related result types only affect the type of a message send or property access +via the given method. In all other respects, a method with a related result +type is treated the same way as method that returns ``id``. + +Use ``__has_feature(objc_instancetype)`` to determine whether the +``instancetype`` contextual keyword is available. + +Automatic reference counting +---------------------------- + +Clang provides support for :doc:`automated reference counting +<AutomaticReferenceCounting>` in Objective-C, which eliminates the need +for manual ``retain``/``release``/``autorelease`` message sends. There are two +feature macros associated with automatic reference counting: +``__has_feature(objc_arc)`` indicates the availability of automated reference +counting in general, while ``__has_feature(objc_arc_weak)`` indicates that +automated reference counting also includes support for ``__weak`` pointers to +Objective-C objects. + +.. _objc-fixed-enum: + +Enumerations with a fixed underlying type +----------------------------------------- + +Clang provides support for C++11 enumerations with a fixed underlying type +within Objective-C. For example, one can write an enumeration type as: + +.. code-block:: c++ + + typedef enum : unsigned char { Red, Green, Blue } Color; + +This specifies that the underlying type, which is used to store the enumeration +value, is ``unsigned char``. + +Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed +underlying types is available in Objective-C. + +Interoperability with C++11 lambdas +----------------------------------- + +Clang provides interoperability between C++11 lambdas and blocks-based APIs, by +permitting a lambda to be implicitly converted to a block pointer with the +corresponding signature. For example, consider an API such as ``NSArray``'s +array-sorting method: + +.. code-block:: objc + + - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; + +``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult +(^)(id, id)``, and parameters of this type are generally provided with block +literals as arguments. However, one can also use a C++11 lambda so long as it +provides the same signature (in this case, accepting two parameters of type +``id`` and returning an ``NSComparisonResult``): + +.. code-block:: objc + + NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", + @"String 02"]; + const NSStringCompareOptions comparisonOptions + = NSCaseInsensitiveSearch | NSNumericSearch | + NSWidthInsensitiveSearch | NSForcedOrderingSearch; + NSLocale *currentLocale = [NSLocale currentLocale]; + NSArray *sorted + = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult { + NSRange string1Range = NSMakeRange(0, [s1 length]); + return [s1 compare:s2 options:comparisonOptions + range:string1Range locale:currentLocale]; + }]; + NSLog(@"sorted: %@", sorted); + +This code relies on an implicit conversion from the type of the lambda +expression (an unnamed, local class type called the *closure type*) to the +corresponding block pointer type. The conversion itself is expressed by a +conversion operator in that closure type that produces a block pointer with the +same signature as the lambda itself, e.g., + +.. code-block:: objc + + operator NSComparisonResult (^)(id, id)() const; + +This conversion function returns a new block that simply forwards the two +parameters to the lambda object (which it captures by copy), then returns the +result. The returned block is first copied (with ``Block_copy``) and then +autoreleased. As an optimization, if a lambda expression is immediately +converted to a block pointer (as in the first example, above), then the block +is not copied and autoreleased: rather, it is given the same lifetime as a +block literal written at that point in the program, which avoids the overhead +of copying a block to the heap in the common case. + +The conversion from a lambda to a block pointer is only available in +Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory +management (autorelease). + +Object Literals and Subscripting +-------------------------------- + +Clang provides support for :doc:`Object Literals and Subscripting +<ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C +programming patterns, makes programs more concise, and improves the safety of +container creation. There are several feature macros associated with object +literals and subscripting: ``__has_feature(objc_array_literals)`` tests the +availability of array literals; ``__has_feature(objc_dictionary_literals)`` +tests the availability of dictionary literals; +``__has_feature(objc_subscripting)`` tests the availability of object +subscripting. + +Objective-C Autosynthesis of Properties +--------------------------------------- + +Clang provides support for autosynthesis of declared properties. Using this +feature, clang provides default synthesis of those properties not declared +@dynamic and not having user provided backing getter and setter methods. +``__has_feature(objc_default_synthesize_properties)`` checks for availability +of this feature in version of clang being used. + +.. _langext-objc_method_family: + +The ``objc_method_family`` attribute +------------------------------------ + +Many methods in Objective-C have conventional meanings determined by their +selectors. It is sometimes useful to be able to mark a method as having a +particular conventional meaning despite not having the right selector, or as +not having the conventional meaning that its selector would suggest. For these +use cases, we provide an attribute to specifically describe the "method family" +that a method belongs to. + +**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of +``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This +attribute can only be placed at the end of a method declaration: + +.. code-block:: objc + + - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); + +Users who do not wish to change the conventional meaning of a method, and who +merely want to document its non-standard retain and release semantics, should +use the :ref:`retaining behavior attributes <langext-objc-retain-release>` +described below. + +Query for this feature with ``__has_attribute(objc_method_family)``. + +.. _langext-objc-retain-release: + +Objective-C retaining behavior attributes +----------------------------------------- + +In Objective-C, functions and methods are generally assumed to follow the +`Cocoa Memory Management +<http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_ +conventions for ownership of object arguments and +return values. However, there are exceptions, and so Clang provides attributes +to allow these exceptions to be documented. This are used by ARC and the +`static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be +better described using the :ref:`objc_method_family +<langext-objc_method_family>` attribute instead. + +**Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``, +``ns_returns_autoreleased``, ``cf_returns_retained``, and +``cf_returns_not_retained`` attributes can be placed on methods and functions +that return Objective-C or CoreFoundation objects. They are commonly placed at +the end of a function prototype or method declaration: + +.. code-block:: objc + + id foo() __attribute__((ns_returns_retained)); + + - (NSString *)bar:(int)x __attribute__((ns_returns_retained)); + +The ``*_returns_retained`` attributes specify that the returned object has a +1 +retain count. The ``*_returns_not_retained`` attributes specify that the return +object has a +0 retain count, even if the normal convention for its selector +would be +1. ``ns_returns_autoreleased`` specifies that the returned object is ++0, but is guaranteed to live at least as long as the next flush of an +autorelease pool. + +**Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on +an parameter declaration; they specify that the argument is expected to have a ++1 retain count, which will be balanced in some way by the function or method. +The ``ns_consumes_self`` attribute can only be placed on an Objective-C +method; it specifies that the method expects its ``self`` parameter to have a ++1 retain count, which it will balance in some way. + +.. code-block:: objc + + void foo(__attribute__((ns_consumed)) NSString *string); + + - (void) bar __attribute__((ns_consumes_self)); + - (void) baz:(id) __attribute__((ns_consumed)) x; + +Further examples of these attributes are available in the static analyzer's `list of annotations for analysis +<http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_. + +Query for these features with ``__has_attribute(ns_consumed)``, +``__has_attribute(ns_returns_retained)``, etc. + + +Function Overloading in C +========================= + +Clang provides support for C++ function overloading in C. Function overloading +in C is introduced using the ``overloadable`` attribute. For example, one +might provide several overloaded versions of a ``tgsin`` function that invokes +the appropriate standard function computing the sine of a value with ``float``, +``double``, or ``long double`` precision: + +.. code-block:: c + + #include <math.h> + float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } + double __attribute__((overloadable)) tgsin(double x) { return sin(x); } + long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } + +Given these declarations, one can call ``tgsin`` with a ``float`` value to +receive a ``float`` result, with a ``double`` to receive a ``double`` result, +etc. Function overloading in C follows the rules of C++ function overloading +to pick the best overload given the call arguments, with a few C-specific +semantics: + +* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a + floating-point promotion (per C99) rather than as a floating-point conversion + (as in C++). + +* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is + considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are + compatible types. + +* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` + and ``U`` are compatible types. This conversion is given "conversion" rank. + +The declaration of ``overloadable`` functions is restricted to function +declarations and definitions. Most importantly, if any function with a given +name is given the ``overloadable`` attribute, then all function declarations +and definitions with that name (and in that scope) must have the +``overloadable`` attribute. This rule even applies to redeclarations of +functions whose original declaration had the ``overloadable`` attribute, e.g., + +.. code-block:: c + + int f(int) __attribute__((overloadable)); + float f(float); // error: declaration of "f" must have the "overloadable" attribute + + int g(int) __attribute__((overloadable)); + int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute + +Functions marked ``overloadable`` must have prototypes. Therefore, the +following code is ill-formed: + +.. code-block:: c + + int h() __attribute__((overloadable)); // error: h does not have a prototype + +However, ``overloadable`` functions are allowed to use a ellipsis even if there +are no named parameters (as is permitted in C++). This feature is particularly +useful when combined with the ``unavailable`` attribute: + +.. code-block:: c++ + + void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error + +Functions declared with the ``overloadable`` attribute have their names mangled +according to the same rules as C++ function names. For example, the three +``tgsin`` functions in our motivating example get the mangled names +``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two +caveats to this use of name mangling: + +* Future versions of Clang may change the name mangling of functions overloaded + in C, so you should not depend on an specific mangling. To be completely + safe, we strongly urge the use of ``static inline`` with ``overloadable`` + functions. + +* The ``overloadable`` attribute has almost no meaning when used in C++, + because names will already be mangled and functions are already overloadable. + However, when an ``overloadable`` function occurs within an ``extern "C"`` + linkage specification, it's name *will* be mangled in the same way as it + would in C. + +Query for this feature with ``__has_extension(attribute_overloadable)``. + +Initializer lists for complex numbers in C +========================================== + +clang supports an extension which allows the following in C: + +.. code-block:: c++ + + #include <math.h> + #include <complex.h> + complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) + +This construct is useful because there is no way to separately initialize the +real and imaginary parts of a complex variable in standard C, given that clang +does not support ``_Imaginary``. (Clang also supports the ``__real__`` and +``__imag__`` extensions from gcc, which help in some cases, but are not usable +in static initializers.) + +Note that this extension does not allow eliding the braces; the meaning of the +following two lines is different: + +.. code-block:: c++ + + complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) + complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) + +This extension also works in C++ mode, as far as that goes, but does not apply +to the C++ ``std::complex``. (In C++11, list initialization allows the same +syntax to be used with ``std::complex`` with the same meaning.) + +Builtin Functions +================= + +Clang supports a number of builtin library functions with the same syntax as +GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``, +``__builtin_choose_expr``, ``__builtin_types_compatible_p``, +``__sync_fetch_and_add``, etc. In addition to the GCC builtins, Clang supports +a number of builtins that GCC does not, which are listed here. + +Please note that Clang does not and will not support all of the GCC builtins +for vector operations. Instead of using builtins, you should use the functions +defined in target-specific header files like ``<xmmintrin.h>``, which define +portable wrappers for these. Many of the Clang versions of these functions are +implemented directly in terms of :ref:`extended vector support +<langext-vectors>` instead of builtins, in order to reduce the number of +builtins that we need to implement. + +``__builtin_readcyclecounter`` +------------------------------ + +``__builtin_readcyclecounter`` is used to access the cycle counter register (or +a similar low-latency, high-accuracy clock) on those targets that support it. + +**Syntax**: + +.. code-block:: c++ + + __builtin_readcyclecounter() + +**Example of Use**: + +.. code-block:: c++ + + unsigned long long t0 = __builtin_readcyclecounter(); + do_something(); + unsigned long long t1 = __builtin_readcyclecounter(); + unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow + +**Description**: + +The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value, +which may be either global or process/thread-specific depending on the target. +As the backing counters often overflow quickly (on the order of seconds) this +should only be used for timing small intervals. When not supported by the +target, the return value is always zero. This builtin takes no arguments and +produces an unsigned long long result. + +Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. + +.. _langext-__builtin_shufflevector: + +``__builtin_shufflevector`` +--------------------------- + +``__builtin_shufflevector`` is used to express generic vector +permutation/shuffle/swizzle operations. This builtin is also very important +for the implementation of various target-specific header files like +``<xmmintrin.h>``. + +**Syntax**: + +.. code-block:: c++ + + __builtin_shufflevector(vec1, vec2, index1, index2, ...) + +**Examples**: + +.. code-block:: c++ + + // Identity operation - return 4-element vector V1. + __builtin_shufflevector(V1, V1, 0, 1, 2, 3) + + // "Splat" element 0 of V1 into a 4-element result. + __builtin_shufflevector(V1, V1, 0, 0, 0, 0) + + // Reverse 4-element vector V1. + __builtin_shufflevector(V1, V1, 3, 2, 1, 0) + + // Concatenate every other element of 4-element vectors V1 and V2. + __builtin_shufflevector(V1, V2, 0, 2, 4, 6) + + // Concatenate every other element of 8-element vectors V1 and V2. + __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) + +**Description**: + +The first two arguments to ``__builtin_shufflevector`` are vectors that have +the same element type. The remaining arguments are a list of integers that +specify the elements indices of the first two vectors that should be extracted +and returned in a new vector. These element indices are numbered sequentially +starting with the first vector, continuing into the second vector. Thus, if +``vec1`` is a 4-element vector, index 5 would refer to the second element of +``vec2``. + +The result of ``__builtin_shufflevector`` is a vector with the same element +type as ``vec1``/``vec2`` but that has an element count equal to the number of +indices specified. + +Query for this feature with ``__has_builtin(__builtin_shufflevector)``. + +``__builtin_unreachable`` +------------------------- + +``__builtin_unreachable`` is used to indicate that a specific point in the +program cannot be reached, even if the compiler might otherwise think it can. +This is useful to improve optimization and eliminates certain warnings. For +example, without the ``__builtin_unreachable`` in the example below, the +compiler assumes that the inline asm can fall through and prints a "function +declared '``noreturn``' should not return" warning. + +**Syntax**: + +.. code-block:: c++ + + __builtin_unreachable() + +**Example of use**: + +.. code-block:: c++ + + void myabort(void) __attribute__((noreturn)); + void myabort(void) { + asm("int3"); + __builtin_unreachable(); + } + +**Description**: + +The ``__builtin_unreachable()`` builtin has completely undefined behavior. +Since it has undefined behavior, it is a statement that it is never reached and +the optimizer can take advantage of this to produce better code. This builtin +takes no arguments and produces a void result. + +Query for this feature with ``__has_builtin(__builtin_unreachable)``. + +``__sync_swap`` +--------------- + +``__sync_swap`` is used to atomically swap integers or pointers in memory. + +**Syntax**: + +.. code-block:: c++ + + type __sync_swap(type *ptr, type value, ...) + +**Example of Use**: + +.. code-block:: c++ + + int old_value = __sync_swap(&value, new_value); + +**Description**: + +The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of +atomic intrinsics to allow code to atomically swap the current value with the +new value. More importantly, it helps developers write more efficient and +correct code by avoiding expensive loops around +``__sync_bool_compare_and_swap()`` or relying on the platform specific +implementation details of ``__sync_lock_test_and_set()``. The +``__sync_swap()`` builtin is a full barrier. + +Multiprecision Arithmetic Builtins +---------------------------------- + +Clang provides a set of builtins which expose multiprecision arithmetic in a +manner amenable to C. They all have the following form: + +.. code-block:: c + + unsigned x = ..., y = ..., carryin = ..., carryout; + unsigned sum = __builtin_addc(x, y, carryin, &carryout); + +Thus one can form a multiprecision addition chain in the following manner: + +.. code-block:: c + + unsigned *x, *y, *z, carryin=0, carryout; + z[0] = __builtin_addc(x[0], y[0], carryin, &carryout); + carryin = carryout; + z[1] = __builtin_addc(x[1], y[1], carryin, &carryout); + carryin = carryout; + z[2] = __builtin_addc(x[2], y[2], carryin, &carryout); + carryin = carryout; + z[3] = __builtin_addc(x[3], y[3], carryin, &carryout); + +The complete list of builtins are: + +.. code-block:: c + + unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); + unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); + unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); + unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); + unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); + unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); + unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); + unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); + +.. _langext-__c11_atomic: + +__c11_atomic builtins +--------------------- + +Clang provides a set of builtins which are intended to be used to implement +C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the +``_explicit`` form of the corresponding C11 operation, and are named with a +``__c11_`` prefix. The supported operations are: + +* ``__c11_atomic_init`` +* ``__c11_atomic_thread_fence`` +* ``__c11_atomic_signal_fence`` +* ``__c11_atomic_is_lock_free`` +* ``__c11_atomic_store`` +* ``__c11_atomic_load`` +* ``__c11_atomic_exchange`` +* ``__c11_atomic_compare_exchange_strong`` +* ``__c11_atomic_compare_exchange_weak`` +* ``__c11_atomic_fetch_add`` +* ``__c11_atomic_fetch_sub`` +* ``__c11_atomic_fetch_and`` +* ``__c11_atomic_fetch_or`` +* ``__c11_atomic_fetch_xor`` + +Non-standard C++11 Attributes +============================= + +Clang's non-standard C++11 attributes live in the ``clang`` attribute +namespace. + +The ``clang::fallthrough`` attribute +------------------------------------ + +The ``clang::fallthrough`` attribute is used along with the +``-Wimplicit-fallthrough`` argument to annotate intentional fall-through +between switch labels. It can only be applied to a null statement placed at a +point of execution between any statement and the next switch label. It is +common to mark these places with a specific comment, but this attribute is +meant to replace comments with a more strict annotation, which can be checked +by the compiler. This attribute doesn't change semantics of the code and can +be used wherever an intended fall-through occurs. It is designed to mimic +control-flow statements like ``break;``, so it can be placed in most places +where ``break;`` can, but only if there are no statements on the execution path +between it and the next switch label. + +Here is an example: + +.. code-block:: c++ + + // compile with -Wimplicit-fallthrough + switch (n) { + case 22: + case 33: // no warning: no statements between case labels + f(); + case 44: // warning: unannotated fall-through + g(); + [[clang::fallthrough]]; + case 55: // no warning + if (x) { + h(); + break; + } + else { + i(); + [[clang::fallthrough]]; + } + case 66: // no warning + p(); + [[clang::fallthrough]]; // warning: fallthrough annotation does not + // directly precede case label + q(); + case 77: // warning: unannotated fall-through + r(); + } + +``gnu::`` attributes +-------------------- + +Clang also supports GCC's ``gnu`` attribute namespace. All GCC attributes which +are accepted with the ``__attribute__((foo))`` syntax are also accepted as +``[[gnu::foo]]``. This only extends to attributes which are specified by GCC +(see the list of `GCC function attributes +<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable +attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and +`GCC type attributes +<http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_. As with the GCC +implementation, these attributes must appertain to the *declarator-id* in a +declaration, which means they must go either at the start of the declaration or +immediately after the name being declared. + +For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and +also applies the GNU ``noreturn`` attribute to ``f``. + +.. code-block:: c++ + + [[gnu::unused]] int a, f [[gnu::noreturn]] (); + +Target-Specific Extensions +========================== + +Clang supports some language features conditionally on some targets. + +X86/X86-64 Language Extensions +------------------------------ + +The X86 backend has these language extensions: + +Memory references off the GS segment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Annotating a pointer with address space #256 causes it to be code generated +relative to the X86 GS segment register, and address space #257 causes it to be +relative to the X86 FS segment. Note that this is a very very low-level +feature that should only be used if you know what you're doing (for example in +an OS kernel). + +Here is an example: + +.. code-block:: c++ + + #define GS_RELATIVE __attribute__((address_space(256))) + int foo(int GS_RELATIVE *P) { + return *P; + } + +Which compiles to (on X86-32): + +.. code-block:: gas + + _foo: + movl 4(%esp), %eax + movl %gs:(%eax), %eax + ret + +Extensions for Static Analysis +============================== + +Clang supports additional attributes that are useful for documenting program +invariants and rules for static analysis tools, such as the `Clang Static +Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented +in the analyzer's `list of source-level annotations +<http://clang-analyzer.llvm.org/annotations.html>`_. + + +Extensions for Dynamic Analysis +=============================== + +.. _langext-address_sanitizer: + +AddressSanitizer +---------------- + +Use ``__has_feature(address_sanitizer)`` to check if the code is being built +with :doc:`AddressSanitizer`. + +Use ``__attribute__((no_sanitize_address))`` +on a function declaration +to specify that address safety instrumentation (e.g. AddressSanitizer) should +not be applied to that function. + +.. _langext-thread_sanitizer: + +ThreadSanitizer +---------------- + +Use ``__has_feature(thread_sanitizer)`` to check if the code is being built +with :doc:`ThreadSanitizer`. + +Use ``__attribute__((no_sanitize_thread))`` on a function declaration +to specify that checks for data races on plain (non-atomic) memory accesses +should not be inserted by ThreadSanitizer. +The function may still be instrumented by the tool +to avoid false positives in other places. + +.. _langext-memory_sanitizer: + +MemorySanitizer +---------------- +Use ``__has_feature(memory_sanitizer)`` to check if the code is being built +with :doc:`MemorySanitizer`. + +Use ``__attribute__((no_sanitize_memory))`` on a function declaration +to specify that checks for uninitialized memory should not be inserted +(e.g. by MemorySanitizer). The function may still be instrumented by the tool +to avoid false positives in other places. + + +Thread-Safety Annotation Checking +================================= + +Clang supports additional attributes for checking basic locking policies in +multithreaded programs. Clang currently parses the following list of +attributes, although **the implementation for these annotations is currently in +development.** For more details, see the `GCC implementation +<http://gcc.gnu.org/wiki/ThreadSafetyAnnotation>`_. + +``no_thread_safety_analysis`` +----------------------------- + +Use ``__attribute__((no_thread_safety_analysis))`` on a function declaration to +specify that the thread safety analysis should not be run on that function. +This attribute provides an escape hatch (e.g. for situations when it is +difficult to annotate the locking policy). + +``lockable`` +------------ + +Use ``__attribute__((lockable))`` on a class definition to specify that it has +a lockable type (e.g. a Mutex class). This annotation is primarily used to +check consistency. + +``scoped_lockable`` +------------------- + +Use ``__attribute__((scoped_lockable))`` on a class definition to specify that +it has a "scoped" lockable type. Objects of this type will acquire the lock +upon construction and release it upon going out of scope. This annotation is +primarily used to check consistency. + +``guarded_var`` +--------------- + +Use ``__attribute__((guarded_var))`` on a variable declaration to specify that +the variable must be accessed while holding some lock. + +``pt_guarded_var`` +------------------ + +Use ``__attribute__((pt_guarded_var))`` on a pointer declaration to specify +that the pointer must be dereferenced while holding some lock. + +``guarded_by(l)`` +----------------- + +Use ``__attribute__((guarded_by(l)))`` on a variable declaration to specify +that the variable must be accessed while holding lock ``l``. + +``pt_guarded_by(l)`` +-------------------- + +Use ``__attribute__((pt_guarded_by(l)))`` on a pointer declaration to specify +that the pointer must be dereferenced while holding lock ``l``. + +``acquired_before(...)`` +------------------------ + +Use ``__attribute__((acquired_before(...)))`` on a declaration of a lockable +variable to specify that the lock must be acquired before all attribute +arguments. Arguments must be lockable type, and there must be at least one +argument. + +``acquired_after(...)`` +----------------------- + +Use ``__attribute__((acquired_after(...)))`` on a declaration of a lockable +variable to specify that the lock must be acquired after all attribute +arguments. Arguments must be lockable type, and there must be at least one +argument. + +``exclusive_lock_function(...)`` +-------------------------------- + +Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration +to specify that the function acquires all listed locks exclusively. This +attribute takes zero or more arguments: either of lockable type or integers +indexing into function parameters of lockable type. If no arguments are given, +the acquired lock is implicitly ``this`` of the enclosing object. + +``shared_lock_function(...)`` +----------------------------- + +Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to +specify that the function acquires all listed locks, although the locks may be +shared (e.g. read locks). This attribute takes zero or more arguments: either +of lockable type or integers indexing into function parameters of lockable +type. If no arguments are given, the acquired lock is implicitly ``this`` of +the enclosing object. + +``exclusive_trylock_function(...)`` +----------------------------------- + +Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration +to specify that the function will try (without blocking) to acquire all listed +locks exclusively. This attribute takes one or more arguments. The first +argument is an integer or boolean value specifying the return value of a +successful lock acquisition. The remaining arugments are either of lockable +type or integers indexing into function parameters of lockable type. If only +one argument is given, the acquired lock is implicitly ``this`` of the +enclosing object. + +``shared_trylock_function(...)`` +-------------------------------- + +Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to +specify that the function will try (without blocking) to acquire all listed +locks, although the locks may be shared (e.g. read locks). This attribute +takes one or more arguments. The first argument is an integer or boolean value +specifying the return value of a successful lock acquisition. The remaining +arugments are either of lockable type or integers indexing into function +parameters of lockable type. If only one argument is given, the acquired lock +is implicitly ``this`` of the enclosing object. + +``unlock_function(...)`` +------------------------ + +Use ``__attribute__((unlock_function(...)))`` on a function declaration to +specify that the function release all listed locks. This attribute takes zero +or more arguments: either of lockable type or integers indexing into function +parameters of lockable type. If no arguments are given, the acquired lock is +implicitly ``this`` of the enclosing object. + +``lock_returned(l)`` +-------------------- + +Use ``__attribute__((lock_returned(l)))`` on a function declaration to specify +that the function returns lock ``l`` (``l`` must be of lockable type). This +annotation is used to aid in resolving lock expressions. + +``locks_excluded(...)`` +----------------------- + +Use ``__attribute__((locks_excluded(...)))`` on a function declaration to +specify that the function must not be called with the listed locks. Arguments +must be lockable type, and there must be at least one argument. + +``exclusive_locks_required(...)`` +--------------------------------- + +Use ``__attribute__((exclusive_locks_required(...)))`` on a function +declaration to specify that the function must be called while holding the +listed exclusive locks. Arguments must be lockable type, and there must be at +least one argument. + +``shared_locks_required(...)`` +------------------------------ + +Use ``__attribute__((shared_locks_required(...)))`` on a function declaration +to specify that the function must be called while holding the listed shared +locks. Arguments must be lockable type, and there must be at least one +argument. + +Type Safety Checking +==================== + +Clang supports additional attributes to enable checking type safety properties +that can't be enforced by C type system. Usecases include: + +* MPI library implementations, where these attributes enable checking that + buffer type matches the passed ``MPI_Datatype``; +* for HDF5 library there is a similar usecase as MPI; +* checking types of variadic functions' arguments for functions like + ``fcntl()`` and ``ioctl()``. + +You can detect support for these attributes with ``__has_attribute()``. For +example: + +.. code-block:: c++ + + #if defined(__has_attribute) + # if __has_attribute(argument_with_type_tag) && \ + __has_attribute(pointer_with_type_tag) && \ + __has_attribute(type_tag_for_datatype) + # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) + /* ... other macros ... */ + # endif + #endif + + #if !defined(ATTR_MPI_PWT) + # define ATTR_MPI_PWT(buffer_idx, type_idx) + #endif + + int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) + ATTR_MPI_PWT(1,3); + +``argument_with_type_tag(...)`` +------------------------------- + +Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, +type_tag_idx)))`` on a function declaration to specify that the function +accepts a type tag that determines the type of some other argument. +``arg_kind`` is an identifier that should be used when annotating all +applicable type tags. + +This attribute is primarily useful for checking arguments of variadic functions +(``pointer_with_type_tag`` can be used in most of non-variadic cases). + +For example: + +.. code-block:: c++ + + int fcntl(int fd, int cmd, ...) + __attribute__(( argument_with_type_tag(fcntl,3,2) )); + +``pointer_with_type_tag(...)`` +------------------------------ + +Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` +on a function declaration to specify that the function accepts a type tag that +determines the pointee type of some other pointer argument. + +For example: + +.. code-block:: c++ + + int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) + __attribute__(( pointer_with_type_tag(mpi,1,3) )); + +``type_tag_for_datatype(...)`` +------------------------------ + +Clang supports annotating type tags of two forms. + +* **Type tag that is an expression containing a reference to some declared + identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a + declaration with that identifier: + + .. code-block:: c++ + + extern struct mpi_datatype mpi_datatype_int + __attribute__(( type_tag_for_datatype(mpi,int) )); + #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) + +* **Type tag that is an integral literal.** Introduce a ``static const`` + variable with a corresponding initializer value and attach + ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration, + for example: + + .. code-block:: c++ + + #define MPI_INT ((MPI_Datatype) 42) + static const MPI_Datatype mpi_datatype_int + __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 + +The attribute also accepts an optional third argument that determines how the +expression is compared to the type tag. There are two supported flags: + +* ``layout_compatible`` will cause types to be compared according to + layout-compatibility rules (C++11 [class.mem] p 17, 18). This is + implemented to support annotating types like ``MPI_DOUBLE_INT``. + + For example: + + .. code-block:: c++ + + /* In mpi.h */ + struct internal_mpi_double_int { double d; int i; }; + extern struct mpi_datatype mpi_datatype_double_int + __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) )); + + #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) + + /* In user code */ + struct my_pair { double a; int b; }; + struct my_pair *buffer; + MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning + + struct my_int_pair { int a; int b; } + struct my_int_pair *buffer2; + MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element + // type 'struct my_int_pair' + // doesn't match specified MPI_Datatype + +* ``must_be_null`` specifies that the expression should be a null pointer + constant, for example: + + .. code-block:: c++ + + /* In mpi.h */ + extern struct mpi_datatype mpi_datatype_null + __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); + + #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) + + /* In user code */ + MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL + // was specified but buffer + // is not a null pointer + +Format String Checking +====================== + +Clang supports the ``format`` attribute, which indicates that the function +accepts a ``printf`` or ``scanf``-like format string and corresponding +arguments or a ``va_list`` that contains these arguments. + +Please see `GCC documentation about format attribute +<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details +about attribute syntax. + +Clang implements two kinds of checks with this attribute. + +#. Clang checks that the function with the ``format`` attribute is called with + a format string that uses format specifiers that are allowed, and that + arguments match the format string. This is the ``-Wformat`` warning, it is + on by default. + +#. Clang checks that the format string argument is a literal string. This is + the ``-Wformat-nonliteral`` warning, it is off by default. + + Clang implements this mostly the same way as GCC, but there is a difference + for functions that accept a ``va_list`` argument (for example, ``vprintf``). + GCC does not emit ``-Wformat-nonliteral`` warning for calls to such + fuctions. Clang does not warn if the format string comes from a function + parameter, where the function is annotated with a compatible attribute, + otherwise it warns. For example: + + .. code-block:: c + + __attribute__((__format__ (__scanf__, 1, 3))) + void foo(const char* s, char *buf, ...) { + va_list ap; + va_start(ap, buf); + + vprintf(s, ap); // warning: format string is not a string literal + } + + In this case we warn because ``s`` contains a format string for a + ``scanf``-like function, but it is passed to a ``printf``-like function. + + If the attribute is removed, clang still warns, because the format string is + not a string literal. + + Another example: + + .. code-block:: c + + __attribute__((__format__ (__printf__, 1, 3))) + void foo(const char* s, char *buf, ...) { + va_list ap; + va_start(ap, buf); + + vprintf(s, ap); // warning + } + + In this case Clang does not warn because the format string ``s`` and + the corresponding arguments are annotated. If the arguments are + incorrect, the caller of ``foo`` will receive a warning. |