1========================= 2Clang Language Extensions 3========================= 4 5.. contents:: 6 :local: 7 :depth: 1 8 9.. toctree:: 10 :hidden: 11 12 ObjectiveCLiterals 13 BlockLanguageSpec 14 Block-ABI-Apple 15 AutomaticReferenceCounting 16 17Introduction 18============ 19 20This document describes the language extensions provided by Clang. In addition 21to the language extensions listed here, Clang aims to support a broad range of 22GCC extensions. Please see the `GCC manual 23<http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on 24these extensions. 25 26.. _langext-feature_check: 27 28Feature Checking Macros 29======================= 30 31Language extensions can be very useful, but only if you know you can depend on 32them. In order to allow fine-grain features checks, we support three builtin 33function-like macros. This allows you to directly test for a feature in your 34code without having to resort to something like autoconf or fragile "compiler 35version checks". 36 37``__has_builtin`` 38----------------- 39 40This function-like macro takes a single identifier argument that is the name of 41a builtin function. It evaluates to 1 if the builtin is supported or 0 if not. 42It can be used like this: 43 44.. code-block:: c++ 45 46 #ifndef __has_builtin // Optional of course. 47 #define __has_builtin(x) 0 // Compatibility with non-clang compilers. 48 #endif 49 50 ... 51 #if __has_builtin(__builtin_trap) 52 __builtin_trap(); 53 #else 54 abort(); 55 #endif 56 ... 57 58.. _langext-__has_feature-__has_extension: 59 60``__has_feature`` and ``__has_extension`` 61----------------------------------------- 62 63These function-like macros take a single identifier argument that is the name 64of a feature. ``__has_feature`` evaluates to 1 if the feature is both 65supported by Clang and standardized in the current language standard or 0 if 66not (but see :ref:`below <langext-has-feature-back-compat>`), while 67``__has_extension`` evaluates to 1 if the feature is supported by Clang in the 68current language (either as a language extension or a standard language 69feature) or 0 if not. They can be used like this: 70 71.. code-block:: c++ 72 73 #ifndef __has_feature // Optional of course. 74 #define __has_feature(x) 0 // Compatibility with non-clang compilers. 75 #endif 76 #ifndef __has_extension 77 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers. 78 #endif 79 80 ... 81 #if __has_feature(cxx_rvalue_references) 82 // This code will only be compiled with the -std=c++11 and -std=gnu++11 83 // options, because rvalue references are only standardized in C++11. 84 #endif 85 86 #if __has_extension(cxx_rvalue_references) 87 // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 88 // and -std=gnu++98 options, because rvalue references are supported as a 89 // language extension in C++98. 90 #endif 91 92.. _langext-has-feature-back-compat: 93 94For backward compatibility, ``__has_feature`` can also be used to test 95for support for non-standardized features, i.e. features not prefixed ``c_``, 96``cxx_`` or ``objc_``. 97 98Another use of ``__has_feature`` is to check for compiler features not related 99to the language standard, such as e.g. :doc:`AddressSanitizer 100<AddressSanitizer>`. 101 102If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent 103to ``__has_feature``. 104 105The feature tag is described along with the language feature below. 106 107The feature name or extension name can also be specified with a preceding and 108following ``__`` (double underscore) to avoid interference from a macro with 109the same name. For instance, ``__cxx_rvalue_references__`` can be used instead 110of ``cxx_rvalue_references``. 111 112``__has_cpp_attribute`` 113----------------------- 114 115This function-like macro takes a single argument that is the name of a 116C++11-style attribute. The argument can either be a single identifier, or a 117scoped identifier. If the attribute is supported, a nonzero value is returned. 118If the attribute is a standards-based attribute, this macro returns a nonzero 119value based on the year and month in which the attribute was voted into the 120working draft. If the attribute is not supported by the current compliation 121target, this macro evaluates to 0. It can be used like this: 122 123.. code-block:: c++ 124 125 #ifndef __has_cpp_attribute // Optional of course. 126 #define __has_cpp_attribute(x) 0 // Compatibility with non-clang compilers. 127 #endif 128 129 ... 130 #if __has_cpp_attribute(clang::fallthrough) 131 #define FALLTHROUGH [[clang::fallthrough]] 132 #else 133 #define FALLTHROUGH 134 #endif 135 ... 136 137The attribute identifier (but not scope) can also be specified with a preceding 138and following ``__`` (double underscore) to avoid interference from a macro with 139the same name. For instance, ``gnu::__const__`` can be used instead of 140``gnu::const``. 141 142``__has_attribute`` 143------------------- 144 145This function-like macro takes a single identifier argument that is the name of 146a GNU-style attribute. It evaluates to 1 if the attribute is supported by the 147current compilation target, or 0 if not. It can be used like this: 148 149.. code-block:: c++ 150 151 #ifndef __has_attribute // Optional of course. 152 #define __has_attribute(x) 0 // Compatibility with non-clang compilers. 153 #endif 154 155 ... 156 #if __has_attribute(always_inline) 157 #define ALWAYS_INLINE __attribute__((always_inline)) 158 #else 159 #define ALWAYS_INLINE 160 #endif 161 ... 162 163The attribute name can also be specified with a preceding and following ``__`` 164(double underscore) to avoid interference from a macro with the same name. For 165instance, ``__always_inline__`` can be used instead of ``always_inline``. 166 167 168``__has_declspec_attribute`` 169---------------------------- 170 171This function-like macro takes a single identifier argument that is the name of 172an attribute implemented as a Microsoft-style ``__declspec`` attribute. It 173evaluates to 1 if the attribute is supported by the current compilation target, 174or 0 if not. It can be used like this: 175 176.. code-block:: c++ 177 178 #ifndef __has_declspec_attribute // Optional of course. 179 #define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers. 180 #endif 181 182 ... 183 #if __has_declspec_attribute(dllexport) 184 #define DLLEXPORT __declspec(dllexport) 185 #else 186 #define DLLEXPORT 187 #endif 188 ... 189 190The attribute name can also be specified with a preceding and following ``__`` 191(double underscore) to avoid interference from a macro with the same name. For 192instance, ``__dllexport__`` can be used instead of ``dllexport``. 193 194``__is_identifier`` 195------------------- 196 197This function-like macro takes a single identifier argument that might be either 198a reserved word or a regular identifier. It evaluates to 1 if the argument is just 199a regular identifier and not a reserved word, in the sense that it can then be 200used as the name of a user-defined function or variable. Otherwise it evaluates 201to 0. It can be used like this: 202 203.. code-block:: c++ 204 205 ... 206 #ifdef __is_identifier // Compatibility with non-clang compilers. 207 #if __is_identifier(__wchar_t) 208 typedef wchar_t __wchar_t; 209 #endif 210 #endif 211 212 __wchar_t WideCharacter; 213 ... 214 215Include File Checking Macros 216============================ 217 218Not all developments systems have the same include files. The 219:ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow 220you to check for the existence of an include file before doing a possibly 221failing ``#include`` directive. Include file checking macros must be used 222as expressions in ``#if`` or ``#elif`` preprocessing directives. 223 224.. _langext-__has_include: 225 226``__has_include`` 227----------------- 228 229This function-like macro takes a single file name string argument that is the 230name of an include file. It evaluates to 1 if the file can be found using the 231include paths, or 0 otherwise: 232 233.. code-block:: c++ 234 235 // Note the two possible file name string formats. 236 #if __has_include("myinclude.h") && __has_include(<stdint.h>) 237 # include "myinclude.h" 238 #endif 239 240To test for this feature, use ``#if defined(__has_include)``: 241 242.. code-block:: c++ 243 244 // To avoid problem with non-clang compilers not having this macro. 245 #if defined(__has_include) 246 #if __has_include("myinclude.h") 247 # include "myinclude.h" 248 #endif 249 #endif 250 251.. _langext-__has_include_next: 252 253``__has_include_next`` 254---------------------- 255 256This function-like macro takes a single file name string argument that is the 257name of an include file. It is like ``__has_include`` except that it looks for 258the second instance of the given file found in the include paths. It evaluates 259to 1 if the second instance of the file can be found using the include paths, 260or 0 otherwise: 261 262.. code-block:: c++ 263 264 // Note the two possible file name string formats. 265 #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>) 266 # include_next "myinclude.h" 267 #endif 268 269 // To avoid problem with non-clang compilers not having this macro. 270 #if defined(__has_include_next) 271 #if __has_include_next("myinclude.h") 272 # include_next "myinclude.h" 273 #endif 274 #endif 275 276Note that ``__has_include_next``, like the GNU extension ``#include_next`` 277directive, is intended for use in headers only, and will issue a warning if 278used in the top-level compilation file. A warning will also be issued if an 279absolute path is used in the file argument. 280 281``__has_warning`` 282----------------- 283 284This function-like macro takes a string literal that represents a command line 285option for a warning and returns true if that is a valid warning option. 286 287.. code-block:: c++ 288 289 #if __has_warning("-Wformat") 290 ... 291 #endif 292 293Builtin Macros 294============== 295 296``__BASE_FILE__`` 297 Defined to a string that contains the name of the main input file passed to 298 Clang. 299 300``__COUNTER__`` 301 Defined to an integer value that starts at zero and is incremented each time 302 the ``__COUNTER__`` macro is expanded. 303 304``__INCLUDE_LEVEL__`` 305 Defined to an integral value that is the include depth of the file currently 306 being translated. For the main file, this value is zero. 307 308``__TIMESTAMP__`` 309 Defined to the date and time of the last modification of the current source 310 file. 311 312``__clang__`` 313 Defined when compiling with Clang 314 315``__clang_major__`` 316 Defined to the major marketing version number of Clang (e.g., the 2 in 317 2.0.1). Note that marketing version numbers should not be used to check for 318 language features, as different vendors use different numbering schemes. 319 Instead, use the :ref:`langext-feature_check`. 320 321``__clang_minor__`` 322 Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note 323 that marketing version numbers should not be used to check for language 324 features, as different vendors use different numbering schemes. Instead, use 325 the :ref:`langext-feature_check`. 326 327``__clang_patchlevel__`` 328 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1). 329 330``__clang_version__`` 331 Defined to a string that captures the Clang marketing version, including the 332 Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``". 333 334.. _langext-vectors: 335 336Vectors and Extended Vectors 337============================ 338 339Supports the GCC, OpenCL, AltiVec and NEON vector extensions. 340 341OpenCL vector types are created using ``ext_vector_type`` attribute. It 342support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example 343is: 344 345.. code-block:: c++ 346 347 typedef float float4 __attribute__((ext_vector_type(4))); 348 typedef float float2 __attribute__((ext_vector_type(2))); 349 350 float4 foo(float2 a, float2 b) { 351 float4 c; 352 c.xz = a; 353 c.yw = b; 354 return c; 355 } 356 357Query for this feature with ``__has_extension(attribute_ext_vector_type)``. 358 359Giving ``-faltivec`` option to clang enables support for AltiVec vector syntax 360and functions. For example: 361 362.. code-block:: c++ 363 364 vector float foo(vector int a) { 365 vector int b; 366 b = vec_add(a, a) + a; 367 return (vector float)b; 368 } 369 370NEON vector types are created using ``neon_vector_type`` and 371``neon_polyvector_type`` attributes. For example: 372 373.. code-block:: c++ 374 375 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t; 376 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t; 377 378 int8x8_t foo(int8x8_t a) { 379 int8x8_t v; 380 v = a; 381 return v; 382 } 383 384Vector Literals 385--------------- 386 387Vector literals can be used to create vectors from a set of scalars, or 388vectors. Either parentheses or braces form can be used. In the parentheses 389form the number of literal values specified must be one, i.e. referring to a 390scalar value, or must match the size of the vector type being created. If a 391single scalar literal value is specified, the scalar literal value will be 392replicated to all the components of the vector type. In the brackets form any 393number of literals can be specified. For example: 394 395.. code-block:: c++ 396 397 typedef int v4si __attribute__((__vector_size__(16))); 398 typedef float float4 __attribute__((ext_vector_type(4))); 399 typedef float float2 __attribute__((ext_vector_type(2))); 400 401 v4si vsi = (v4si){1, 2, 3, 4}; 402 float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); 403 vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). 404 vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). 405 vector int vi3 = (vector int)(1, 2); // error 406 vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). 407 vector int vi5 = (vector int)(1, 2, 3, 4); 408 float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); 409 410Vector Operations 411----------------- 412 413The table below shows the support for each operation by vector extension. A 414dash indicates that an operation is not accepted according to a corresponding 415specification. 416 417============================== ======= ======= ======= ======= 418 Operator OpenCL AltiVec GCC NEON 419============================== ======= ======= ======= ======= 420[] yes yes yes -- 421unary operators +, -- yes yes yes -- 422++, -- -- yes yes yes -- 423+,--,*,/,% yes yes yes -- 424bitwise operators &,|,^,~ yes yes yes -- 425>>,<< yes yes yes -- 426!, &&, || yes -- -- -- 427==, !=, >, <, >=, <= yes yes -- -- 428= yes yes yes yes 429:? yes -- -- -- 430sizeof yes yes yes yes 431C-style cast yes yes yes no 432reinterpret_cast yes no yes no 433static_cast yes no yes no 434const_cast no no no no 435============================== ======= ======= ======= ======= 436 437See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`. 438 439Messages on ``deprecated`` and ``unavailable`` Attributes 440========================================================= 441 442An optional string message can be added to the ``deprecated`` and 443``unavailable`` attributes. For example: 444 445.. code-block:: c++ 446 447 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!"))); 448 449If the deprecated or unavailable declaration is used, the message will be 450incorporated into the appropriate diagnostic: 451 452.. code-block:: none 453 454 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! 455 [-Wdeprecated-declarations] 456 explode(); 457 ^ 458 459Query for this feature with 460``__has_extension(attribute_deprecated_with_message)`` and 461``__has_extension(attribute_unavailable_with_message)``. 462 463Attributes on Enumerators 464========================= 465 466Clang allows attributes to be written on individual enumerators. This allows 467enumerators to be deprecated, made unavailable, etc. The attribute must appear 468after the enumerator name and before any initializer, like so: 469 470.. code-block:: c++ 471 472 enum OperationMode { 473 OM_Invalid, 474 OM_Normal, 475 OM_Terrified __attribute__((deprecated)), 476 OM_AbortOnError __attribute__((deprecated)) = 4 477 }; 478 479Attributes on the ``enum`` declaration do not apply to individual enumerators. 480 481Query for this feature with ``__has_extension(enumerator_attributes)``. 482 483'User-Specified' System Frameworks 484================================== 485 486Clang provides a mechanism by which frameworks can be built in such a way that 487they will always be treated as being "system frameworks", even if they are not 488present in a system framework directory. This can be useful to system 489framework developers who want to be able to test building other applications 490with development builds of their framework, including the manner in which the 491compiler changes warning behavior for system headers. 492 493Framework developers can opt-in to this mechanism by creating a 494"``.system_framework``" file at the top-level of their framework. That is, the 495framework should have contents like: 496 497.. code-block:: none 498 499 .../TestFramework.framework 500 .../TestFramework.framework/.system_framework 501 .../TestFramework.framework/Headers 502 .../TestFramework.framework/Headers/TestFramework.h 503 ... 504 505Clang will treat the presence of this file as an indicator that the framework 506should be treated as a system framework, regardless of how it was found in the 507framework search path. For consistency, we recommend that such files never be 508included in installed versions of the framework. 509 510Checks for Standard Language Features 511===================================== 512 513The ``__has_feature`` macro can be used to query if certain standard language 514features are enabled. The ``__has_extension`` macro can be used to query if 515language features are available as an extension when compiling for a standard 516which does not provide them. The features which can be tested are listed here. 517 518Since Clang 3.4, the C++ SD-6 feature test macros are also supported. 519These are macros with names of the form ``__cpp_<feature_name>``, and are 520intended to be a portable way to query the supported features of the compiler. 521See `the C++ status page <http://clang.llvm.org/cxx_status.html#ts>`_ for 522information on the version of SD-6 supported by each Clang release, and the 523macros provided by that revision of the recommendations. 524 525C++98 526----- 527 528The features listed below are part of the C++98 standard. These features are 529enabled by default when compiling C++ code. 530 531C++ exceptions 532^^^^^^^^^^^^^^ 533 534Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been 535enabled. For example, compiling code with ``-fno-exceptions`` disables C++ 536exceptions. 537 538C++ RTTI 539^^^^^^^^ 540 541Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For 542example, compiling code with ``-fno-rtti`` disables the use of RTTI. 543 544C++11 545----- 546 547The features listed below are part of the C++11 standard. As a result, all 548these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option 549when compiling C++ code. 550 551C++11 SFINAE includes access control 552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 553 554Use ``__has_feature(cxx_access_control_sfinae)`` or 555``__has_extension(cxx_access_control_sfinae)`` to determine whether 556access-control errors (e.g., calling a private constructor) are considered to 557be template argument deduction errors (aka SFINAE errors), per `C++ DR1170 558<http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_. 559 560C++11 alias templates 561^^^^^^^^^^^^^^^^^^^^^ 562 563Use ``__has_feature(cxx_alias_templates)`` or 564``__has_extension(cxx_alias_templates)`` to determine if support for C++11's 565alias declarations and alias templates is enabled. 566 567C++11 alignment specifiers 568^^^^^^^^^^^^^^^^^^^^^^^^^^ 569 570Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to 571determine if support for alignment specifiers using ``alignas`` is enabled. 572 573Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to 574determine if support for the ``alignof`` keyword is enabled. 575 576C++11 attributes 577^^^^^^^^^^^^^^^^ 578 579Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to 580determine if support for attribute parsing with C++11's square bracket notation 581is enabled. 582 583C++11 generalized constant expressions 584^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 585 586Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized 587constant expressions (e.g., ``constexpr``) is enabled. 588 589C++11 ``decltype()`` 590^^^^^^^^^^^^^^^^^^^^ 591 592Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to 593determine if support for the ``decltype()`` specifier is enabled. C++11's 594``decltype`` does not require type-completeness of a function call expression. 595Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or 596``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if 597support for this feature is enabled. 598 599C++11 default template arguments in function templates 600^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 601 602Use ``__has_feature(cxx_default_function_template_args)`` or 603``__has_extension(cxx_default_function_template_args)`` to determine if support 604for default template arguments in function templates is enabled. 605 606C++11 ``default``\ ed functions 607^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 608 609Use ``__has_feature(cxx_defaulted_functions)`` or 610``__has_extension(cxx_defaulted_functions)`` to determine if support for 611defaulted function definitions (with ``= default``) is enabled. 612 613C++11 delegating constructors 614^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 615 616Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for 617delegating constructors is enabled. 618 619C++11 ``deleted`` functions 620^^^^^^^^^^^^^^^^^^^^^^^^^^^ 621 622Use ``__has_feature(cxx_deleted_functions)`` or 623``__has_extension(cxx_deleted_functions)`` to determine if support for deleted 624function definitions (with ``= delete``) is enabled. 625 626C++11 explicit conversion functions 627^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 628 629Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for 630``explicit`` conversion functions is enabled. 631 632C++11 generalized initializers 633^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 634 635Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for 636generalized initializers (using braced lists and ``std::initializer_list``) is 637enabled. 638 639C++11 implicit move constructors/assignment operators 640^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 641 642Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly 643generate move constructors and move assignment operators where needed. 644 645C++11 inheriting constructors 646^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 647 648Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for 649inheriting constructors is enabled. 650 651C++11 inline namespaces 652^^^^^^^^^^^^^^^^^^^^^^^ 653 654Use ``__has_feature(cxx_inline_namespaces)`` or 655``__has_extension(cxx_inline_namespaces)`` to determine if support for inline 656namespaces is enabled. 657 658C++11 lambdas 659^^^^^^^^^^^^^ 660 661Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to 662determine if support for lambdas is enabled. 663 664C++11 local and unnamed types as template arguments 665^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 666 667Use ``__has_feature(cxx_local_type_template_args)`` or 668``__has_extension(cxx_local_type_template_args)`` to determine if support for 669local and unnamed types as template arguments is enabled. 670 671C++11 noexcept 672^^^^^^^^^^^^^^ 673 674Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to 675determine if support for noexcept exception specifications is enabled. 676 677C++11 in-class non-static data member initialization 678^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 679 680Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class 681initialization of non-static data members is enabled. 682 683C++11 ``nullptr`` 684^^^^^^^^^^^^^^^^^ 685 686Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to 687determine if support for ``nullptr`` is enabled. 688 689C++11 ``override control`` 690^^^^^^^^^^^^^^^^^^^^^^^^^^ 691 692Use ``__has_feature(cxx_override_control)`` or 693``__has_extension(cxx_override_control)`` to determine if support for the 694override control keywords is enabled. 695 696C++11 reference-qualified functions 697^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 698 699Use ``__has_feature(cxx_reference_qualified_functions)`` or 700``__has_extension(cxx_reference_qualified_functions)`` to determine if support 701for reference-qualified functions (e.g., member functions with ``&`` or ``&&`` 702applied to ``*this``) is enabled. 703 704C++11 range-based ``for`` loop 705^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 706 707Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to 708determine if support for the range-based for loop is enabled. 709 710C++11 raw string literals 711^^^^^^^^^^^^^^^^^^^^^^^^^ 712 713Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw 714string literals (e.g., ``R"x(foo\bar)x"``) is enabled. 715 716C++11 rvalue references 717^^^^^^^^^^^^^^^^^^^^^^^ 718 719Use ``__has_feature(cxx_rvalue_references)`` or 720``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue 721references is enabled. 722 723C++11 ``static_assert()`` 724^^^^^^^^^^^^^^^^^^^^^^^^^ 725 726Use ``__has_feature(cxx_static_assert)`` or 727``__has_extension(cxx_static_assert)`` to determine if support for compile-time 728assertions using ``static_assert`` is enabled. 729 730C++11 ``thread_local`` 731^^^^^^^^^^^^^^^^^^^^^^ 732 733Use ``__has_feature(cxx_thread_local)`` to determine if support for 734``thread_local`` variables is enabled. 735 736C++11 type inference 737^^^^^^^^^^^^^^^^^^^^ 738 739Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to 740determine C++11 type inference is supported using the ``auto`` specifier. If 741this is disabled, ``auto`` will instead be a storage class specifier, as in C 742or C++98. 743 744C++11 strongly typed enumerations 745^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 746 747Use ``__has_feature(cxx_strong_enums)`` or 748``__has_extension(cxx_strong_enums)`` to determine if support for strongly 749typed, scoped enumerations is enabled. 750 751C++11 trailing return type 752^^^^^^^^^^^^^^^^^^^^^^^^^^ 753 754Use ``__has_feature(cxx_trailing_return)`` or 755``__has_extension(cxx_trailing_return)`` to determine if support for the 756alternate function declaration syntax with trailing return type is enabled. 757 758C++11 Unicode string literals 759^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 760 761Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode 762string literals is enabled. 763 764C++11 unrestricted unions 765^^^^^^^^^^^^^^^^^^^^^^^^^ 766 767Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for 768unrestricted unions is enabled. 769 770C++11 user-defined literals 771^^^^^^^^^^^^^^^^^^^^^^^^^^^ 772 773Use ``__has_feature(cxx_user_literals)`` to determine if support for 774user-defined literals is enabled. 775 776C++11 variadic templates 777^^^^^^^^^^^^^^^^^^^^^^^^ 778 779Use ``__has_feature(cxx_variadic_templates)`` or 780``__has_extension(cxx_variadic_templates)`` to determine if support for 781variadic templates is enabled. 782 783C++1y 784----- 785 786The features listed below are part of the committee draft for the C++1y 787standard. As a result, all these features are enabled with the ``-std=c++1y`` 788or ``-std=gnu++1y`` option when compiling C++ code. 789 790C++1y binary literals 791^^^^^^^^^^^^^^^^^^^^^ 792 793Use ``__has_feature(cxx_binary_literals)`` or 794``__has_extension(cxx_binary_literals)`` to determine whether 795binary literals (for instance, ``0b10010``) are recognized. Clang supports this 796feature as an extension in all language modes. 797 798C++1y contextual conversions 799^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 800 801Use ``__has_feature(cxx_contextual_conversions)`` or 802``__has_extension(cxx_contextual_conversions)`` to determine if the C++1y rules 803are used when performing an implicit conversion for an array bound in a 804*new-expression*, the operand of a *delete-expression*, an integral constant 805expression, or a condition in a ``switch`` statement. 806 807C++1y decltype(auto) 808^^^^^^^^^^^^^^^^^^^^ 809 810Use ``__has_feature(cxx_decltype_auto)`` or 811``__has_extension(cxx_decltype_auto)`` to determine if support 812for the ``decltype(auto)`` placeholder type is enabled. 813 814C++1y default initializers for aggregates 815^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 816 817Use ``__has_feature(cxx_aggregate_nsdmi)`` or 818``__has_extension(cxx_aggregate_nsdmi)`` to determine if support 819for default initializers in aggregate members is enabled. 820 821C++1y digit separators 822^^^^^^^^^^^^^^^^^^^^^^ 823 824Use ``__cpp_digit_separators`` to determine if support for digit separators 825using single quotes (for instance, ``10'000``) is enabled. At this time, there 826is no corresponding ``__has_feature`` name 827 828C++1y generalized lambda capture 829^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 830 831Use ``__has_feature(cxx_init_captures)`` or 832``__has_extension(cxx_init_captures)`` to determine if support for 833lambda captures with explicit initializers is enabled 834(for instance, ``[n(0)] { return ++n; }``). 835 836C++1y generic lambdas 837^^^^^^^^^^^^^^^^^^^^^ 838 839Use ``__has_feature(cxx_generic_lambdas)`` or 840``__has_extension(cxx_generic_lambdas)`` to determine if support for generic 841(polymorphic) lambdas is enabled 842(for instance, ``[] (auto x) { return x + 1; }``). 843 844C++1y relaxed constexpr 845^^^^^^^^^^^^^^^^^^^^^^^ 846 847Use ``__has_feature(cxx_relaxed_constexpr)`` or 848``__has_extension(cxx_relaxed_constexpr)`` to determine if variable 849declarations, local variable modification, and control flow constructs 850are permitted in ``constexpr`` functions. 851 852C++1y return type deduction 853^^^^^^^^^^^^^^^^^^^^^^^^^^^ 854 855Use ``__has_feature(cxx_return_type_deduction)`` or 856``__has_extension(cxx_return_type_deduction)`` to determine if support 857for return type deduction for functions (using ``auto`` as a return type) 858is enabled. 859 860C++1y runtime-sized arrays 861^^^^^^^^^^^^^^^^^^^^^^^^^^ 862 863Use ``__has_feature(cxx_runtime_array)`` or 864``__has_extension(cxx_runtime_array)`` to determine if support 865for arrays of runtime bound (a restricted form of variable-length arrays) 866is enabled. 867Clang's implementation of this feature is incomplete. 868 869C++1y variable templates 870^^^^^^^^^^^^^^^^^^^^^^^^ 871 872Use ``__has_feature(cxx_variable_templates)`` or 873``__has_extension(cxx_variable_templates)`` to determine if support for 874templated variable declarations is enabled. 875 876C11 877--- 878 879The features listed below are part of the C11 standard. As a result, all these 880features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when 881compiling C code. Additionally, because these features are all 882backward-compatible, they are available as extensions in all language modes. 883 884C11 alignment specifiers 885^^^^^^^^^^^^^^^^^^^^^^^^ 886 887Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine 888if support for alignment specifiers using ``_Alignas`` is enabled. 889 890Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine 891if support for the ``_Alignof`` keyword is enabled. 892 893C11 atomic operations 894^^^^^^^^^^^^^^^^^^^^^ 895 896Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine 897if support for atomic types using ``_Atomic`` is enabled. Clang also provides 898:ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement 899the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use 900``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header 901is available. 902 903Clang will use the system's ``<stdatomic.h>`` header when one is available, and 904will otherwise use its own. When using its own, implementations of the atomic 905operations are provided as macros. In the cases where C11 also requires a real 906function, this header provides only the declaration of that function (along 907with a shadowing macro implementation), and you must link to a library which 908provides a definition of the function if you use it instead of the macro. 909 910C11 generic selections 911^^^^^^^^^^^^^^^^^^^^^^ 912 913Use ``__has_feature(c_generic_selections)`` or 914``__has_extension(c_generic_selections)`` to determine if support for generic 915selections is enabled. 916 917As an extension, the C11 generic selection expression is available in all 918languages supported by Clang. The syntax is the same as that given in the C11 919standard. 920 921In C, type compatibility is decided according to the rules given in the 922appropriate standard, but in C++, which lacks the type compatibility rules used 923in C, types are considered compatible only if they are equivalent. 924 925C11 ``_Static_assert()`` 926^^^^^^^^^^^^^^^^^^^^^^^^ 927 928Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)`` 929to determine if support for compile-time assertions using ``_Static_assert`` is 930enabled. 931 932C11 ``_Thread_local`` 933^^^^^^^^^^^^^^^^^^^^^ 934 935Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)`` 936to determine if support for ``_Thread_local`` variables is enabled. 937 938Modules 939------- 940 941Use ``__has_feature(modules)`` to determine if Modules have been enabled. 942For example, compiling code with ``-fmodules`` enables the use of Modules. 943 944More information could be found `here <http://clang.llvm.org/docs/Modules.html>`_. 945 946Checks for Type Trait Primitives 947================================ 948 949Type trait primitives are special builtin constant expressions that can be used 950by the standard C++ library to facilitate or simplify the implementation of 951user-facing type traits in the <type_traits> header. 952 953They are not intended to be used directly by user code because they are 954implementation-defined and subject to change -- as such they're tied closely to 955the supported set of system headers, currently: 956 957* LLVM's own libc++ 958* GNU libstdc++ 959* The Microsoft standard C++ library 960 961Clang supports the `GNU C++ type traits 962<http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the 963`Microsoft Visual C++ Type traits 964<http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_. 965 966Feature detection is supported only for some of the primitives at present. User 967code should not use these checks because they bear no direct relation to the 968actual set of type traits supported by the C++ standard library. 969 970For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the 971type trait primitive in the compiler. A simplistic usage example as might be 972seen in standard C++ headers follows: 973 974.. code-block:: c++ 975 976 #if __has_extension(is_convertible_to) 977 template<typename From, typename To> 978 struct is_convertible_to { 979 static const bool value = __is_convertible_to(From, To); 980 }; 981 #else 982 // Emulate type trait for compatibility with other compilers. 983 #endif 984 985The following type trait primitives are supported by Clang: 986 987* ``__has_nothrow_assign`` (GNU, Microsoft) 988* ``__has_nothrow_copy`` (GNU, Microsoft) 989* ``__has_nothrow_constructor`` (GNU, Microsoft) 990* ``__has_trivial_assign`` (GNU, Microsoft) 991* ``__has_trivial_copy`` (GNU, Microsoft) 992* ``__has_trivial_constructor`` (GNU, Microsoft) 993* ``__has_trivial_destructor`` (GNU, Microsoft) 994* ``__has_virtual_destructor`` (GNU, Microsoft) 995* ``__is_abstract`` (GNU, Microsoft) 996* ``__is_base_of`` (GNU, Microsoft) 997* ``__is_class`` (GNU, Microsoft) 998* ``__is_convertible_to`` (Microsoft) 999* ``__is_empty`` (GNU, Microsoft) 1000* ``__is_enum`` (GNU, Microsoft) 1001* ``__is_interface_class`` (Microsoft) 1002* ``__is_pod`` (GNU, Microsoft) 1003* ``__is_polymorphic`` (GNU, Microsoft) 1004* ``__is_union`` (GNU, Microsoft) 1005* ``__is_literal(type)``: Determines whether the given type is a literal type 1006* ``__is_final``: Determines whether the given type is declared with a 1007 ``final`` class-virt-specifier. 1008* ``__underlying_type(type)``: Retrieves the underlying type for a given 1009 ``enum`` type. This trait is required to implement the C++11 standard 1010 library. 1011* ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value 1012 of type ``totype`` can be assigned to from a value of type ``fromtype`` such 1013 that no non-trivial functions are called as part of that assignment. This 1014 trait is required to implement the C++11 standard library. 1015* ``__is_trivially_constructible(type, argtypes...)``: Determines whether a 1016 value of type ``type`` can be direct-initialized with arguments of types 1017 ``argtypes...`` such that no non-trivial functions are called as part of 1018 that initialization. This trait is required to implement the C++11 standard 1019 library. 1020* ``__is_destructible`` (MSVC 2013) 1021* ``__is_nothrow_destructible`` (MSVC 2013) 1022* ``__is_nothrow_assignable`` (MSVC 2013, clang) 1023* ``__is_constructible`` (MSVC 2013, clang) 1024* ``__is_nothrow_constructible`` (MSVC 2013, clang) 1025* ``__is_assignable`` (MSVC 2015, clang) 1026 1027Blocks 1028====== 1029 1030The syntax and high level language feature description is in 1031:doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for 1032the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`. 1033 1034Query for this feature with ``__has_extension(blocks)``. 1035 1036Objective-C Features 1037==================== 1038 1039Related result types 1040-------------------- 1041 1042According to Cocoa conventions, Objective-C methods with certain names 1043("``init``", "``alloc``", etc.) always return objects that are an instance of 1044the receiving class's type. Such methods are said to have a "related result 1045type", meaning that a message send to one of these methods will have the same 1046static type as an instance of the receiver class. For example, given the 1047following classes: 1048 1049.. code-block:: objc 1050 1051 @interface NSObject 1052 + (id)alloc; 1053 - (id)init; 1054 @end 1055 1056 @interface NSArray : NSObject 1057 @end 1058 1059and this common initialization pattern 1060 1061.. code-block:: objc 1062 1063 NSArray *array = [[NSArray alloc] init]; 1064 1065the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because 1066``alloc`` implicitly has a related result type. Similarly, the type of the 1067expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a 1068related result type and its receiver is known to have the type ``NSArray *``. 1069If neither ``alloc`` nor ``init`` had a related result type, the expressions 1070would have had type ``id``, as declared in the method signature. 1071 1072A method with a related result type can be declared by using the type 1073``instancetype`` as its result type. ``instancetype`` is a contextual keyword 1074that is only permitted in the result type of an Objective-C method, e.g. 1075 1076.. code-block:: objc 1077 1078 @interface A 1079 + (instancetype)constructAnA; 1080 @end 1081 1082The related result type can also be inferred for some methods. To determine 1083whether a method has an inferred related result type, the first word in the 1084camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered, 1085and the method will have a related result type if its return type is compatible 1086with the type of its class and if: 1087 1088* the first word is "``alloc``" or "``new``", and the method is a class method, 1089 or 1090 1091* the first word is "``autorelease``", "``init``", "``retain``", or "``self``", 1092 and the method is an instance method. 1093 1094If a method with a related result type is overridden by a subclass method, the 1095subclass method must also return a type that is compatible with the subclass 1096type. For example: 1097 1098.. code-block:: objc 1099 1100 @interface NSString : NSObject 1101 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString 1102 @end 1103 1104Related result types only affect the type of a message send or property access 1105via the given method. In all other respects, a method with a related result 1106type is treated the same way as method that returns ``id``. 1107 1108Use ``__has_feature(objc_instancetype)`` to determine whether the 1109``instancetype`` contextual keyword is available. 1110 1111Automatic reference counting 1112---------------------------- 1113 1114Clang provides support for :doc:`automated reference counting 1115<AutomaticReferenceCounting>` in Objective-C, which eliminates the need 1116for manual ``retain``/``release``/``autorelease`` message sends. There are two 1117feature macros associated with automatic reference counting: 1118``__has_feature(objc_arc)`` indicates the availability of automated reference 1119counting in general, while ``__has_feature(objc_arc_weak)`` indicates that 1120automated reference counting also includes support for ``__weak`` pointers to 1121Objective-C objects. 1122 1123.. _objc-fixed-enum: 1124 1125Enumerations with a fixed underlying type 1126----------------------------------------- 1127 1128Clang provides support for C++11 enumerations with a fixed underlying type 1129within Objective-C. For example, one can write an enumeration type as: 1130 1131.. code-block:: c++ 1132 1133 typedef enum : unsigned char { Red, Green, Blue } Color; 1134 1135This specifies that the underlying type, which is used to store the enumeration 1136value, is ``unsigned char``. 1137 1138Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed 1139underlying types is available in Objective-C. 1140 1141Interoperability with C++11 lambdas 1142----------------------------------- 1143 1144Clang provides interoperability between C++11 lambdas and blocks-based APIs, by 1145permitting a lambda to be implicitly converted to a block pointer with the 1146corresponding signature. For example, consider an API such as ``NSArray``'s 1147array-sorting method: 1148 1149.. code-block:: objc 1150 1151 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; 1152 1153``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult 1154(^)(id, id)``, and parameters of this type are generally provided with block 1155literals as arguments. However, one can also use a C++11 lambda so long as it 1156provides the same signature (in this case, accepting two parameters of type 1157``id`` and returning an ``NSComparisonResult``): 1158 1159.. code-block:: objc 1160 1161 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", 1162 @"String 02"]; 1163 const NSStringCompareOptions comparisonOptions 1164 = NSCaseInsensitiveSearch | NSNumericSearch | 1165 NSWidthInsensitiveSearch | NSForcedOrderingSearch; 1166 NSLocale *currentLocale = [NSLocale currentLocale]; 1167 NSArray *sorted 1168 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult { 1169 NSRange string1Range = NSMakeRange(0, [s1 length]); 1170 return [s1 compare:s2 options:comparisonOptions 1171 range:string1Range locale:currentLocale]; 1172 }]; 1173 NSLog(@"sorted: %@", sorted); 1174 1175This code relies on an implicit conversion from the type of the lambda 1176expression (an unnamed, local class type called the *closure type*) to the 1177corresponding block pointer type. The conversion itself is expressed by a 1178conversion operator in that closure type that produces a block pointer with the 1179same signature as the lambda itself, e.g., 1180 1181.. code-block:: objc 1182 1183 operator NSComparisonResult (^)(id, id)() const; 1184 1185This conversion function returns a new block that simply forwards the two 1186parameters to the lambda object (which it captures by copy), then returns the 1187result. The returned block is first copied (with ``Block_copy``) and then 1188autoreleased. As an optimization, if a lambda expression is immediately 1189converted to a block pointer (as in the first example, above), then the block 1190is not copied and autoreleased: rather, it is given the same lifetime as a 1191block literal written at that point in the program, which avoids the overhead 1192of copying a block to the heap in the common case. 1193 1194The conversion from a lambda to a block pointer is only available in 1195Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory 1196management (autorelease). 1197 1198Object Literals and Subscripting 1199-------------------------------- 1200 1201Clang provides support for :doc:`Object Literals and Subscripting 1202<ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C 1203programming patterns, makes programs more concise, and improves the safety of 1204container creation. There are several feature macros associated with object 1205literals and subscripting: ``__has_feature(objc_array_literals)`` tests the 1206availability of array literals; ``__has_feature(objc_dictionary_literals)`` 1207tests the availability of dictionary literals; 1208``__has_feature(objc_subscripting)`` tests the availability of object 1209subscripting. 1210 1211Objective-C Autosynthesis of Properties 1212--------------------------------------- 1213 1214Clang provides support for autosynthesis of declared properties. Using this 1215feature, clang provides default synthesis of those properties not declared 1216@dynamic and not having user provided backing getter and setter methods. 1217``__has_feature(objc_default_synthesize_properties)`` checks for availability 1218of this feature in version of clang being used. 1219 1220.. _langext-objc-retain-release: 1221 1222Objective-C retaining behavior attributes 1223----------------------------------------- 1224 1225In Objective-C, functions and methods are generally assumed to follow the 1226`Cocoa Memory Management 1227<http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_ 1228conventions for ownership of object arguments and 1229return values. However, there are exceptions, and so Clang provides attributes 1230to allow these exceptions to be documented. This are used by ARC and the 1231`static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be 1232better described using the ``objc_method_family`` attribute instead. 1233 1234**Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``, 1235``ns_returns_autoreleased``, ``cf_returns_retained``, and 1236``cf_returns_not_retained`` attributes can be placed on methods and functions 1237that return Objective-C or CoreFoundation objects. They are commonly placed at 1238the end of a function prototype or method declaration: 1239 1240.. code-block:: objc 1241 1242 id foo() __attribute__((ns_returns_retained)); 1243 1244 - (NSString *)bar:(int)x __attribute__((ns_returns_retained)); 1245 1246The ``*_returns_retained`` attributes specify that the returned object has a +1 1247retain count. The ``*_returns_not_retained`` attributes specify that the return 1248object has a +0 retain count, even if the normal convention for its selector 1249would be +1. ``ns_returns_autoreleased`` specifies that the returned object is 1250+0, but is guaranteed to live at least as long as the next flush of an 1251autorelease pool. 1252 1253**Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on 1254an parameter declaration; they specify that the argument is expected to have a 1255+1 retain count, which will be balanced in some way by the function or method. 1256The ``ns_consumes_self`` attribute can only be placed on an Objective-C 1257method; it specifies that the method expects its ``self`` parameter to have a 1258+1 retain count, which it will balance in some way. 1259 1260.. code-block:: objc 1261 1262 void foo(__attribute__((ns_consumed)) NSString *string); 1263 1264 - (void) bar __attribute__((ns_consumes_self)); 1265 - (void) baz:(id) __attribute__((ns_consumed)) x; 1266 1267Further examples of these attributes are available in the static analyzer's `list of annotations for analysis 1268<http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_. 1269 1270Query for these features with ``__has_attribute(ns_consumed)``, 1271``__has_attribute(ns_returns_retained)``, etc. 1272 1273 1274Objective-C++ ABI: protocol-qualifier mangling of parameters 1275------------------------------------------------------------ 1276 1277Starting with LLVM 3.4, Clang produces a new mangling for parameters whose 1278type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such 1279parameters to be differentiated from those with the regular unqualified ``id`` 1280type. 1281 1282This was a non-backward compatible mangling change to the ABI. This change 1283allows proper overloading, and also prevents mangling conflicts with template 1284parameters of protocol-qualified type. 1285 1286Query the presence of this new mangling with 1287``__has_feature(objc_protocol_qualifier_mangling)``. 1288 1289.. _langext-overloading: 1290 1291Initializer lists for complex numbers in C 1292========================================== 1293 1294clang supports an extension which allows the following in C: 1295 1296.. code-block:: c++ 1297 1298 #include <math.h> 1299 #include <complex.h> 1300 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) 1301 1302This construct is useful because there is no way to separately initialize the 1303real and imaginary parts of a complex variable in standard C, given that clang 1304does not support ``_Imaginary``. (Clang also supports the ``__real__`` and 1305``__imag__`` extensions from gcc, which help in some cases, but are not usable 1306in static initializers.) 1307 1308Note that this extension does not allow eliding the braces; the meaning of the 1309following two lines is different: 1310 1311.. code-block:: c++ 1312 1313 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) 1314 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) 1315 1316This extension also works in C++ mode, as far as that goes, but does not apply 1317to the C++ ``std::complex``. (In C++11, list initialization allows the same 1318syntax to be used with ``std::complex`` with the same meaning.) 1319 1320Builtin Functions 1321================= 1322 1323Clang supports a number of builtin library functions with the same syntax as 1324GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``, 1325``__builtin_choose_expr``, ``__builtin_types_compatible_p``, 1326``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to 1327the GCC builtins, Clang supports a number of builtins that GCC does not, which 1328are listed here. 1329 1330Please note that Clang does not and will not support all of the GCC builtins 1331for vector operations. Instead of using builtins, you should use the functions 1332defined in target-specific header files like ``<xmmintrin.h>``, which define 1333portable wrappers for these. Many of the Clang versions of these functions are 1334implemented directly in terms of :ref:`extended vector support 1335<langext-vectors>` instead of builtins, in order to reduce the number of 1336builtins that we need to implement. 1337 1338``__builtin_assume`` 1339------------------------------ 1340 1341``__builtin_assume`` is used to provide the optimizer with a boolean 1342invariant that is defined to be true. 1343 1344**Syntax**: 1345 1346.. code-block:: c++ 1347 1348 __builtin_assume(bool) 1349 1350**Example of Use**: 1351 1352.. code-block:: c++ 1353 1354 int foo(int x) { 1355 __builtin_assume(x != 0); 1356 1357 // The optimizer may short-circuit this check using the invariant. 1358 if (x == 0) 1359 return do_something(); 1360 1361 return do_something_else(); 1362 } 1363 1364**Description**: 1365 1366The boolean argument to this function is defined to be true. The optimizer may 1367analyze the form of the expression provided as the argument and deduce from 1368that information used to optimize the program. If the condition is violated 1369during execution, the behavior is undefined. The argument itself is never 1370evaluated, so any side effects of the expression will be discarded. 1371 1372Query for this feature with ``__has_builtin(__builtin_assume)``. 1373 1374``__builtin_readcyclecounter`` 1375------------------------------ 1376 1377``__builtin_readcyclecounter`` is used to access the cycle counter register (or 1378a similar low-latency, high-accuracy clock) on those targets that support it. 1379 1380**Syntax**: 1381 1382.. code-block:: c++ 1383 1384 __builtin_readcyclecounter() 1385 1386**Example of Use**: 1387 1388.. code-block:: c++ 1389 1390 unsigned long long t0 = __builtin_readcyclecounter(); 1391 do_something(); 1392 unsigned long long t1 = __builtin_readcyclecounter(); 1393 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow 1394 1395**Description**: 1396 1397The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value, 1398which may be either global or process/thread-specific depending on the target. 1399As the backing counters often overflow quickly (on the order of seconds) this 1400should only be used for timing small intervals. When not supported by the 1401target, the return value is always zero. This builtin takes no arguments and 1402produces an unsigned long long result. 1403 1404Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note 1405that even if present, its use may depend on run-time privilege or other OS 1406controlled state. 1407 1408.. _langext-__builtin_shufflevector: 1409 1410``__builtin_shufflevector`` 1411--------------------------- 1412 1413``__builtin_shufflevector`` is used to express generic vector 1414permutation/shuffle/swizzle operations. This builtin is also very important 1415for the implementation of various target-specific header files like 1416``<xmmintrin.h>``. 1417 1418**Syntax**: 1419 1420.. code-block:: c++ 1421 1422 __builtin_shufflevector(vec1, vec2, index1, index2, ...) 1423 1424**Examples**: 1425 1426.. code-block:: c++ 1427 1428 // identity operation - return 4-element vector v1. 1429 __builtin_shufflevector(v1, v1, 0, 1, 2, 3) 1430 1431 // "Splat" element 0 of V1 into a 4-element result. 1432 __builtin_shufflevector(V1, V1, 0, 0, 0, 0) 1433 1434 // Reverse 4-element vector V1. 1435 __builtin_shufflevector(V1, V1, 3, 2, 1, 0) 1436 1437 // Concatenate every other element of 4-element vectors V1 and V2. 1438 __builtin_shufflevector(V1, V2, 0, 2, 4, 6) 1439 1440 // Concatenate every other element of 8-element vectors V1 and V2. 1441 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) 1442 1443 // Shuffle v1 with some elements being undefined 1444 __builtin_shufflevector(v1, v1, 3, -1, 1, -1) 1445 1446**Description**: 1447 1448The first two arguments to ``__builtin_shufflevector`` are vectors that have 1449the same element type. The remaining arguments are a list of integers that 1450specify the elements indices of the first two vectors that should be extracted 1451and returned in a new vector. These element indices are numbered sequentially 1452starting with the first vector, continuing into the second vector. Thus, if 1453``vec1`` is a 4-element vector, index 5 would refer to the second element of 1454``vec2``. An index of -1 can be used to indicate that the corresponding element 1455in the returned vector is a don't care and can be optimized by the backend. 1456 1457The result of ``__builtin_shufflevector`` is a vector with the same element 1458type as ``vec1``/``vec2`` but that has an element count equal to the number of 1459indices specified. 1460 1461Query for this feature with ``__has_builtin(__builtin_shufflevector)``. 1462 1463.. _langext-__builtin_convertvector: 1464 1465``__builtin_convertvector`` 1466--------------------------- 1467 1468``__builtin_convertvector`` is used to express generic vector 1469type-conversion operations. The input vector and the output vector 1470type must have the same number of elements. 1471 1472**Syntax**: 1473 1474.. code-block:: c++ 1475 1476 __builtin_convertvector(src_vec, dst_vec_type) 1477 1478**Examples**: 1479 1480.. code-block:: c++ 1481 1482 typedef double vector4double __attribute__((__vector_size__(32))); 1483 typedef float vector4float __attribute__((__vector_size__(16))); 1484 typedef short vector4short __attribute__((__vector_size__(8))); 1485 vector4float vf; vector4short vs; 1486 1487 // convert from a vector of 4 floats to a vector of 4 doubles. 1488 __builtin_convertvector(vf, vector4double) 1489 // equivalent to: 1490 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] } 1491 1492 // convert from a vector of 4 shorts to a vector of 4 floats. 1493 __builtin_convertvector(vs, vector4float) 1494 // equivalent to: 1495 (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] } 1496 1497**Description**: 1498 1499The first argument to ``__builtin_convertvector`` is a vector, and the second 1500argument is a vector type with the same number of elements as the first 1501argument. 1502 1503The result of ``__builtin_convertvector`` is a vector with the same element 1504type as the second argument, with a value defined in terms of the action of a 1505C-style cast applied to each element of the first argument. 1506 1507Query for this feature with ``__has_builtin(__builtin_convertvector)``. 1508 1509``__builtin_bitreverse`` 1510------------------------ 1511 1512* ``__builtin_bitreverse8`` 1513* ``__builtin_bitreverse16`` 1514* ``__builtin_bitreverse32`` 1515* ``__builtin_bitreverse64`` 1516 1517**Syntax**: 1518 1519.. code-block:: c++ 1520 1521 __builtin_bitreverse32(x) 1522 1523**Examples**: 1524 1525.. code-block:: c++ 1526 1527 uint8_t rev_x = __builtin_bitreverse8(x); 1528 uint16_t rev_x = __builtin_bitreverse16(x); 1529 uint32_t rev_y = __builtin_bitreverse32(y); 1530 uint64_t rev_z = __builtin_bitreverse64(z); 1531 1532**Description**: 1533 1534The '``__builtin_bitreverse``' family of builtins is used to reverse 1535the bitpattern of an integer value; for example ``0b10110110`` becomes 1536``0b01101101``. 1537 1538``__builtin_unreachable`` 1539------------------------- 1540 1541``__builtin_unreachable`` is used to indicate that a specific point in the 1542program cannot be reached, even if the compiler might otherwise think it can. 1543This is useful to improve optimization and eliminates certain warnings. For 1544example, without the ``__builtin_unreachable`` in the example below, the 1545compiler assumes that the inline asm can fall through and prints a "function 1546declared '``noreturn``' should not return" warning. 1547 1548**Syntax**: 1549 1550.. code-block:: c++ 1551 1552 __builtin_unreachable() 1553 1554**Example of use**: 1555 1556.. code-block:: c++ 1557 1558 void myabort(void) __attribute__((noreturn)); 1559 void myabort(void) { 1560 asm("int3"); 1561 __builtin_unreachable(); 1562 } 1563 1564**Description**: 1565 1566The ``__builtin_unreachable()`` builtin has completely undefined behavior. 1567Since it has undefined behavior, it is a statement that it is never reached and 1568the optimizer can take advantage of this to produce better code. This builtin 1569takes no arguments and produces a void result. 1570 1571Query for this feature with ``__has_builtin(__builtin_unreachable)``. 1572 1573``__builtin_unpredictable`` 1574--------------------------- 1575 1576``__builtin_unpredictable`` is used to indicate that a branch condition is 1577unpredictable by hardware mechanisms such as branch prediction logic. 1578 1579**Syntax**: 1580 1581.. code-block:: c++ 1582 1583 __builtin_unpredictable(long long) 1584 1585**Example of use**: 1586 1587.. code-block:: c++ 1588 1589 if (__builtin_unpredictable(x > 0)) { 1590 foo(); 1591 } 1592 1593**Description**: 1594 1595The ``__builtin_unpredictable()`` builtin is expected to be used with control 1596flow conditions such as in ``if`` and ``switch`` statements. 1597 1598Query for this feature with ``__has_builtin(__builtin_unpredictable)``. 1599 1600``__sync_swap`` 1601--------------- 1602 1603``__sync_swap`` is used to atomically swap integers or pointers in memory. 1604 1605**Syntax**: 1606 1607.. code-block:: c++ 1608 1609 type __sync_swap(type *ptr, type value, ...) 1610 1611**Example of Use**: 1612 1613.. code-block:: c++ 1614 1615 int old_value = __sync_swap(&value, new_value); 1616 1617**Description**: 1618 1619The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of 1620atomic intrinsics to allow code to atomically swap the current value with the 1621new value. More importantly, it helps developers write more efficient and 1622correct code by avoiding expensive loops around 1623``__sync_bool_compare_and_swap()`` or relying on the platform specific 1624implementation details of ``__sync_lock_test_and_set()``. The 1625``__sync_swap()`` builtin is a full barrier. 1626 1627``__builtin_addressof`` 1628----------------------- 1629 1630``__builtin_addressof`` performs the functionality of the built-in ``&`` 1631operator, ignoring any ``operator&`` overload. This is useful in constant 1632expressions in C++11, where there is no other way to take the address of an 1633object that overloads ``operator&``. 1634 1635**Example of use**: 1636 1637.. code-block:: c++ 1638 1639 template<typename T> constexpr T *addressof(T &value) { 1640 return __builtin_addressof(value); 1641 } 1642 1643``__builtin_operator_new`` and ``__builtin_operator_delete`` 1644------------------------------------------------------------ 1645 1646``__builtin_operator_new`` allocates memory just like a non-placement non-class 1647*new-expression*. This is exactly like directly calling the normal 1648non-placement ``::operator new``, except that it allows certain optimizations 1649that the C++ standard does not permit for a direct function call to 1650``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and 1651merging allocations). 1652 1653Likewise, ``__builtin_operator_delete`` deallocates memory just like a 1654non-class *delete-expression*, and is exactly like directly calling the normal 1655``::operator delete``, except that it permits optimizations. Only the unsized 1656form of ``__builtin_operator_delete`` is currently available. 1657 1658These builtins are intended for use in the implementation of ``std::allocator`` 1659and other similar allocation libraries, and are only available in C++. 1660 1661Multiprecision Arithmetic Builtins 1662---------------------------------- 1663 1664Clang provides a set of builtins which expose multiprecision arithmetic in a 1665manner amenable to C. They all have the following form: 1666 1667.. code-block:: c 1668 1669 unsigned x = ..., y = ..., carryin = ..., carryout; 1670 unsigned sum = __builtin_addc(x, y, carryin, &carryout); 1671 1672Thus one can form a multiprecision addition chain in the following manner: 1673 1674.. code-block:: c 1675 1676 unsigned *x, *y, *z, carryin=0, carryout; 1677 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout); 1678 carryin = carryout; 1679 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout); 1680 carryin = carryout; 1681 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout); 1682 carryin = carryout; 1683 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout); 1684 1685The complete list of builtins are: 1686 1687.. code-block:: c 1688 1689 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 1690 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 1691 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 1692 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 1693 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 1694 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 1695 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 1696 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 1697 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 1698 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 1699 1700Checked Arithmetic Builtins 1701--------------------------- 1702 1703Clang provides a set of builtins that implement checked arithmetic for security 1704critical applications in a manner that is fast and easily expressable in C. As 1705an example of their usage: 1706 1707.. code-block:: c 1708 1709 errorcode_t security_critical_application(...) { 1710 unsigned x, y, result; 1711 ... 1712 if (__builtin_mul_overflow(x, y, &result)) 1713 return kErrorCodeHackers; 1714 ... 1715 use_multiply(result); 1716 ... 1717 } 1718 1719Clang provides the following checked arithmetic builtins: 1720 1721.. code-block:: c 1722 1723 bool __builtin_add_overflow (type1 x, type2 y, type3 *sum); 1724 bool __builtin_sub_overflow (type1 x, type2 y, type3 *diff); 1725 bool __builtin_mul_overflow (type1 x, type2 y, type3 *prod); 1726 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum); 1727 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum); 1728 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum); 1729 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff); 1730 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff); 1731 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff); 1732 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod); 1733 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod); 1734 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod); 1735 bool __builtin_sadd_overflow (int x, int y, int *sum); 1736 bool __builtin_saddl_overflow (long x, long y, long *sum); 1737 bool __builtin_saddll_overflow(long long x, long long y, long long *sum); 1738 bool __builtin_ssub_overflow (int x, int y, int *diff); 1739 bool __builtin_ssubl_overflow (long x, long y, long *diff); 1740 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff); 1741 bool __builtin_smul_overflow (int x, int y, int *prod); 1742 bool __builtin_smull_overflow (long x, long y, long *prod); 1743 bool __builtin_smulll_overflow(long long x, long long y, long long *prod); 1744 1745Each builtin performs the specified mathematical operation on the 1746first two arguments and stores the result in the third argument. If 1747possible, the result will be equal to mathematically-correct result 1748and the builtin will return 0. Otherwise, the builtin will return 17491 and the result will be equal to the unique value that is equivalent 1750to the mathematically-correct result modulo two raised to the *k* 1751power, where *k* is the number of bits in the result type. The 1752behavior of these builtins is well-defined for all argument values. 1753 1754The first three builtins work generically for operands of any integer type, 1755including boolean types. The operands need not have the same type as each 1756other, or as the result. The other builtins may implicitly promote or 1757convert their operands before performing the operation. 1758 1759Query for this feature with ``__has_builtin(__builtin_add_overflow)``, etc. 1760 1761Floating point builtins 1762--------------------------------------- 1763 1764``__builtin_canonicalize`` 1765-------------------------- 1766 1767.. code-block:: c 1768 1769 double __builtin_canonicalize(double); 1770 float __builtin_canonicalizef(float); 1771 long double__builtin_canonicalizel(long double); 1772 1773Returns the platform specific canonical encoding of a floating point 1774number. This canonicalization is useful for implementing certain 1775numeric primitives such as frexp. See `LLVM canonicalize intrinsic 1776<http://llvm.org/docs/LangRef.html#llvm-canonicalize-intrinsic>`_ for 1777more information on the semantics. 1778 1779.. _langext-__c11_atomic: 1780 1781__c11_atomic builtins 1782--------------------- 1783 1784Clang provides a set of builtins which are intended to be used to implement 1785C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the 1786``_explicit`` form of the corresponding C11 operation, and are named with a 1787``__c11_`` prefix. The supported operations, and the differences from 1788the corresponding C11 operations, are: 1789 1790* ``__c11_atomic_init`` 1791* ``__c11_atomic_thread_fence`` 1792* ``__c11_atomic_signal_fence`` 1793* ``__c11_atomic_is_lock_free`` (The argument is the size of the 1794 ``_Atomic(...)`` object, instead of its address) 1795* ``__c11_atomic_store`` 1796* ``__c11_atomic_load`` 1797* ``__c11_atomic_exchange`` 1798* ``__c11_atomic_compare_exchange_strong`` 1799* ``__c11_atomic_compare_exchange_weak`` 1800* ``__c11_atomic_fetch_add`` 1801* ``__c11_atomic_fetch_sub`` 1802* ``__c11_atomic_fetch_and`` 1803* ``__c11_atomic_fetch_or`` 1804* ``__c11_atomic_fetch_xor`` 1805 1806The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, 1807``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are 1808provided, with values corresponding to the enumerators of C11's 1809``memory_order`` enumeration. 1810 1811(Note that Clang additionally provides GCC-compatible ``__atomic_*`` 1812builtins) 1813 1814Low-level ARM exclusive memory builtins 1815--------------------------------------- 1816 1817Clang provides overloaded builtins giving direct access to the three key ARM 1818instructions for implementing atomic operations. 1819 1820.. code-block:: c 1821 1822 T __builtin_arm_ldrex(const volatile T *addr); 1823 T __builtin_arm_ldaex(const volatile T *addr); 1824 int __builtin_arm_strex(T val, volatile T *addr); 1825 int __builtin_arm_stlex(T val, volatile T *addr); 1826 void __builtin_arm_clrex(void); 1827 1828The types ``T`` currently supported are: 1829 1830* Integer types with width at most 64 bits (or 128 bits on AArch64). 1831* Floating-point types 1832* Pointer types. 1833 1834Note that the compiler does not guarantee it will not insert stores which clear 1835the exclusive monitor in between an ``ldrex`` type operation and its paired 1836``strex``. In practice this is only usually a risk when the extra store is on 1837the same cache line as the variable being modified and Clang will only insert 1838stack stores on its own, so it is best not to use these operations on variables 1839with automatic storage duration. 1840 1841Also, loads and stores may be implicit in code written between the ``ldrex`` and 1842``strex``. Clang will not necessarily mitigate the effects of these either, so 1843care should be exercised. 1844 1845For these reasons the higher level atomic primitives should be preferred where 1846possible. 1847 1848Non-temporal load/store builtins 1849-------------------------------- 1850 1851Clang provides overloaded builtins allowing generation of non-temporal memory 1852accesses. 1853 1854.. code-block:: c 1855 1856 T __builtin_nontemporal_load(T *addr); 1857 void __builtin_nontemporal_store(T value, T *addr); 1858 1859The types ``T`` currently supported are: 1860 1861* Integer types. 1862* Floating-point types. 1863* Vector types. 1864 1865Note that the compiler does not guarantee that non-temporal loads or stores 1866will be used. 1867 1868Non-standard C++11 Attributes 1869============================= 1870 1871Clang's non-standard C++11 attributes live in the ``clang`` attribute 1872namespace. 1873 1874Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which 1875are accepted with the ``__attribute__((foo))`` syntax are also accepted as 1876``[[gnu::foo]]``. This only extends to attributes which are specified by GCC 1877(see the list of `GCC function attributes 1878<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable 1879attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and 1880`GCC type attributes 1881<http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC 1882implementation, these attributes must appertain to the *declarator-id* in a 1883declaration, which means they must go either at the start of the declaration or 1884immediately after the name being declared. 1885 1886For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and 1887also applies the GNU ``noreturn`` attribute to ``f``. 1888 1889.. code-block:: c++ 1890 1891 [[gnu::unused]] int a, f [[gnu::noreturn]] (); 1892 1893Target-Specific Extensions 1894========================== 1895 1896Clang supports some language features conditionally on some targets. 1897 1898ARM/AArch64 Language Extensions 1899------------------------------- 1900 1901Memory Barrier Intrinsics 1902^^^^^^^^^^^^^^^^^^^^^^^^^ 1903Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined 1904in the `ARM C Language Extensions Release 2.0 1905<http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_. 1906Note that these intrinsics are implemented as motion barriers that block 1907reordering of memory accesses and side effect instructions. Other instructions 1908like simple arithmetic may be reordered around the intrinsic. If you expect to 1909have no reordering at all, use inline assembly instead. 1910 1911X86/X86-64 Language Extensions 1912------------------------------ 1913 1914The X86 backend has these language extensions: 1915 1916Memory references to specified segments 1917^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1918 1919Annotating a pointer with address space #256 causes it to be code generated 1920relative to the X86 GS segment register, address space #257 causes it to be 1921relative to the X86 FS segment, and address space #258 causes it to be 1922relative to the X86 SS segment. Note that this is a very very low-level 1923feature that should only be used if you know what you're doing (for example in 1924an OS kernel). 1925 1926Here is an example: 1927 1928.. code-block:: c++ 1929 1930 #define GS_RELATIVE __attribute__((address_space(256))) 1931 int foo(int GS_RELATIVE *P) { 1932 return *P; 1933 } 1934 1935Which compiles to (on X86-32): 1936 1937.. code-block:: gas 1938 1939 _foo: 1940 movl 4(%esp), %eax 1941 movl %gs:(%eax), %eax 1942 ret 1943 1944Extensions for Static Analysis 1945============================== 1946 1947Clang supports additional attributes that are useful for documenting program 1948invariants and rules for static analysis tools, such as the `Clang Static 1949Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented 1950in the analyzer's `list of source-level annotations 1951<http://clang-analyzer.llvm.org/annotations.html>`_. 1952 1953 1954Extensions for Dynamic Analysis 1955=============================== 1956 1957Use ``__has_feature(address_sanitizer)`` to check if the code is being built 1958with :doc:`AddressSanitizer`. 1959 1960Use ``__has_feature(thread_sanitizer)`` to check if the code is being built 1961with :doc:`ThreadSanitizer`. 1962 1963Use ``__has_feature(memory_sanitizer)`` to check if the code is being built 1964with :doc:`MemorySanitizer`. 1965 1966Use ``__has_feature(safe_stack)`` to check if the code is being built 1967with :doc:`SafeStack`. 1968 1969 1970Extensions for selectively disabling optimization 1971================================================= 1972 1973Clang provides a mechanism for selectively disabling optimizations in functions 1974and methods. 1975 1976To disable optimizations in a single function definition, the GNU-style or C++11 1977non-standard attribute ``optnone`` can be used. 1978 1979.. code-block:: c++ 1980 1981 // The following functions will not be optimized. 1982 // GNU-style attribute 1983 __attribute__((optnone)) int foo() { 1984 // ... code 1985 } 1986 // C++11 attribute 1987 [[clang::optnone]] int bar() { 1988 // ... code 1989 } 1990 1991To facilitate disabling optimization for a range of function definitions, a 1992range-based pragma is provided. Its syntax is ``#pragma clang optimize`` 1993followed by ``off`` or ``on``. 1994 1995All function definitions in the region between an ``off`` and the following 1996``on`` will be decorated with the ``optnone`` attribute unless doing so would 1997conflict with explicit attributes already present on the function (e.g. the 1998ones that control inlining). 1999 2000.. code-block:: c++ 2001 2002 #pragma clang optimize off 2003 // This function will be decorated with optnone. 2004 int foo() { 2005 // ... code 2006 } 2007 2008 // optnone conflicts with always_inline, so bar() will not be decorated. 2009 __attribute__((always_inline)) int bar() { 2010 // ... code 2011 } 2012 #pragma clang optimize on 2013 2014If no ``on`` is found to close an ``off`` region, the end of the region is the 2015end of the compilation unit. 2016 2017Note that a stray ``#pragma clang optimize on`` does not selectively enable 2018additional optimizations when compiling at low optimization levels. This feature 2019can only be used to selectively disable optimizations. 2020 2021The pragma has an effect on functions only at the point of their definition; for 2022function templates, this means that the state of the pragma at the point of an 2023instantiation is not necessarily relevant. Consider the following example: 2024 2025.. code-block:: c++ 2026 2027 template<typename T> T twice(T t) { 2028 return 2 * t; 2029 } 2030 2031 #pragma clang optimize off 2032 template<typename T> T thrice(T t) { 2033 return 3 * t; 2034 } 2035 2036 int container(int a, int b) { 2037 return twice(a) + thrice(b); 2038 } 2039 #pragma clang optimize on 2040 2041In this example, the definition of the template function ``twice`` is outside 2042the pragma region, whereas the definition of ``thrice`` is inside the region. 2043The ``container`` function is also in the region and will not be optimized, but 2044it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of 2045these two instantiations, ``twice`` will be optimized (because its definition 2046was outside the region) and ``thrice`` will not be optimized. 2047 2048Extensions for loop hint optimizations 2049====================================== 2050 2051The ``#pragma clang loop`` directive is used to specify hints for optimizing the 2052subsequent for, while, do-while, or c++11 range-based for loop. The directive 2053provides options for vectorization, interleaving, unrolling and 2054distribution. Loop hints can be specified before any loop and will be ignored if 2055the optimization is not safe to apply. 2056 2057Vectorization and Interleaving 2058------------------------------ 2059 2060A vectorized loop performs multiple iterations of the original loop 2061in parallel using vector instructions. The instruction set of the target 2062processor determines which vector instructions are available and their vector 2063widths. This restricts the types of loops that can be vectorized. The vectorizer 2064automatically determines if the loop is safe and profitable to vectorize. A 2065vector instruction cost model is used to select the vector width. 2066 2067Interleaving multiple loop iterations allows modern processors to further 2068improve instruction-level parallelism (ILP) using advanced hardware features, 2069such as multiple execution units and out-of-order execution. The vectorizer uses 2070a cost model that depends on the register pressure and generated code size to 2071select the interleaving count. 2072 2073Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled 2074by ``interleave(enable)``. This is useful when compiling with ``-Os`` to 2075manually enable vectorization or interleaving. 2076 2077.. code-block:: c++ 2078 2079 #pragma clang loop vectorize(enable) 2080 #pragma clang loop interleave(enable) 2081 for(...) { 2082 ... 2083 } 2084 2085The vector width is specified by ``vectorize_width(_value_)`` and the interleave 2086count is specified by ``interleave_count(_value_)``, where 2087_value_ is a positive integer. This is useful for specifying the optimal 2088width/count of the set of target architectures supported by your application. 2089 2090.. code-block:: c++ 2091 2092 #pragma clang loop vectorize_width(2) 2093 #pragma clang loop interleave_count(2) 2094 for(...) { 2095 ... 2096 } 2097 2098Specifying a width/count of 1 disables the optimization, and is equivalent to 2099``vectorize(disable)`` or ``interleave(disable)``. 2100 2101Loop Unrolling 2102-------------- 2103 2104Unrolling a loop reduces the loop control overhead and exposes more 2105opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling 2106eliminates the loop and replaces it with an enumerated sequence of loop 2107iterations. Full unrolling is only possible if the loop trip count is known at 2108compile time. Partial unrolling replicates the loop body within the loop and 2109reduces the trip count. 2110 2111If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the 2112loop if the trip count is known at compile time. If the fully unrolled code size 2113is greater than an internal limit the loop will be partially unrolled up to this 2114limit. If the trip count is not known at compile time the loop will be partially 2115unrolled with a heuristically chosen unroll factor. 2116 2117.. code-block:: c++ 2118 2119 #pragma clang loop unroll(enable) 2120 for(...) { 2121 ... 2122 } 2123 2124If ``unroll(full)`` is specified the unroller will attempt to fully unroll the 2125loop if the trip count is known at compile time identically to 2126``unroll(enable)``. However, with ``unroll(full)`` the loop will not be unrolled 2127if the loop count is not known at compile time. 2128 2129.. code-block:: c++ 2130 2131 #pragma clang loop unroll(full) 2132 for(...) { 2133 ... 2134 } 2135 2136The unroll count can be specified explicitly with ``unroll_count(_value_)`` where 2137_value_ is a positive integer. If this value is greater than the trip count the 2138loop will be fully unrolled. Otherwise the loop is partially unrolled subject 2139to the same code size limit as with ``unroll(enable)``. 2140 2141.. code-block:: c++ 2142 2143 #pragma clang loop unroll_count(8) 2144 for(...) { 2145 ... 2146 } 2147 2148Unrolling of a loop can be prevented by specifying ``unroll(disable)``. 2149 2150Loop Distribution 2151----------------- 2152 2153Loop Distribution allows splitting a loop into multiple loops. This is 2154beneficial for example when the entire loop cannot be vectorized but some of the 2155resulting loops can. 2156 2157If ``distribute(enable))`` is specified and the loop has memory dependencies 2158that inhibit vectorization, the compiler will attempt to isolate the offending 2159operations into a new loop. This optimization is not enabled by default, only 2160loops marked with the pragma are considered. 2161 2162.. code-block:: c++ 2163 2164 #pragma clang loop distribute(enable) 2165 for (i = 0; i < N; ++i) { 2166 S1: A[i + 1] = A[i] + B[i]; 2167 S2: C[i] = D[i] * E[i]; 2168 } 2169 2170This loop will be split into two loops between statements S1 and S2. The 2171second loop containing S2 will be vectorized. 2172 2173Loop Distribution is currently not enabled by default in the optimizer because 2174it can hurt performance in some cases. For example, instruction-level 2175parallelism could be reduced by sequentializing the execution of the 2176statements S1 and S2 above. 2177 2178If Loop Distribution is turned on globally with 2179``-mllvm -enable-loop-distribution``, specifying ``distribute(disable)`` can 2180be used the disable it on a per-loop basis. 2181 2182Additional Information 2183---------------------- 2184 2185For convenience multiple loop hints can be specified on a single line. 2186 2187.. code-block:: c++ 2188 2189 #pragma clang loop vectorize_width(4) interleave_count(8) 2190 for(...) { 2191 ... 2192 } 2193 2194If an optimization cannot be applied any hints that apply to it will be ignored. 2195For example, the hint ``vectorize_width(4)`` is ignored if the loop is not 2196proven safe to vectorize. To identify and diagnose optimization issues use 2197`-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the 2198user guide for details. 2199