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 Opeator 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:: c++ 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 938Checks for Type Trait Primitives 939================================ 940 941Type trait primitives are special builtin constant expressions that can be used 942by the standard C++ library to facilitate or simplify the implementation of 943user-facing type traits in the <type_traits> header. 944 945They are not intended to be used directly by user code because they are 946implementation-defined and subject to change -- as such they're tied closely to 947the supported set of system headers, currently: 948 949* LLVM's own libc++ 950* GNU libstdc++ 951* The Microsoft standard C++ library 952 953Clang supports the `GNU C++ type traits 954<http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the 955`Microsoft Visual C++ Type traits 956<http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_. 957 958Feature detection is supported only for some of the primitives at present. User 959code should not use these checks because they bear no direct relation to the 960actual set of type traits supported by the C++ standard library. 961 962For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the 963type trait primitive in the compiler. A simplistic usage example as might be 964seen in standard C++ headers follows: 965 966.. code-block:: c++ 967 968 #if __has_extension(is_convertible_to) 969 template<typename From, typename To> 970 struct is_convertible_to { 971 static const bool value = __is_convertible_to(From, To); 972 }; 973 #else 974 // Emulate type trait for compatibility with other compilers. 975 #endif 976 977The following type trait primitives are supported by Clang: 978 979* ``__has_nothrow_assign`` (GNU, Microsoft) 980* ``__has_nothrow_copy`` (GNU, Microsoft) 981* ``__has_nothrow_constructor`` (GNU, Microsoft) 982* ``__has_trivial_assign`` (GNU, Microsoft) 983* ``__has_trivial_copy`` (GNU, Microsoft) 984* ``__has_trivial_constructor`` (GNU, Microsoft) 985* ``__has_trivial_destructor`` (GNU, Microsoft) 986* ``__has_virtual_destructor`` (GNU, Microsoft) 987* ``__is_abstract`` (GNU, Microsoft) 988* ``__is_base_of`` (GNU, Microsoft) 989* ``__is_class`` (GNU, Microsoft) 990* ``__is_convertible_to`` (Microsoft) 991* ``__is_empty`` (GNU, Microsoft) 992* ``__is_enum`` (GNU, Microsoft) 993* ``__is_interface_class`` (Microsoft) 994* ``__is_pod`` (GNU, Microsoft) 995* ``__is_polymorphic`` (GNU, Microsoft) 996* ``__is_union`` (GNU, Microsoft) 997* ``__is_literal(type)``: Determines whether the given type is a literal type 998* ``__is_final``: Determines whether the given type is declared with a 999 ``final`` class-virt-specifier. 1000* ``__underlying_type(type)``: Retrieves the underlying type for a given 1001 ``enum`` type. This trait is required to implement the C++11 standard 1002 library. 1003* ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value 1004 of type ``totype`` can be assigned to from a value of type ``fromtype`` such 1005 that no non-trivial functions are called as part of that assignment. This 1006 trait is required to implement the C++11 standard library. 1007* ``__is_trivially_constructible(type, argtypes...)``: Determines whether a 1008 value of type ``type`` can be direct-initialized with arguments of types 1009 ``argtypes...`` such that no non-trivial functions are called as part of 1010 that initialization. This trait is required to implement the C++11 standard 1011 library. 1012* ``__is_destructible`` (MSVC 2013): partially implemented 1013* ``__is_nothrow_destructible`` (MSVC 2013): partially implemented 1014* ``__is_nothrow_assignable`` (MSVC 2013, clang) 1015* ``__is_constructible`` (MSVC 2013, clang) 1016* ``__is_nothrow_constructible`` (MSVC 2013, clang) 1017 1018Blocks 1019====== 1020 1021The syntax and high level language feature description is in 1022:doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for 1023the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`. 1024 1025Query for this feature with ``__has_extension(blocks)``. 1026 1027Objective-C Features 1028==================== 1029 1030Related result types 1031-------------------- 1032 1033According to Cocoa conventions, Objective-C methods with certain names 1034("``init``", "``alloc``", etc.) always return objects that are an instance of 1035the receiving class's type. Such methods are said to have a "related result 1036type", meaning that a message send to one of these methods will have the same 1037static type as an instance of the receiver class. For example, given the 1038following classes: 1039 1040.. code-block:: objc 1041 1042 @interface NSObject 1043 + (id)alloc; 1044 - (id)init; 1045 @end 1046 1047 @interface NSArray : NSObject 1048 @end 1049 1050and this common initialization pattern 1051 1052.. code-block:: objc 1053 1054 NSArray *array = [[NSArray alloc] init]; 1055 1056the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because 1057``alloc`` implicitly has a related result type. Similarly, the type of the 1058expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a 1059related result type and its receiver is known to have the type ``NSArray *``. 1060If neither ``alloc`` nor ``init`` had a related result type, the expressions 1061would have had type ``id``, as declared in the method signature. 1062 1063A method with a related result type can be declared by using the type 1064``instancetype`` as its result type. ``instancetype`` is a contextual keyword 1065that is only permitted in the result type of an Objective-C method, e.g. 1066 1067.. code-block:: objc 1068 1069 @interface A 1070 + (instancetype)constructAnA; 1071 @end 1072 1073The related result type can also be inferred for some methods. To determine 1074whether a method has an inferred related result type, the first word in the 1075camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered, 1076and the method will have a related result type if its return type is compatible 1077with the type of its class and if: 1078 1079* the first word is "``alloc``" or "``new``", and the method is a class method, 1080 or 1081 1082* the first word is "``autorelease``", "``init``", "``retain``", or "``self``", 1083 and the method is an instance method. 1084 1085If a method with a related result type is overridden by a subclass method, the 1086subclass method must also return a type that is compatible with the subclass 1087type. For example: 1088 1089.. code-block:: objc 1090 1091 @interface NSString : NSObject 1092 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString 1093 @end 1094 1095Related result types only affect the type of a message send or property access 1096via the given method. In all other respects, a method with a related result 1097type is treated the same way as method that returns ``id``. 1098 1099Use ``__has_feature(objc_instancetype)`` to determine whether the 1100``instancetype`` contextual keyword is available. 1101 1102Automatic reference counting 1103---------------------------- 1104 1105Clang provides support for :doc:`automated reference counting 1106<AutomaticReferenceCounting>` in Objective-C, which eliminates the need 1107for manual ``retain``/``release``/``autorelease`` message sends. There are two 1108feature macros associated with automatic reference counting: 1109``__has_feature(objc_arc)`` indicates the availability of automated reference 1110counting in general, while ``__has_feature(objc_arc_weak)`` indicates that 1111automated reference counting also includes support for ``__weak`` pointers to 1112Objective-C objects. 1113 1114.. _objc-fixed-enum: 1115 1116Enumerations with a fixed underlying type 1117----------------------------------------- 1118 1119Clang provides support for C++11 enumerations with a fixed underlying type 1120within Objective-C. For example, one can write an enumeration type as: 1121 1122.. code-block:: c++ 1123 1124 typedef enum : unsigned char { Red, Green, Blue } Color; 1125 1126This specifies that the underlying type, which is used to store the enumeration 1127value, is ``unsigned char``. 1128 1129Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed 1130underlying types is available in Objective-C. 1131 1132Interoperability with C++11 lambdas 1133----------------------------------- 1134 1135Clang provides interoperability between C++11 lambdas and blocks-based APIs, by 1136permitting a lambda to be implicitly converted to a block pointer with the 1137corresponding signature. For example, consider an API such as ``NSArray``'s 1138array-sorting method: 1139 1140.. code-block:: objc 1141 1142 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; 1143 1144``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult 1145(^)(id, id)``, and parameters of this type are generally provided with block 1146literals as arguments. However, one can also use a C++11 lambda so long as it 1147provides the same signature (in this case, accepting two parameters of type 1148``id`` and returning an ``NSComparisonResult``): 1149 1150.. code-block:: objc 1151 1152 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", 1153 @"String 02"]; 1154 const NSStringCompareOptions comparisonOptions 1155 = NSCaseInsensitiveSearch | NSNumericSearch | 1156 NSWidthInsensitiveSearch | NSForcedOrderingSearch; 1157 NSLocale *currentLocale = [NSLocale currentLocale]; 1158 NSArray *sorted 1159 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult { 1160 NSRange string1Range = NSMakeRange(0, [s1 length]); 1161 return [s1 compare:s2 options:comparisonOptions 1162 range:string1Range locale:currentLocale]; 1163 }]; 1164 NSLog(@"sorted: %@", sorted); 1165 1166This code relies on an implicit conversion from the type of the lambda 1167expression (an unnamed, local class type called the *closure type*) to the 1168corresponding block pointer type. The conversion itself is expressed by a 1169conversion operator in that closure type that produces a block pointer with the 1170same signature as the lambda itself, e.g., 1171 1172.. code-block:: objc 1173 1174 operator NSComparisonResult (^)(id, id)() const; 1175 1176This conversion function returns a new block that simply forwards the two 1177parameters to the lambda object (which it captures by copy), then returns the 1178result. The returned block is first copied (with ``Block_copy``) and then 1179autoreleased. As an optimization, if a lambda expression is immediately 1180converted to a block pointer (as in the first example, above), then the block 1181is not copied and autoreleased: rather, it is given the same lifetime as a 1182block literal written at that point in the program, which avoids the overhead 1183of copying a block to the heap in the common case. 1184 1185The conversion from a lambda to a block pointer is only available in 1186Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory 1187management (autorelease). 1188 1189Object Literals and Subscripting 1190-------------------------------- 1191 1192Clang provides support for :doc:`Object Literals and Subscripting 1193<ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C 1194programming patterns, makes programs more concise, and improves the safety of 1195container creation. There are several feature macros associated with object 1196literals and subscripting: ``__has_feature(objc_array_literals)`` tests the 1197availability of array literals; ``__has_feature(objc_dictionary_literals)`` 1198tests the availability of dictionary literals; 1199``__has_feature(objc_subscripting)`` tests the availability of object 1200subscripting. 1201 1202Objective-C Autosynthesis of Properties 1203--------------------------------------- 1204 1205Clang provides support for autosynthesis of declared properties. Using this 1206feature, clang provides default synthesis of those properties not declared 1207@dynamic and not having user provided backing getter and setter methods. 1208``__has_feature(objc_default_synthesize_properties)`` checks for availability 1209of this feature in version of clang being used. 1210 1211.. _langext-objc-retain-release: 1212 1213Objective-C retaining behavior attributes 1214----------------------------------------- 1215 1216In Objective-C, functions and methods are generally assumed to follow the 1217`Cocoa Memory Management 1218<http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_ 1219conventions for ownership of object arguments and 1220return values. However, there are exceptions, and so Clang provides attributes 1221to allow these exceptions to be documented. This are used by ARC and the 1222`static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be 1223better described using the ``objc_method_family`` attribute instead. 1224 1225**Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``, 1226``ns_returns_autoreleased``, ``cf_returns_retained``, and 1227``cf_returns_not_retained`` attributes can be placed on methods and functions 1228that return Objective-C or CoreFoundation objects. They are commonly placed at 1229the end of a function prototype or method declaration: 1230 1231.. code-block:: objc 1232 1233 id foo() __attribute__((ns_returns_retained)); 1234 1235 - (NSString *)bar:(int)x __attribute__((ns_returns_retained)); 1236 1237The ``*_returns_retained`` attributes specify that the returned object has a +1 1238retain count. The ``*_returns_not_retained`` attributes specify that the return 1239object has a +0 retain count, even if the normal convention for its selector 1240would be +1. ``ns_returns_autoreleased`` specifies that the returned object is 1241+0, but is guaranteed to live at least as long as the next flush of an 1242autorelease pool. 1243 1244**Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on 1245an parameter declaration; they specify that the argument is expected to have a 1246+1 retain count, which will be balanced in some way by the function or method. 1247The ``ns_consumes_self`` attribute can only be placed on an Objective-C 1248method; it specifies that the method expects its ``self`` parameter to have a 1249+1 retain count, which it will balance in some way. 1250 1251.. code-block:: objc 1252 1253 void foo(__attribute__((ns_consumed)) NSString *string); 1254 1255 - (void) bar __attribute__((ns_consumes_self)); 1256 - (void) baz:(id) __attribute__((ns_consumed)) x; 1257 1258Further examples of these attributes are available in the static analyzer's `list of annotations for analysis 1259<http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_. 1260 1261Query for these features with ``__has_attribute(ns_consumed)``, 1262``__has_attribute(ns_returns_retained)``, etc. 1263 1264 1265Objective-C++ ABI: protocol-qualifier mangling of parameters 1266------------------------------------------------------------ 1267 1268Starting with LLVM 3.4, Clang produces a new mangling for parameters whose 1269type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such 1270parameters to be differentiated from those with the regular unqualified ``id`` 1271type. 1272 1273This was a non-backward compatible mangling change to the ABI. This change 1274allows proper overloading, and also prevents mangling conflicts with template 1275parameters of protocol-qualified type. 1276 1277Query the presence of this new mangling with 1278``__has_feature(objc_protocol_qualifier_mangling)``. 1279 1280.. _langext-overloading: 1281 1282Initializer lists for complex numbers in C 1283========================================== 1284 1285clang supports an extension which allows the following in C: 1286 1287.. code-block:: c++ 1288 1289 #include <math.h> 1290 #include <complex.h> 1291 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) 1292 1293This construct is useful because there is no way to separately initialize the 1294real and imaginary parts of a complex variable in standard C, given that clang 1295does not support ``_Imaginary``. (Clang also supports the ``__real__`` and 1296``__imag__`` extensions from gcc, which help in some cases, but are not usable 1297in static initializers.) 1298 1299Note that this extension does not allow eliding the braces; the meaning of the 1300following two lines is different: 1301 1302.. code-block:: c++ 1303 1304 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) 1305 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) 1306 1307This extension also works in C++ mode, as far as that goes, but does not apply 1308to the C++ ``std::complex``. (In C++11, list initialization allows the same 1309syntax to be used with ``std::complex`` with the same meaning.) 1310 1311Builtin Functions 1312================= 1313 1314Clang supports a number of builtin library functions with the same syntax as 1315GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``, 1316``__builtin_choose_expr``, ``__builtin_types_compatible_p``, 1317``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to 1318the GCC builtins, Clang supports a number of builtins that GCC does not, which 1319are listed here. 1320 1321Please note that Clang does not and will not support all of the GCC builtins 1322for vector operations. Instead of using builtins, you should use the functions 1323defined in target-specific header files like ``<xmmintrin.h>``, which define 1324portable wrappers for these. Many of the Clang versions of these functions are 1325implemented directly in terms of :ref:`extended vector support 1326<langext-vectors>` instead of builtins, in order to reduce the number of 1327builtins that we need to implement. 1328 1329``__builtin_assume`` 1330------------------------------ 1331 1332``__builtin_assume`` is used to provide the optimizer with a boolean 1333invariant that is defined to be true. 1334 1335**Syntax**: 1336 1337.. code-block:: c++ 1338 1339 __builtin_assume(bool) 1340 1341**Example of Use**: 1342 1343.. code-block:: c++ 1344 1345 int foo(int x) { 1346 __builtin_assume(x != 0); 1347 1348 // The optimizer may short-circuit this check using the invariant. 1349 if (x == 0) 1350 return do_something(); 1351 1352 return do_something_else(); 1353 } 1354 1355**Description**: 1356 1357The boolean argument to this function is defined to be true. The optimizer may 1358analyze the form of the expression provided as the argument and deduce from 1359that information used to optimize the program. If the condition is violated 1360during execution, the behavior is undefined. The argument itself is never 1361evaluated, so any side effects of the expression will be discarded. 1362 1363Query for this feature with ``__has_builtin(__builtin_assume)``. 1364 1365``__builtin_readcyclecounter`` 1366------------------------------ 1367 1368``__builtin_readcyclecounter`` is used to access the cycle counter register (or 1369a similar low-latency, high-accuracy clock) on those targets that support it. 1370 1371**Syntax**: 1372 1373.. code-block:: c++ 1374 1375 __builtin_readcyclecounter() 1376 1377**Example of Use**: 1378 1379.. code-block:: c++ 1380 1381 unsigned long long t0 = __builtin_readcyclecounter(); 1382 do_something(); 1383 unsigned long long t1 = __builtin_readcyclecounter(); 1384 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow 1385 1386**Description**: 1387 1388The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value, 1389which may be either global or process/thread-specific depending on the target. 1390As the backing counters often overflow quickly (on the order of seconds) this 1391should only be used for timing small intervals. When not supported by the 1392target, the return value is always zero. This builtin takes no arguments and 1393produces an unsigned long long result. 1394 1395Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note 1396that even if present, its use may depend on run-time privilege or other OS 1397controlled state. 1398 1399.. _langext-__builtin_shufflevector: 1400 1401``__builtin_shufflevector`` 1402--------------------------- 1403 1404``__builtin_shufflevector`` is used to express generic vector 1405permutation/shuffle/swizzle operations. This builtin is also very important 1406for the implementation of various target-specific header files like 1407``<xmmintrin.h>``. 1408 1409**Syntax**: 1410 1411.. code-block:: c++ 1412 1413 __builtin_shufflevector(vec1, vec2, index1, index2, ...) 1414 1415**Examples**: 1416 1417.. code-block:: c++ 1418 1419 // identity operation - return 4-element vector v1. 1420 __builtin_shufflevector(v1, v1, 0, 1, 2, 3) 1421 1422 // "Splat" element 0 of V1 into a 4-element result. 1423 __builtin_shufflevector(V1, V1, 0, 0, 0, 0) 1424 1425 // Reverse 4-element vector V1. 1426 __builtin_shufflevector(V1, V1, 3, 2, 1, 0) 1427 1428 // Concatenate every other element of 4-element vectors V1 and V2. 1429 __builtin_shufflevector(V1, V2, 0, 2, 4, 6) 1430 1431 // Concatenate every other element of 8-element vectors V1 and V2. 1432 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) 1433 1434 // Shuffle v1 with some elements being undefined 1435 __builtin_shufflevector(v1, v1, 3, -1, 1, -1) 1436 1437**Description**: 1438 1439The first two arguments to ``__builtin_shufflevector`` are vectors that have 1440the same element type. The remaining arguments are a list of integers that 1441specify the elements indices of the first two vectors that should be extracted 1442and returned in a new vector. These element indices are numbered sequentially 1443starting with the first vector, continuing into the second vector. Thus, if 1444``vec1`` is a 4-element vector, index 5 would refer to the second element of 1445``vec2``. An index of -1 can be used to indicate that the corresponding element 1446in the returned vector is a don't care and can be optimized by the backend. 1447 1448The result of ``__builtin_shufflevector`` is a vector with the same element 1449type as ``vec1``/``vec2`` but that has an element count equal to the number of 1450indices specified. 1451 1452Query for this feature with ``__has_builtin(__builtin_shufflevector)``. 1453 1454.. _langext-__builtin_convertvector: 1455 1456``__builtin_convertvector`` 1457--------------------------- 1458 1459``__builtin_convertvector`` is used to express generic vector 1460type-conversion operations. The input vector and the output vector 1461type must have the same number of elements. 1462 1463**Syntax**: 1464 1465.. code-block:: c++ 1466 1467 __builtin_convertvector(src_vec, dst_vec_type) 1468 1469**Examples**: 1470 1471.. code-block:: c++ 1472 1473 typedef double vector4double __attribute__((__vector_size__(32))); 1474 typedef float vector4float __attribute__((__vector_size__(16))); 1475 typedef short vector4short __attribute__((__vector_size__(8))); 1476 vector4float vf; vector4short vs; 1477 1478 // convert from a vector of 4 floats to a vector of 4 doubles. 1479 __builtin_convertvector(vf, vector4double) 1480 // equivalent to: 1481 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] } 1482 1483 // convert from a vector of 4 shorts to a vector of 4 floats. 1484 __builtin_convertvector(vs, vector4float) 1485 // equivalent to: 1486 (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] } 1487 1488**Description**: 1489 1490The first argument to ``__builtin_convertvector`` is a vector, and the second 1491argument is a vector type with the same number of elements as the first 1492argument. 1493 1494The result of ``__builtin_convertvector`` is a vector with the same element 1495type as the second argument, with a value defined in terms of the action of a 1496C-style cast applied to each element of the first argument. 1497 1498Query for this feature with ``__has_builtin(__builtin_convertvector)``. 1499 1500``__builtin_unreachable`` 1501------------------------- 1502 1503``__builtin_unreachable`` is used to indicate that a specific point in the 1504program cannot be reached, even if the compiler might otherwise think it can. 1505This is useful to improve optimization and eliminates certain warnings. For 1506example, without the ``__builtin_unreachable`` in the example below, the 1507compiler assumes that the inline asm can fall through and prints a "function 1508declared '``noreturn``' should not return" warning. 1509 1510**Syntax**: 1511 1512.. code-block:: c++ 1513 1514 __builtin_unreachable() 1515 1516**Example of use**: 1517 1518.. code-block:: c++ 1519 1520 void myabort(void) __attribute__((noreturn)); 1521 void myabort(void) { 1522 asm("int3"); 1523 __builtin_unreachable(); 1524 } 1525 1526**Description**: 1527 1528The ``__builtin_unreachable()`` builtin has completely undefined behavior. 1529Since it has undefined behavior, it is a statement that it is never reached and 1530the optimizer can take advantage of this to produce better code. This builtin 1531takes no arguments and produces a void result. 1532 1533Query for this feature with ``__has_builtin(__builtin_unreachable)``. 1534 1535``__sync_swap`` 1536--------------- 1537 1538``__sync_swap`` is used to atomically swap integers or pointers in memory. 1539 1540**Syntax**: 1541 1542.. code-block:: c++ 1543 1544 type __sync_swap(type *ptr, type value, ...) 1545 1546**Example of Use**: 1547 1548.. code-block:: c++ 1549 1550 int old_value = __sync_swap(&value, new_value); 1551 1552**Description**: 1553 1554The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of 1555atomic intrinsics to allow code to atomically swap the current value with the 1556new value. More importantly, it helps developers write more efficient and 1557correct code by avoiding expensive loops around 1558``__sync_bool_compare_and_swap()`` or relying on the platform specific 1559implementation details of ``__sync_lock_test_and_set()``. The 1560``__sync_swap()`` builtin is a full barrier. 1561 1562``__builtin_addressof`` 1563----------------------- 1564 1565``__builtin_addressof`` performs the functionality of the built-in ``&`` 1566operator, ignoring any ``operator&`` overload. This is useful in constant 1567expressions in C++11, where there is no other way to take the address of an 1568object that overloads ``operator&``. 1569 1570**Example of use**: 1571 1572.. code-block:: c++ 1573 1574 template<typename T> constexpr T *addressof(T &value) { 1575 return __builtin_addressof(value); 1576 } 1577 1578``__builtin_operator_new`` and ``__builtin_operator_delete`` 1579------------------------------------------------------------ 1580 1581``__builtin_operator_new`` allocates memory just like a non-placement non-class 1582*new-expression*. This is exactly like directly calling the normal 1583non-placement ``::operator new``, except that it allows certain optimizations 1584that the C++ standard does not permit for a direct function call to 1585``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and 1586merging allocations). 1587 1588Likewise, ``__builtin_operator_delete`` deallocates memory just like a 1589non-class *delete-expression*, and is exactly like directly calling the normal 1590``::operator delete``, except that it permits optimizations. Only the unsized 1591form of ``__builtin_operator_delete`` is currently available. 1592 1593These builtins are intended for use in the implementation of ``std::allocator`` 1594and other similar allocation libraries, and are only available in C++. 1595 1596Multiprecision Arithmetic Builtins 1597---------------------------------- 1598 1599Clang provides a set of builtins which expose multiprecision arithmetic in a 1600manner amenable to C. They all have the following form: 1601 1602.. code-block:: c 1603 1604 unsigned x = ..., y = ..., carryin = ..., carryout; 1605 unsigned sum = __builtin_addc(x, y, carryin, &carryout); 1606 1607Thus one can form a multiprecision addition chain in the following manner: 1608 1609.. code-block:: c 1610 1611 unsigned *x, *y, *z, carryin=0, carryout; 1612 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout); 1613 carryin = carryout; 1614 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout); 1615 carryin = carryout; 1616 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout); 1617 carryin = carryout; 1618 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout); 1619 1620The complete list of builtins are: 1621 1622.. code-block:: c 1623 1624 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 1625 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 1626 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 1627 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 1628 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 1629 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 1630 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 1631 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 1632 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 1633 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 1634 1635Checked Arithmetic Builtins 1636--------------------------- 1637 1638Clang provides a set of builtins that implement checked arithmetic for security 1639critical applications in a manner that is fast and easily expressable in C. As 1640an example of their usage: 1641 1642.. code-block:: c 1643 1644 errorcode_t security_critical_application(...) { 1645 unsigned x, y, result; 1646 ... 1647 if (__builtin_umul_overflow(x, y, &result)) 1648 return kErrorCodeHackers; 1649 ... 1650 use_multiply(result); 1651 ... 1652 } 1653 1654A complete enumeration of the builtins are: 1655 1656.. code-block:: c 1657 1658 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum); 1659 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum); 1660 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum); 1661 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff); 1662 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff); 1663 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff); 1664 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod); 1665 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod); 1666 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod); 1667 bool __builtin_sadd_overflow (int x, int y, int *sum); 1668 bool __builtin_saddl_overflow (long x, long y, long *sum); 1669 bool __builtin_saddll_overflow(long long x, long long y, long long *sum); 1670 bool __builtin_ssub_overflow (int x, int y, int *diff); 1671 bool __builtin_ssubl_overflow (long x, long y, long *diff); 1672 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff); 1673 bool __builtin_smul_overflow (int x, int y, int *prod); 1674 bool __builtin_smull_overflow (long x, long y, long *prod); 1675 bool __builtin_smulll_overflow(long long x, long long y, long long *prod); 1676 1677 1678.. _langext-__c11_atomic: 1679 1680__c11_atomic builtins 1681--------------------- 1682 1683Clang provides a set of builtins which are intended to be used to implement 1684C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the 1685``_explicit`` form of the corresponding C11 operation, and are named with a 1686``__c11_`` prefix. The supported operations, and the differences from 1687the corresponding C11 operations, are: 1688 1689* ``__c11_atomic_init`` 1690* ``__c11_atomic_thread_fence`` 1691* ``__c11_atomic_signal_fence`` 1692* ``__c11_atomic_is_lock_free`` (The argument is the size of the 1693 ``_Atomic(...)`` object, instead of its address) 1694* ``__c11_atomic_store`` 1695* ``__c11_atomic_load`` 1696* ``__c11_atomic_exchange`` 1697* ``__c11_atomic_compare_exchange_strong`` 1698* ``__c11_atomic_compare_exchange_weak`` 1699* ``__c11_atomic_fetch_add`` 1700* ``__c11_atomic_fetch_sub`` 1701* ``__c11_atomic_fetch_and`` 1702* ``__c11_atomic_fetch_or`` 1703* ``__c11_atomic_fetch_xor`` 1704 1705The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, 1706``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are 1707provided, with values corresponding to the enumerators of C11's 1708``memory_order`` enumeration. 1709 1710Low-level ARM exclusive memory builtins 1711--------------------------------------- 1712 1713Clang provides overloaded builtins giving direct access to the three key ARM 1714instructions for implementing atomic operations. 1715 1716.. code-block:: c 1717 1718 T __builtin_arm_ldrex(const volatile T *addr); 1719 T __builtin_arm_ldaex(const volatile T *addr); 1720 int __builtin_arm_strex(T val, volatile T *addr); 1721 int __builtin_arm_stlex(T val, volatile T *addr); 1722 void __builtin_arm_clrex(void); 1723 1724The types ``T`` currently supported are: 1725* Integer types with width at most 64 bits (or 128 bits on AArch64). 1726* Floating-point types 1727* Pointer types. 1728 1729Note that the compiler does not guarantee it will not insert stores which clear 1730the exclusive monitor in between an ``ldrex`` type operation and its paired 1731``strex``. In practice this is only usually a risk when the extra store is on 1732the same cache line as the variable being modified and Clang will only insert 1733stack stores on its own, so it is best not to use these operations on variables 1734with automatic storage duration. 1735 1736Also, loads and stores may be implicit in code written between the ``ldrex`` and 1737``strex``. Clang will not necessarily mitigate the effects of these either, so 1738care should be exercised. 1739 1740For these reasons the higher level atomic primitives should be preferred where 1741possible. 1742 1743Non-standard C++11 Attributes 1744============================= 1745 1746Clang's non-standard C++11 attributes live in the ``clang`` attribute 1747namespace. 1748 1749Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which 1750are accepted with the ``__attribute__((foo))`` syntax are also accepted as 1751``[[gnu::foo]]``. This only extends to attributes which are specified by GCC 1752(see the list of `GCC function attributes 1753<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable 1754attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and 1755`GCC type attributes 1756<http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC 1757implementation, these attributes must appertain to the *declarator-id* in a 1758declaration, which means they must go either at the start of the declaration or 1759immediately after the name being declared. 1760 1761For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and 1762also applies the GNU ``noreturn`` attribute to ``f``. 1763 1764.. code-block:: c++ 1765 1766 [[gnu::unused]] int a, f [[gnu::noreturn]] (); 1767 1768Target-Specific Extensions 1769========================== 1770 1771Clang supports some language features conditionally on some targets. 1772 1773ARM/AArch64 Language Extensions 1774------------------------------- 1775 1776Memory Barrier Intrinsics 1777^^^^^^^^^^^^^^^^^^^^^^^^^ 1778Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined 1779in the `ARM C Language Extensions Release 2.0 1780<http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_. 1781Note that these intrinsics are implemented as motion barriers that block 1782reordering of memory accesses and side effect instructions. Other instructions 1783like simple arithmatic may be reordered around the intrinsic. If you expect to 1784have no reordering at all, use inline assembly instead. 1785 1786X86/X86-64 Language Extensions 1787------------------------------ 1788 1789The X86 backend has these language extensions: 1790 1791Memory references off the GS segment 1792^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1793 1794Annotating a pointer with address space #256 causes it to be code generated 1795relative to the X86 GS segment register, and address space #257 causes it to be 1796relative to the X86 FS segment. Note that this is a very very low-level 1797feature that should only be used if you know what you're doing (for example in 1798an OS kernel). 1799 1800Here is an example: 1801 1802.. code-block:: c++ 1803 1804 #define GS_RELATIVE __attribute__((address_space(256))) 1805 int foo(int GS_RELATIVE *P) { 1806 return *P; 1807 } 1808 1809Which compiles to (on X86-32): 1810 1811.. code-block:: gas 1812 1813 _foo: 1814 movl 4(%esp), %eax 1815 movl %gs:(%eax), %eax 1816 ret 1817 1818Extensions for Static Analysis 1819============================== 1820 1821Clang supports additional attributes that are useful for documenting program 1822invariants and rules for static analysis tools, such as the `Clang Static 1823Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented 1824in the analyzer's `list of source-level annotations 1825<http://clang-analyzer.llvm.org/annotations.html>`_. 1826 1827 1828Extensions for Dynamic Analysis 1829=============================== 1830 1831Use ``__has_feature(address_sanitizer)`` to check if the code is being built 1832with :doc:`AddressSanitizer`. 1833 1834Use ``__has_feature(thread_sanitizer)`` to check if the code is being built 1835with :doc:`ThreadSanitizer`. 1836 1837Use ``__has_feature(memory_sanitizer)`` to check if the code is being built 1838with :doc:`MemorySanitizer`. 1839 1840 1841Extensions for selectively disabling optimization 1842================================================= 1843 1844Clang provides a mechanism for selectively disabling optimizations in functions 1845and methods. 1846 1847To disable optimizations in a single function definition, the GNU-style or C++11 1848non-standard attribute ``optnone`` can be used. 1849 1850.. code-block:: c++ 1851 1852 // The following functions will not be optimized. 1853 // GNU-style attribute 1854 __attribute__((optnone)) int foo() { 1855 // ... code 1856 } 1857 // C++11 attribute 1858 [[clang::optnone]] int bar() { 1859 // ... code 1860 } 1861 1862To facilitate disabling optimization for a range of function definitions, a 1863range-based pragma is provided. Its syntax is ``#pragma clang optimize`` 1864followed by ``off`` or ``on``. 1865 1866All function definitions in the region between an ``off`` and the following 1867``on`` will be decorated with the ``optnone`` attribute unless doing so would 1868conflict with explicit attributes already present on the function (e.g. the 1869ones that control inlining). 1870 1871.. code-block:: c++ 1872 1873 #pragma clang optimize off 1874 // This function will be decorated with optnone. 1875 int foo() { 1876 // ... code 1877 } 1878 1879 // optnone conflicts with always_inline, so bar() will not be decorated. 1880 __attribute__((always_inline)) int bar() { 1881 // ... code 1882 } 1883 #pragma clang optimize on 1884 1885If no ``on`` is found to close an ``off`` region, the end of the region is the 1886end of the compilation unit. 1887 1888Note that a stray ``#pragma clang optimize on`` does not selectively enable 1889additional optimizations when compiling at low optimization levels. This feature 1890can only be used to selectively disable optimizations. 1891 1892The pragma has an effect on functions only at the point of their definition; for 1893function templates, this means that the state of the pragma at the point of an 1894instantiation is not necessarily relevant. Consider the following example: 1895 1896.. code-block:: c++ 1897 1898 template<typename T> T twice(T t) { 1899 return 2 * t; 1900 } 1901 1902 #pragma clang optimize off 1903 template<typename T> T thrice(T t) { 1904 return 3 * t; 1905 } 1906 1907 int container(int a, int b) { 1908 return twice(a) + thrice(b); 1909 } 1910 #pragma clang optimize on 1911 1912In this example, the definition of the template function ``twice`` is outside 1913the pragma region, whereas the definition of ``thrice`` is inside the region. 1914The ``container`` function is also in the region and will not be optimized, but 1915it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of 1916these two instantiations, ``twice`` will be optimized (because its definition 1917was outside the region) and ``thrice`` will not be optimized. 1918 1919Extensions for loop hint optimizations 1920====================================== 1921 1922The ``#pragma clang loop`` directive is used to specify hints for optimizing the 1923subsequent for, while, do-while, or c++11 range-based for loop. The directive 1924provides options for vectorization, interleaving, and unrolling. Loop hints can 1925be specified before any loop and will be ignored if the optimization is not safe 1926to apply. 1927 1928Vectorization and Interleaving 1929------------------------------ 1930 1931A vectorized loop performs multiple iterations of the original loop 1932in parallel using vector instructions. The instruction set of the target 1933processor determines which vector instructions are available and their vector 1934widths. This restricts the types of loops that can be vectorized. The vectorizer 1935automatically determines if the loop is safe and profitable to vectorize. A 1936vector instruction cost model is used to select the vector width. 1937 1938Interleaving multiple loop iterations allows modern processors to further 1939improve instruction-level parallelism (ILP) using advanced hardware features, 1940such as multiple execution units and out-of-order execution. The vectorizer uses 1941a cost model that depends on the register pressure and generated code size to 1942select the interleaving count. 1943 1944Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled 1945by ``interleave(enable)``. This is useful when compiling with ``-Os`` to 1946manually enable vectorization or interleaving. 1947 1948.. code-block:: c++ 1949 1950 #pragma clang loop vectorize(enable) 1951 #pragma clang loop interleave(enable) 1952 for(...) { 1953 ... 1954 } 1955 1956The vector width is specified by ``vectorize_width(_value_)`` and the interleave 1957count is specified by ``interleave_count(_value_)``, where 1958_value_ is a positive integer. This is useful for specifying the optimal 1959width/count of the set of target architectures supported by your application. 1960 1961.. code-block:: c++ 1962 1963 #pragma clang loop vectorize_width(2) 1964 #pragma clang loop interleave_count(2) 1965 for(...) { 1966 ... 1967 } 1968 1969Specifying a width/count of 1 disables the optimization, and is equivalent to 1970``vectorize(disable)`` or ``interleave(disable)``. 1971 1972Loop Unrolling 1973-------------- 1974 1975Unrolling a loop reduces the loop control overhead and exposes more 1976opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling 1977eliminates the loop and replaces it with an enumerated sequence of loop 1978iterations. Full unrolling is only possible if the loop trip count is known at 1979compile time. Partial unrolling replicates the loop body within the loop and 1980reduces the trip count. 1981 1982If ``unroll(full)`` is specified the unroller will attempt to fully unroll the 1983loop if the trip count is known at compile time. If the loop count is not known 1984or the fully unrolled code size is greater than the limit specified by the 1985`-pragma-unroll-threshold` command line option the loop will be partially 1986unrolled subject to the same limit. 1987 1988.. code-block:: c++ 1989 1990 #pragma clang loop unroll(full) 1991 for(...) { 1992 ... 1993 } 1994 1995The unroll count can be specified explicitly with ``unroll_count(_value_)`` where 1996_value_ is a positive integer. If this value is greater than the trip count the 1997loop will be fully unrolled. Otherwise the loop is partially unrolled subject 1998to the `-pragma-unroll-threshold` limit. 1999 2000.. code-block:: c++ 2001 2002 #pragma clang loop unroll_count(8) 2003 for(...) { 2004 ... 2005 } 2006 2007Unrolling of a loop can be prevented by specifying ``unroll(disable)``. 2008 2009Additional Information 2010---------------------- 2011 2012For convenience multiple loop hints can be specified on a single line. 2013 2014.. code-block:: c++ 2015 2016 #pragma clang loop vectorize_width(4) interleave_count(8) 2017 for(...) { 2018 ... 2019 } 2020 2021If an optimization cannot be applied any hints that apply to it will be ignored. 2022For example, the hint ``vectorize_width(4)`` is ignored if the loop is not 2023proven safe to vectorize. To identify and diagnose optimization issues use 2024`-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the 2025user guide for details. 2026