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