1 =========================
2 Clang Language Extensions
3 =========================
15 AutomaticReferenceCounting
20 This document describes the language extensions provided by Clang. In addition
21 to the language extensions listed here, Clang aims to support a broad range of
22 GCC extensions. Please see the `GCC manual
23 <http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on
26 .. _langext-feature_check:
28 Feature Checking Macros
29 =======================
31 Language extensions can be very useful, but only if you know you can depend on
32 them. In order to allow fine-grain features checks, we support three builtin
33 function-like macros. This allows you to directly test for a feature in your
34 code without having to resort to something like autoconf or fragile "compiler
40 This function-like macro takes a single identifier argument that is the name of
41 a builtin function. It evaluates to 1 if the builtin is supported or 0 if not.
42 It can be used like this:
46 #ifndef __has_builtin // Optional of course.
47 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
51 #if __has_builtin(__builtin_trap)
58 .. _langext-__has_feature-__has_extension:
60 ``__has_feature`` and ``__has_extension``
61 -----------------------------------------
63 These function-like macros take a single identifier argument that is the name
64 of a feature. ``__has_feature`` evaluates to 1 if the feature is both
65 supported by Clang and standardized in the current language standard or 0 if
66 not (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
68 current language (either as a language extension or a standard language
69 feature) or 0 if not. They can be used like this:
73 #ifndef __has_feature // Optional of course.
74 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
76 #ifndef __has_extension
77 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
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.
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.
92 .. _langext-has-feature-back-compat:
94 For backward compatibility, ``__has_feature`` can also be used to test
95 for support for non-standardized features, i.e. features not prefixed ``c_``,
96 ``cxx_`` or ``objc_``.
98 Another use of ``__has_feature`` is to check for compiler features not related
99 to the language standard, such as e.g. :doc:`AddressSanitizer
102 If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent
103 to ``__has_feature``.
105 The feature tag is described along with the language feature below.
107 The feature name or extension name can also be specified with a preceding and
108 following ``__`` (double underscore) to avoid interference from a macro with
109 the same name. For instance, ``__cxx_rvalue_references__`` can be used instead
110 of ``cxx_rvalue_references``.
112 ``__has_cpp_attribute``
113 -----------------------
115 This function-like macro takes a single argument that is the name of a
116 C++11-style attribute. The argument can either be a single identifier, or a
117 scoped identifier. If the attribute is supported, a nonzero value is returned.
118 If the attribute is a standards-based attribute, this macro returns a nonzero
119 value based on the year and month in which the attribute was voted into the
120 working draft. If the attribute is not supported by the current compliation
121 target, this macro evaluates to 0. It can be used like this:
125 #ifndef __has_cpp_attribute // Optional of course.
126 #define __has_cpp_attribute(x) 0 // Compatibility with non-clang compilers.
130 #if __has_cpp_attribute(clang::fallthrough)
131 #define FALLTHROUGH [[clang::fallthrough]]
137 The attribute identifier (but not scope) can also be specified with a preceding
138 and following ``__`` (double underscore) to avoid interference from a macro with
139 the same name. For instance, ``gnu::__const__`` can be used instead of
145 This function-like macro takes a single identifier argument that is the name of
146 a GNU-style attribute. It evaluates to 1 if the attribute is supported by the
147 current compilation target, or 0 if not. It can be used like this:
151 #ifndef __has_attribute // Optional of course.
152 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
156 #if __has_attribute(always_inline)
157 #define ALWAYS_INLINE __attribute__((always_inline))
159 #define ALWAYS_INLINE
163 The 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
165 instance, ``__always_inline__`` can be used instead of ``always_inline``.
168 ``__has_declspec_attribute``
169 ----------------------------
171 This function-like macro takes a single identifier argument that is the name of
172 an attribute implemented as a Microsoft-style ``__declspec`` attribute. It
173 evaluates to 1 if the attribute is supported by the current compilation target,
174 or 0 if not. It can be used like this:
178 #ifndef __has_declspec_attribute // Optional of course.
179 #define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers.
183 #if __has_declspec_attribute(dllexport)
184 #define DLLEXPORT __declspec(dllexport)
190 The 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
192 instance, ``__dllexport__`` can be used instead of ``dllexport``.
197 This function-like macro takes a single identifier argument that might be either
198 a reserved word or a regular identifier. It evaluates to 1 if the argument is just
199 a regular identifier and not a reserved word, in the sense that it can then be
200 used as the name of a user-defined function or variable. Otherwise it evaluates
201 to 0. It can be used like this:
206 #ifdef __is_identifier // Compatibility with non-clang compilers.
207 #if __is_identifier(__wchar_t)
208 typedef wchar_t __wchar_t;
212 __wchar_t WideCharacter;
215 Include File Checking Macros
216 ============================
218 Not all developments systems have the same include files. The
219 :ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow
220 you to check for the existence of an include file before doing a possibly
221 failing ``#include`` directive. Include file checking macros must be used
222 as expressions in ``#if`` or ``#elif`` preprocessing directives.
224 .. _langext-__has_include:
229 This function-like macro takes a single file name string argument that is the
230 name of an include file. It evaluates to 1 if the file can be found using the
231 include paths, or 0 otherwise:
235 // Note the two possible file name string formats.
236 #if __has_include("myinclude.h") && __has_include(<stdint.h>)
237 # include "myinclude.h"
240 To test for this feature, use ``#if defined(__has_include)``:
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"
251 .. _langext-__has_include_next:
253 ``__has_include_next``
254 ----------------------
256 This function-like macro takes a single file name string argument that is the
257 name of an include file. It is like ``__has_include`` except that it looks for
258 the second instance of the given file found in the include paths. It evaluates
259 to 1 if the second instance of the file can be found using the include paths,
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"
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"
276 Note that ``__has_include_next``, like the GNU extension ``#include_next``
277 directive, is intended for use in headers only, and will issue a warning if
278 used in the top-level compilation file. A warning will also be issued if an
279 absolute path is used in the file argument.
284 This function-like macro takes a string literal that represents a command line
285 option for a warning and returns true if that is a valid warning option.
289 #if __has_warning("-Wformat")
297 Defined to a string that contains the name of the main input file passed to
301 Defined to an integer value that starts at zero and is incremented each time
302 the ``__COUNTER__`` macro is expanded.
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.
309 Defined to the date and time of the last modification of the current source
313 Defined when compiling with Clang
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`.
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`.
327 ``__clang_patchlevel__``
328 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
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)``".
336 Vectors and Extended Vectors
337 ============================
339 Supports the GCC, OpenCL, AltiVec and NEON vector extensions.
341 OpenCL vector types are created using ``ext_vector_type`` attribute. It
342 support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example
347 typedef float float4 __attribute__((ext_vector_type(4)));
348 typedef float float2 __attribute__((ext_vector_type(2)));
350 float4 foo(float2 a, float2 b) {
357 Query for this feature with ``__has_extension(attribute_ext_vector_type)``.
359 Giving ``-maltivec`` option to clang enables support for AltiVec vector syntax
360 and functions. For example:
364 vector float foo(vector int a) {
366 b = vec_add(a, a) + a;
367 return (vector float)b;
370 NEON vector types are created using ``neon_vector_type`` and
371 ``neon_polyvector_type`` attributes. For example:
375 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
376 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
378 int8x8_t foo(int8x8_t a) {
387 Vector literals can be used to create vectors from a set of scalars, or
388 vectors. Either parentheses or braces form can be used. In the parentheses
389 form the number of literal values specified must be one, i.e. referring to a
390 scalar value, or must match the size of the vector type being created. If a
391 single scalar literal value is specified, the scalar literal value will be
392 replicated to all the components of the vector type. In the brackets form any
393 number of literals can be specified. For example:
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)));
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));
413 The table below shows the support for each operation by vector extension. A
414 dash indicates that an operation is not accepted according to a corresponding
417 ============================== ======= ======= ======= =======
418 Operator OpenCL AltiVec GCC NEON
419 ============================== ======= ======= ======= =======
421 unary operators +, -- yes yes yes --
422 ++, -- -- yes yes yes --
423 +,--,*,/,% yes yes yes --
424 bitwise operators &,|,^,~ yes yes yes --
426 !, &&, || yes -- -- --
427 ==, !=, >, <, >=, <= yes yes -- --
430 sizeof yes yes yes yes
431 C-style cast yes yes yes no
432 reinterpret_cast yes no yes no
433 static_cast yes no yes no
434 const_cast no no no no
435 ============================== ======= ======= ======= =======
437 See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
439 Messages on ``deprecated`` and ``unavailable`` Attributes
440 =========================================================
442 An optional string message can be added to the ``deprecated`` and
443 ``unavailable`` attributes. For example:
447 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
449 If the deprecated or unavailable declaration is used, the message will be
450 incorporated into the appropriate diagnostic:
454 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
455 [-Wdeprecated-declarations]
459 Query for this feature with
460 ``__has_extension(attribute_deprecated_with_message)`` and
461 ``__has_extension(attribute_unavailable_with_message)``.
463 Attributes on Enumerators
464 =========================
466 Clang allows attributes to be written on individual enumerators. This allows
467 enumerators to be deprecated, made unavailable, etc. The attribute must appear
468 after the enumerator name and before any initializer, like so:
475 OM_Terrified __attribute__((deprecated)),
476 OM_AbortOnError __attribute__((deprecated)) = 4
479 Attributes on the ``enum`` declaration do not apply to individual enumerators.
481 Query for this feature with ``__has_extension(enumerator_attributes)``.
483 'User-Specified' System Frameworks
484 ==================================
486 Clang provides a mechanism by which frameworks can be built in such a way that
487 they will always be treated as being "system frameworks", even if they are not
488 present in a system framework directory. This can be useful to system
489 framework developers who want to be able to test building other applications
490 with development builds of their framework, including the manner in which the
491 compiler changes warning behavior for system headers.
493 Framework developers can opt-in to this mechanism by creating a
494 "``.system_framework``" file at the top-level of their framework. That is, the
495 framework should have contents like:
499 .../TestFramework.framework
500 .../TestFramework.framework/.system_framework
501 .../TestFramework.framework/Headers
502 .../TestFramework.framework/Headers/TestFramework.h
505 Clang will treat the presence of this file as an indicator that the framework
506 should be treated as a system framework, regardless of how it was found in the
507 framework search path. For consistency, we recommend that such files never be
508 included in installed versions of the framework.
510 Checks for Standard Language Features
511 =====================================
513 The ``__has_feature`` macro can be used to query if certain standard language
514 features are enabled. The ``__has_extension`` macro can be used to query if
515 language features are available as an extension when compiling for a standard
516 which does not provide them. The features which can be tested are listed here.
518 Since Clang 3.4, the C++ SD-6 feature test macros are also supported.
519 These are macros with names of the form ``__cpp_<feature_name>``, and are
520 intended to be a portable way to query the supported features of the compiler.
521 See `the C++ status page <http://clang.llvm.org/cxx_status.html#ts>`_ for
522 information on the version of SD-6 supported by each Clang release, and the
523 macros provided by that revision of the recommendations.
528 The features listed below are part of the C++98 standard. These features are
529 enabled by default when compiling C++ code.
534 Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been
535 enabled. For example, compiling code with ``-fno-exceptions`` disables C++
541 Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For
542 example, compiling code with ``-fno-rtti`` disables the use of RTTI.
547 The features listed below are part of the C++11 standard. As a result, all
548 these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option
549 when compiling C++ code.
551 C++11 SFINAE includes access control
552 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
554 Use ``__has_feature(cxx_access_control_sfinae)`` or
555 ``__has_extension(cxx_access_control_sfinae)`` to determine whether
556 access-control errors (e.g., calling a private constructor) are considered to
557 be template argument deduction errors (aka SFINAE errors), per `C++ DR1170
558 <http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_.
560 C++11 alias templates
561 ^^^^^^^^^^^^^^^^^^^^^
563 Use ``__has_feature(cxx_alias_templates)`` or
564 ``__has_extension(cxx_alias_templates)`` to determine if support for C++11's
565 alias declarations and alias templates is enabled.
567 C++11 alignment specifiers
568 ^^^^^^^^^^^^^^^^^^^^^^^^^^
570 Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to
571 determine if support for alignment specifiers using ``alignas`` is enabled.
573 Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to
574 determine if support for the ``alignof`` keyword is enabled.
579 Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to
580 determine if support for attribute parsing with C++11's square bracket notation
583 C++11 generalized constant expressions
584 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
586 Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized
587 constant expressions (e.g., ``constexpr``) is enabled.
592 Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to
593 determine if support for the ``decltype()`` specifier is enabled. C++11's
594 ``decltype`` does not require type-completeness of a function call expression.
595 Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or
596 ``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if
597 support for this feature is enabled.
599 C++11 default template arguments in function templates
600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
602 Use ``__has_feature(cxx_default_function_template_args)`` or
603 ``__has_extension(cxx_default_function_template_args)`` to determine if support
604 for default template arguments in function templates is enabled.
606 C++11 ``default``\ ed functions
607 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
609 Use ``__has_feature(cxx_defaulted_functions)`` or
610 ``__has_extension(cxx_defaulted_functions)`` to determine if support for
611 defaulted function definitions (with ``= default``) is enabled.
613 C++11 delegating constructors
614 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
616 Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for
617 delegating constructors is enabled.
619 C++11 ``deleted`` functions
620 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
622 Use ``__has_feature(cxx_deleted_functions)`` or
623 ``__has_extension(cxx_deleted_functions)`` to determine if support for deleted
624 function definitions (with ``= delete``) is enabled.
626 C++11 explicit conversion functions
627 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
629 Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for
630 ``explicit`` conversion functions is enabled.
632 C++11 generalized initializers
633 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
635 Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for
636 generalized initializers (using braced lists and ``std::initializer_list``) is
639 C++11 implicit move constructors/assignment operators
640 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
642 Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly
643 generate move constructors and move assignment operators where needed.
645 C++11 inheriting constructors
646 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
648 Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for
649 inheriting constructors is enabled.
651 C++11 inline namespaces
652 ^^^^^^^^^^^^^^^^^^^^^^^
654 Use ``__has_feature(cxx_inline_namespaces)`` or
655 ``__has_extension(cxx_inline_namespaces)`` to determine if support for inline
656 namespaces is enabled.
661 Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to
662 determine if support for lambdas is enabled.
664 C++11 local and unnamed types as template arguments
665 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
667 Use ``__has_feature(cxx_local_type_template_args)`` or
668 ``__has_extension(cxx_local_type_template_args)`` to determine if support for
669 local and unnamed types as template arguments is enabled.
674 Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to
675 determine if support for noexcept exception specifications is enabled.
677 C++11 in-class non-static data member initialization
678 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
680 Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class
681 initialization of non-static data members is enabled.
686 Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to
687 determine if support for ``nullptr`` is enabled.
689 C++11 ``override control``
690 ^^^^^^^^^^^^^^^^^^^^^^^^^^
692 Use ``__has_feature(cxx_override_control)`` or
693 ``__has_extension(cxx_override_control)`` to determine if support for the
694 override control keywords is enabled.
696 C++11 reference-qualified functions
697 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
699 Use ``__has_feature(cxx_reference_qualified_functions)`` or
700 ``__has_extension(cxx_reference_qualified_functions)`` to determine if support
701 for reference-qualified functions (e.g., member functions with ``&`` or ``&&``
702 applied to ``*this``) is enabled.
704 C++11 range-based ``for`` loop
705 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
707 Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to
708 determine if support for the range-based for loop is enabled.
710 C++11 raw string literals
711 ^^^^^^^^^^^^^^^^^^^^^^^^^
713 Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw
714 string literals (e.g., ``R"x(foo\bar)x"``) is enabled.
716 C++11 rvalue references
717 ^^^^^^^^^^^^^^^^^^^^^^^
719 Use ``__has_feature(cxx_rvalue_references)`` or
720 ``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue
721 references is enabled.
723 C++11 ``static_assert()``
724 ^^^^^^^^^^^^^^^^^^^^^^^^^
726 Use ``__has_feature(cxx_static_assert)`` or
727 ``__has_extension(cxx_static_assert)`` to determine if support for compile-time
728 assertions using ``static_assert`` is enabled.
730 C++11 ``thread_local``
731 ^^^^^^^^^^^^^^^^^^^^^^
733 Use ``__has_feature(cxx_thread_local)`` to determine if support for
734 ``thread_local`` variables is enabled.
739 Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to
740 determine C++11 type inference is supported using the ``auto`` specifier. If
741 this is disabled, ``auto`` will instead be a storage class specifier, as in C
744 C++11 strongly typed enumerations
745 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
747 Use ``__has_feature(cxx_strong_enums)`` or
748 ``__has_extension(cxx_strong_enums)`` to determine if support for strongly
749 typed, scoped enumerations is enabled.
751 C++11 trailing return type
752 ^^^^^^^^^^^^^^^^^^^^^^^^^^
754 Use ``__has_feature(cxx_trailing_return)`` or
755 ``__has_extension(cxx_trailing_return)`` to determine if support for the
756 alternate function declaration syntax with trailing return type is enabled.
758 C++11 Unicode string literals
759 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
761 Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode
762 string literals is enabled.
764 C++11 unrestricted unions
765 ^^^^^^^^^^^^^^^^^^^^^^^^^
767 Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for
768 unrestricted unions is enabled.
770 C++11 user-defined literals
771 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
773 Use ``__has_feature(cxx_user_literals)`` to determine if support for
774 user-defined literals is enabled.
776 C++11 variadic templates
777 ^^^^^^^^^^^^^^^^^^^^^^^^
779 Use ``__has_feature(cxx_variadic_templates)`` or
780 ``__has_extension(cxx_variadic_templates)`` to determine if support for
781 variadic templates is enabled.
786 The features listed below are part of the C++14 standard. As a result, all
787 these features are enabled with the ``-std=C++14`` or ``-std=gnu++14`` option
788 when compiling C++ code.
790 C++14 binary literals
791 ^^^^^^^^^^^^^^^^^^^^^
793 Use ``__has_feature(cxx_binary_literals)`` or
794 ``__has_extension(cxx_binary_literals)`` to determine whether
795 binary literals (for instance, ``0b10010``) are recognized. Clang supports this
796 feature as an extension in all language modes.
798 C++14 contextual conversions
799 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
801 Use ``__has_feature(cxx_contextual_conversions)`` or
802 ``__has_extension(cxx_contextual_conversions)`` to determine if the C++14 rules
803 are used when performing an implicit conversion for an array bound in a
804 *new-expression*, the operand of a *delete-expression*, an integral constant
805 expression, or a condition in a ``switch`` statement.
810 Use ``__has_feature(cxx_decltype_auto)`` or
811 ``__has_extension(cxx_decltype_auto)`` to determine if support
812 for the ``decltype(auto)`` placeholder type is enabled.
814 C++14 default initializers for aggregates
815 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
817 Use ``__has_feature(cxx_aggregate_nsdmi)`` or
818 ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support
819 for default initializers in aggregate members is enabled.
821 C++14 digit separators
822 ^^^^^^^^^^^^^^^^^^^^^^
824 Use ``__cpp_digit_separators`` to determine if support for digit separators
825 using single quotes (for instance, ``10'000``) is enabled. At this time, there
826 is no corresponding ``__has_feature`` name
828 C++14 generalized lambda capture
829 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
831 Use ``__has_feature(cxx_init_captures)`` or
832 ``__has_extension(cxx_init_captures)`` to determine if support for
833 lambda captures with explicit initializers is enabled
834 (for instance, ``[n(0)] { return ++n; }``).
836 C++14 generic lambdas
837 ^^^^^^^^^^^^^^^^^^^^^
839 Use ``__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; }``).
844 C++14 relaxed constexpr
845 ^^^^^^^^^^^^^^^^^^^^^^^
847 Use ``__has_feature(cxx_relaxed_constexpr)`` or
848 ``__has_extension(cxx_relaxed_constexpr)`` to determine if variable
849 declarations, local variable modification, and control flow constructs
850 are permitted in ``constexpr`` functions.
852 C++14 return type deduction
853 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
855 Use ``__has_feature(cxx_return_type_deduction)`` or
856 ``__has_extension(cxx_return_type_deduction)`` to determine if support
857 for return type deduction for functions (using ``auto`` as a return type)
860 C++14 runtime-sized arrays
861 ^^^^^^^^^^^^^^^^^^^^^^^^^^
863 Use ``__has_feature(cxx_runtime_array)`` or
864 ``__has_extension(cxx_runtime_array)`` to determine if support
865 for arrays of runtime bound (a restricted form of variable-length arrays)
867 Clang's implementation of this feature is incomplete.
869 C++14 variable templates
870 ^^^^^^^^^^^^^^^^^^^^^^^^
872 Use ``__has_feature(cxx_variable_templates)`` or
873 ``__has_extension(cxx_variable_templates)`` to determine if support for
874 templated variable declarations is enabled.
879 The features listed below are part of the C11 standard. As a result, all these
880 features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when
881 compiling C code. Additionally, because these features are all
882 backward-compatible, they are available as extensions in all language modes.
884 C11 alignment specifiers
885 ^^^^^^^^^^^^^^^^^^^^^^^^
887 Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine
888 if support for alignment specifiers using ``_Alignas`` is enabled.
890 Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine
891 if support for the ``_Alignof`` keyword is enabled.
893 C11 atomic operations
894 ^^^^^^^^^^^^^^^^^^^^^
896 Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine
897 if 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
899 the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use
900 ``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header
903 Clang will use the system's ``<stdatomic.h>`` header when one is available, and
904 will otherwise use its own. When using its own, implementations of the atomic
905 operations are provided as macros. In the cases where C11 also requires a real
906 function, this header provides only the declaration of that function (along
907 with a shadowing macro implementation), and you must link to a library which
908 provides a definition of the function if you use it instead of the macro.
910 C11 generic selections
911 ^^^^^^^^^^^^^^^^^^^^^^
913 Use ``__has_feature(c_generic_selections)`` or
914 ``__has_extension(c_generic_selections)`` to determine if support for generic
915 selections is enabled.
917 As an extension, the C11 generic selection expression is available in all
918 languages supported by Clang. The syntax is the same as that given in the C11
921 In C, type compatibility is decided according to the rules given in the
922 appropriate standard, but in C++, which lacks the type compatibility rules used
923 in C, types are considered compatible only if they are equivalent.
925 C11 ``_Static_assert()``
926 ^^^^^^^^^^^^^^^^^^^^^^^^
928 Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)``
929 to determine if support for compile-time assertions using ``_Static_assert`` is
932 C11 ``_Thread_local``
933 ^^^^^^^^^^^^^^^^^^^^^
935 Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)``
936 to determine if support for ``_Thread_local`` variables is enabled.
941 Use ``__has_feature(modules)`` to determine if Modules have been enabled.
942 For example, compiling code with ``-fmodules`` enables the use of Modules.
944 More information could be found `here <http://clang.llvm.org/docs/Modules.html>`_.
946 Checks for Type Trait Primitives
947 ================================
949 Type trait primitives are special builtin constant expressions that can be used
950 by the standard C++ library to facilitate or simplify the implementation of
951 user-facing type traits in the <type_traits> header.
953 They are not intended to be used directly by user code because they are
954 implementation-defined and subject to change -- as such they're tied closely to
955 the supported set of system headers, currently:
959 * The Microsoft standard C++ library
961 Clang supports the `GNU C++ type traits
962 <http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the
963 `Microsoft Visual C++ Type traits
964 <http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_.
966 Feature detection is supported only for some of the primitives at present. User
967 code should not use these checks because they bear no direct relation to the
968 actual set of type traits supported by the C++ standard library.
970 For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the
971 type trait primitive in the compiler. A simplistic usage example as might be
972 seen in standard C++ headers follows:
976 #if __has_extension(is_convertible_to)
977 template<typename From, typename To>
978 struct is_convertible_to {
979 static const bool value = __is_convertible_to(From, To);
982 // Emulate type trait for compatibility with other compilers.
985 The following type trait primitives are supported by Clang:
987 * ``__has_nothrow_assign`` (GNU, Microsoft)
988 * ``__has_nothrow_copy`` (GNU, Microsoft)
989 * ``__has_nothrow_constructor`` (GNU, Microsoft)
990 * ``__has_trivial_assign`` (GNU, Microsoft)
991 * ``__has_trivial_copy`` (GNU, Microsoft)
992 * ``__has_trivial_constructor`` (GNU, Microsoft)
993 * ``__has_trivial_destructor`` (GNU, Microsoft)
994 * ``__has_virtual_destructor`` (GNU, Microsoft)
995 * ``__is_abstract`` (GNU, Microsoft)
996 * ``__is_aggregate`` (GNU, Microsoft)
997 * ``__is_base_of`` (GNU, Microsoft)
998 * ``__is_class`` (GNU, Microsoft)
999 * ``__is_convertible_to`` (Microsoft)
1000 * ``__is_empty`` (GNU, Microsoft)
1001 * ``__is_enum`` (GNU, Microsoft)
1002 * ``__is_interface_class`` (Microsoft)
1003 * ``__is_pod`` (GNU, Microsoft)
1004 * ``__is_polymorphic`` (GNU, Microsoft)
1005 * ``__is_union`` (GNU, Microsoft)
1006 * ``__is_literal(type)``: Determines whether the given type is a literal type
1007 * ``__is_final``: Determines whether the given type is declared with a
1008 ``final`` class-virt-specifier.
1009 * ``__underlying_type(type)``: Retrieves the underlying type for a given
1010 ``enum`` type. This trait is required to implement the C++11 standard
1012 * ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value
1013 of type ``totype`` can be assigned to from a value of type ``fromtype`` such
1014 that no non-trivial functions are called as part of that assignment. This
1015 trait is required to implement the C++11 standard library.
1016 * ``__is_trivially_constructible(type, argtypes...)``: Determines whether a
1017 value of type ``type`` can be direct-initialized with arguments of types
1018 ``argtypes...`` such that no non-trivial functions are called as part of
1019 that initialization. This trait is required to implement the C++11 standard
1021 * ``__is_destructible`` (MSVC 2013)
1022 * ``__is_nothrow_destructible`` (MSVC 2013)
1023 * ``__is_nothrow_assignable`` (MSVC 2013, clang)
1024 * ``__is_constructible`` (MSVC 2013, clang)
1025 * ``__is_nothrow_constructible`` (MSVC 2013, clang)
1026 * ``__is_assignable`` (MSVC 2015, clang)
1031 The syntax and high level language feature description is in
1032 :doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for
1033 the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`.
1035 Query for this feature with ``__has_extension(blocks)``.
1037 Objective-C Features
1038 ====================
1040 Related result types
1041 --------------------
1043 According to Cocoa conventions, Objective-C methods with certain names
1044 ("``init``", "``alloc``", etc.) always return objects that are an instance of
1045 the receiving class's type. Such methods are said to have a "related result
1046 type", meaning that a message send to one of these methods will have the same
1047 static type as an instance of the receiver class. For example, given the
1050 .. code-block:: objc
1057 @interface NSArray : NSObject
1060 and this common initialization pattern
1062 .. code-block:: objc
1064 NSArray *array = [[NSArray alloc] init];
1066 the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because
1067 ``alloc`` implicitly has a related result type. Similarly, the type of the
1068 expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a
1069 related result type and its receiver is known to have the type ``NSArray *``.
1070 If neither ``alloc`` nor ``init`` had a related result type, the expressions
1071 would have had type ``id``, as declared in the method signature.
1073 A method with a related result type can be declared by using the type
1074 ``instancetype`` as its result type. ``instancetype`` is a contextual keyword
1075 that is only permitted in the result type of an Objective-C method, e.g.
1077 .. code-block:: objc
1080 + (instancetype)constructAnA;
1083 The related result type can also be inferred for some methods. To determine
1084 whether a method has an inferred related result type, the first word in the
1085 camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered,
1086 and the method will have a related result type if its return type is compatible
1087 with the type of its class and if:
1089 * the first word is "``alloc``" or "``new``", and the method is a class method,
1092 * the first word is "``autorelease``", "``init``", "``retain``", or "``self``",
1093 and the method is an instance method.
1095 If a method with a related result type is overridden by a subclass method, the
1096 subclass method must also return a type that is compatible with the subclass
1099 .. code-block:: objc
1101 @interface NSString : NSObject
1102 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
1105 Related result types only affect the type of a message send or property access
1106 via the given method. In all other respects, a method with a related result
1107 type is treated the same way as method that returns ``id``.
1109 Use ``__has_feature(objc_instancetype)`` to determine whether the
1110 ``instancetype`` contextual keyword is available.
1112 Automatic reference counting
1113 ----------------------------
1115 Clang provides support for :doc:`automated reference counting
1116 <AutomaticReferenceCounting>` in Objective-C, which eliminates the need
1117 for manual ``retain``/``release``/``autorelease`` message sends. There are two
1118 feature macros associated with automatic reference counting:
1119 ``__has_feature(objc_arc)`` indicates the availability of automated reference
1120 counting in general, while ``__has_feature(objc_arc_weak)`` indicates that
1121 automated reference counting also includes support for ``__weak`` pointers to
1122 Objective-C objects.
1124 .. _objc-fixed-enum:
1126 Enumerations with a fixed underlying type
1127 -----------------------------------------
1129 Clang provides support for C++11 enumerations with a fixed underlying type
1130 within Objective-C. For example, one can write an enumeration type as:
1134 typedef enum : unsigned char { Red, Green, Blue } Color;
1136 This specifies that the underlying type, which is used to store the enumeration
1137 value, is ``unsigned char``.
1139 Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed
1140 underlying types is available in Objective-C.
1142 Interoperability with C++11 lambdas
1143 -----------------------------------
1145 Clang provides interoperability between C++11 lambdas and blocks-based APIs, by
1146 permitting a lambda to be implicitly converted to a block pointer with the
1147 corresponding signature. For example, consider an API such as ``NSArray``'s
1148 array-sorting method:
1150 .. code-block:: objc
1152 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr;
1154 ``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult
1155 (^)(id, id)``, and parameters of this type are generally provided with block
1156 literals as arguments. However, one can also use a C++11 lambda so long as it
1157 provides the same signature (in this case, accepting two parameters of type
1158 ``id`` and returning an ``NSComparisonResult``):
1160 .. code-block:: objc
1162 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
1164 const NSStringCompareOptions comparisonOptions
1165 = NSCaseInsensitiveSearch | NSNumericSearch |
1166 NSWidthInsensitiveSearch | NSForcedOrderingSearch;
1167 NSLocale *currentLocale = [NSLocale currentLocale];
1169 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
1170 NSRange string1Range = NSMakeRange(0, [s1 length]);
1171 return [s1 compare:s2 options:comparisonOptions
1172 range:string1Range locale:currentLocale];
1174 NSLog(@"sorted: %@", sorted);
1176 This code relies on an implicit conversion from the type of the lambda
1177 expression (an unnamed, local class type called the *closure type*) to the
1178 corresponding block pointer type. The conversion itself is expressed by a
1179 conversion operator in that closure type that produces a block pointer with the
1180 same signature as the lambda itself, e.g.,
1182 .. code-block:: objc
1184 operator NSComparisonResult (^)(id, id)() const;
1186 This conversion function returns a new block that simply forwards the two
1187 parameters to the lambda object (which it captures by copy), then returns the
1188 result. The returned block is first copied (with ``Block_copy``) and then
1189 autoreleased. As an optimization, if a lambda expression is immediately
1190 converted to a block pointer (as in the first example, above), then the block
1191 is not copied and autoreleased: rather, it is given the same lifetime as a
1192 block literal written at that point in the program, which avoids the overhead
1193 of copying a block to the heap in the common case.
1195 The conversion from a lambda to a block pointer is only available in
1196 Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory
1197 management (autorelease).
1199 Object Literals and Subscripting
1200 --------------------------------
1202 Clang provides support for :doc:`Object Literals and Subscripting
1203 <ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C
1204 programming patterns, makes programs more concise, and improves the safety of
1205 container creation. There are several feature macros associated with object
1206 literals and subscripting: ``__has_feature(objc_array_literals)`` tests the
1207 availability of array literals; ``__has_feature(objc_dictionary_literals)``
1208 tests the availability of dictionary literals;
1209 ``__has_feature(objc_subscripting)`` tests the availability of object
1212 Objective-C Autosynthesis of Properties
1213 ---------------------------------------
1215 Clang provides support for autosynthesis of declared properties. Using this
1216 feature, clang provides default synthesis of those properties not declared
1217 @dynamic and not having user provided backing getter and setter methods.
1218 ``__has_feature(objc_default_synthesize_properties)`` checks for availability
1219 of this feature in version of clang being used.
1221 .. _langext-objc-retain-release:
1223 Objective-C retaining behavior attributes
1224 -----------------------------------------
1226 In Objective-C, functions and methods are generally assumed to follow the
1227 `Cocoa Memory Management
1228 <http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_
1229 conventions for ownership of object arguments and
1230 return values. However, there are exceptions, and so Clang provides attributes
1231 to allow these exceptions to be documented. This are used by ARC and the
1232 `static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be
1233 better described using the ``objc_method_family`` attribute instead.
1235 **Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``,
1236 ``ns_returns_autoreleased``, ``cf_returns_retained``, and
1237 ``cf_returns_not_retained`` attributes can be placed on methods and functions
1238 that return Objective-C or CoreFoundation objects. They are commonly placed at
1239 the end of a function prototype or method declaration:
1241 .. code-block:: objc
1243 id foo() __attribute__((ns_returns_retained));
1245 - (NSString *)bar:(int)x __attribute__((ns_returns_retained));
1247 The ``*_returns_retained`` attributes specify that the returned object has a +1
1248 retain count. The ``*_returns_not_retained`` attributes specify that the return
1249 object has a +0 retain count, even if the normal convention for its selector
1250 would be +1. ``ns_returns_autoreleased`` specifies that the returned object is
1251 +0, but is guaranteed to live at least as long as the next flush of an
1254 **Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on
1255 an parameter declaration; they specify that the argument is expected to have a
1256 +1 retain count, which will be balanced in some way by the function or method.
1257 The ``ns_consumes_self`` attribute can only be placed on an Objective-C
1258 method; it specifies that the method expects its ``self`` parameter to have a
1259 +1 retain count, which it will balance in some way.
1261 .. code-block:: objc
1263 void foo(__attribute__((ns_consumed)) NSString *string);
1265 - (void) bar __attribute__((ns_consumes_self));
1266 - (void) baz:(id) __attribute__((ns_consumed)) x;
1268 Further examples of these attributes are available in the static analyzer's `list of annotations for analysis
1269 <http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_.
1271 Query for these features with ``__has_attribute(ns_consumed)``,
1272 ``__has_attribute(ns_returns_retained)``, etc.
1275 Objective-C++ ABI: protocol-qualifier mangling of parameters
1276 ------------------------------------------------------------
1278 Starting with LLVM 3.4, Clang produces a new mangling for parameters whose
1279 type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such
1280 parameters to be differentiated from those with the regular unqualified ``id``
1283 This was a non-backward compatible mangling change to the ABI. This change
1284 allows proper overloading, and also prevents mangling conflicts with template
1285 parameters of protocol-qualified type.
1287 Query the presence of this new mangling with
1288 ``__has_feature(objc_protocol_qualifier_mangling)``.
1290 .. _langext-overloading:
1292 Initializer lists for complex numbers in C
1293 ==========================================
1295 clang supports an extension which allows the following in C:
1300 #include <complex.h>
1301 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
1303 This construct is useful because there is no way to separately initialize the
1304 real and imaginary parts of a complex variable in standard C, given that clang
1305 does not support ``_Imaginary``. (Clang also supports the ``__real__`` and
1306 ``__imag__`` extensions from gcc, which help in some cases, but are not usable
1307 in static initializers.)
1309 Note that this extension does not allow eliding the braces; the meaning of the
1310 following two lines is different:
1314 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
1315 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
1317 This extension also works in C++ mode, as far as that goes, but does not apply
1318 to the C++ ``std::complex``. (In C++11, list initialization allows the same
1319 syntax to be used with ``std::complex`` with the same meaning.)
1324 Clang supports a number of builtin library functions with the same syntax as
1325 GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``,
1326 ``__builtin_choose_expr``, ``__builtin_types_compatible_p``,
1327 ``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to
1328 the GCC builtins, Clang supports a number of builtins that GCC does not, which
1331 Please note that Clang does not and will not support all of the GCC builtins
1332 for vector operations. Instead of using builtins, you should use the functions
1333 defined in target-specific header files like ``<xmmintrin.h>``, which define
1334 portable wrappers for these. Many of the Clang versions of these functions are
1335 implemented directly in terms of :ref:`extended vector support
1336 <langext-vectors>` instead of builtins, in order to reduce the number of
1337 builtins that we need to implement.
1339 ``__builtin_assume``
1340 ------------------------------
1342 ``__builtin_assume`` is used to provide the optimizer with a boolean
1343 invariant that is defined to be true.
1349 __builtin_assume(bool)
1356 __builtin_assume(x != 0);
1358 // The optimizer may short-circuit this check using the invariant.
1360 return do_something();
1362 return do_something_else();
1367 The boolean argument to this function is defined to be true. The optimizer may
1368 analyze the form of the expression provided as the argument and deduce from
1369 that information used to optimize the program. If the condition is violated
1370 during execution, the behavior is undefined. The argument itself is never
1371 evaluated, so any side effects of the expression will be discarded.
1373 Query for this feature with ``__has_builtin(__builtin_assume)``.
1375 ``__builtin_readcyclecounter``
1376 ------------------------------
1378 ``__builtin_readcyclecounter`` is used to access the cycle counter register (or
1379 a similar low-latency, high-accuracy clock) on those targets that support it.
1385 __builtin_readcyclecounter()
1391 unsigned long long t0 = __builtin_readcyclecounter();
1393 unsigned long long t1 = __builtin_readcyclecounter();
1394 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow
1398 The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value,
1399 which may be either global or process/thread-specific depending on the target.
1400 As the backing counters often overflow quickly (on the order of seconds) this
1401 should only be used for timing small intervals. When not supported by the
1402 target, the return value is always zero. This builtin takes no arguments and
1403 produces an unsigned long long result.
1405 Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note
1406 that even if present, its use may depend on run-time privilege or other OS
1409 .. _langext-__builtin_shufflevector:
1411 ``__builtin_shufflevector``
1412 ---------------------------
1414 ``__builtin_shufflevector`` is used to express generic vector
1415 permutation/shuffle/swizzle operations. This builtin is also very important
1416 for the implementation of various target-specific header files like
1423 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
1429 // identity operation - return 4-element vector v1.
1430 __builtin_shufflevector(v1, v1, 0, 1, 2, 3)
1432 // "Splat" element 0 of V1 into a 4-element result.
1433 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
1435 // Reverse 4-element vector V1.
1436 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
1438 // Concatenate every other element of 4-element vectors V1 and V2.
1439 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
1441 // Concatenate every other element of 8-element vectors V1 and V2.
1442 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
1444 // Shuffle v1 with some elements being undefined
1445 __builtin_shufflevector(v1, v1, 3, -1, 1, -1)
1449 The first two arguments to ``__builtin_shufflevector`` are vectors that have
1450 the same element type. The remaining arguments are a list of integers that
1451 specify the elements indices of the first two vectors that should be extracted
1452 and returned in a new vector. These element indices are numbered sequentially
1453 starting with the first vector, continuing into the second vector. Thus, if
1454 ``vec1`` is a 4-element vector, index 5 would refer to the second element of
1455 ``vec2``. An index of -1 can be used to indicate that the corresponding element
1456 in the returned vector is a don't care and can be optimized by the backend.
1458 The result of ``__builtin_shufflevector`` is a vector with the same element
1459 type as ``vec1``/``vec2`` but that has an element count equal to the number of
1462 Query for this feature with ``__has_builtin(__builtin_shufflevector)``.
1464 .. _langext-__builtin_convertvector:
1466 ``__builtin_convertvector``
1467 ---------------------------
1469 ``__builtin_convertvector`` is used to express generic vector
1470 type-conversion operations. The input vector and the output vector
1471 type must have the same number of elements.
1477 __builtin_convertvector(src_vec, dst_vec_type)
1483 typedef double vector4double __attribute__((__vector_size__(32)));
1484 typedef float vector4float __attribute__((__vector_size__(16)));
1485 typedef short vector4short __attribute__((__vector_size__(8)));
1486 vector4float vf; vector4short vs;
1488 // convert from a vector of 4 floats to a vector of 4 doubles.
1489 __builtin_convertvector(vf, vector4double)
1491 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] }
1493 // convert from a vector of 4 shorts to a vector of 4 floats.
1494 __builtin_convertvector(vs, vector4float)
1496 (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] }
1500 The first argument to ``__builtin_convertvector`` is a vector, and the second
1501 argument is a vector type with the same number of elements as the first
1504 The result of ``__builtin_convertvector`` is a vector with the same element
1505 type as the second argument, with a value defined in terms of the action of a
1506 C-style cast applied to each element of the first argument.
1508 Query for this feature with ``__has_builtin(__builtin_convertvector)``.
1510 ``__builtin_bitreverse``
1511 ------------------------
1513 * ``__builtin_bitreverse8``
1514 * ``__builtin_bitreverse16``
1515 * ``__builtin_bitreverse32``
1516 * ``__builtin_bitreverse64``
1522 __builtin_bitreverse32(x)
1528 uint8_t rev_x = __builtin_bitreverse8(x);
1529 uint16_t rev_x = __builtin_bitreverse16(x);
1530 uint32_t rev_y = __builtin_bitreverse32(y);
1531 uint64_t rev_z = __builtin_bitreverse64(z);
1535 The '``__builtin_bitreverse``' family of builtins is used to reverse
1536 the bitpattern of an integer value; for example ``0b10110110`` becomes
1539 ``__builtin_unreachable``
1540 -------------------------
1542 ``__builtin_unreachable`` is used to indicate that a specific point in the
1543 program cannot be reached, even if the compiler might otherwise think it can.
1544 This is useful to improve optimization and eliminates certain warnings. For
1545 example, without the ``__builtin_unreachable`` in the example below, the
1546 compiler assumes that the inline asm can fall through and prints a "function
1547 declared '``noreturn``' should not return" warning.
1553 __builtin_unreachable()
1559 void myabort(void) __attribute__((noreturn));
1560 void myabort(void) {
1562 __builtin_unreachable();
1567 The ``__builtin_unreachable()`` builtin has completely undefined behavior.
1568 Since it has undefined behavior, it is a statement that it is never reached and
1569 the optimizer can take advantage of this to produce better code. This builtin
1570 takes no arguments and produces a void result.
1572 Query for this feature with ``__has_builtin(__builtin_unreachable)``.
1574 ``__builtin_unpredictable``
1575 ---------------------------
1577 ``__builtin_unpredictable`` is used to indicate that a branch condition is
1578 unpredictable by hardware mechanisms such as branch prediction logic.
1584 __builtin_unpredictable(long long)
1590 if (__builtin_unpredictable(x > 0)) {
1596 The ``__builtin_unpredictable()`` builtin is expected to be used with control
1597 flow conditions such as in ``if`` and ``switch`` statements.
1599 Query for this feature with ``__has_builtin(__builtin_unpredictable)``.
1604 ``__sync_swap`` is used to atomically swap integers or pointers in memory.
1610 type __sync_swap(type *ptr, type value, ...)
1616 int old_value = __sync_swap(&value, new_value);
1620 The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of
1621 atomic intrinsics to allow code to atomically swap the current value with the
1622 new value. More importantly, it helps developers write more efficient and
1623 correct code by avoiding expensive loops around
1624 ``__sync_bool_compare_and_swap()`` or relying on the platform specific
1625 implementation details of ``__sync_lock_test_and_set()``. The
1626 ``__sync_swap()`` builtin is a full barrier.
1628 ``__builtin_addressof``
1629 -----------------------
1631 ``__builtin_addressof`` performs the functionality of the built-in ``&``
1632 operator, ignoring any ``operator&`` overload. This is useful in constant
1633 expressions in C++11, where there is no other way to take the address of an
1634 object that overloads ``operator&``.
1640 template<typename T> constexpr T *addressof(T &value) {
1641 return __builtin_addressof(value);
1644 ``__builtin_operator_new`` and ``__builtin_operator_delete``
1645 ------------------------------------------------------------
1647 ``__builtin_operator_new`` allocates memory just like a non-placement non-class
1648 *new-expression*. This is exactly like directly calling the normal
1649 non-placement ``::operator new``, except that it allows certain optimizations
1650 that the C++ standard does not permit for a direct function call to
1651 ``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and
1652 merging allocations).
1654 Likewise, ``__builtin_operator_delete`` deallocates memory just like a
1655 non-class *delete-expression*, and is exactly like directly calling the normal
1656 ``::operator delete``, except that it permits optimizations. Only the unsized
1657 form of ``__builtin_operator_delete`` is currently available.
1659 These builtins are intended for use in the implementation of ``std::allocator``
1660 and other similar allocation libraries, and are only available in C++.
1662 Multiprecision Arithmetic Builtins
1663 ----------------------------------
1665 Clang provides a set of builtins which expose multiprecision arithmetic in a
1666 manner amenable to C. They all have the following form:
1670 unsigned x = ..., y = ..., carryin = ..., carryout;
1671 unsigned sum = __builtin_addc(x, y, carryin, &carryout);
1673 Thus one can form a multiprecision addition chain in the following manner:
1677 unsigned *x, *y, *z, carryin=0, carryout;
1678 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout);
1680 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout);
1682 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout);
1684 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout);
1686 The complete list of builtins are:
1690 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
1691 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1692 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1693 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1694 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1695 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
1696 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1697 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1698 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1699 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1701 Checked Arithmetic Builtins
1702 ---------------------------
1704 Clang provides a set of builtins that implement checked arithmetic for security
1705 critical applications in a manner that is fast and easily expressable in C. As
1706 an example of their usage:
1710 errorcode_t security_critical_application(...) {
1711 unsigned x, y, result;
1713 if (__builtin_mul_overflow(x, y, &result))
1714 return kErrorCodeHackers;
1716 use_multiply(result);
1720 Clang provides the following checked arithmetic builtins:
1724 bool __builtin_add_overflow (type1 x, type2 y, type3 *sum);
1725 bool __builtin_sub_overflow (type1 x, type2 y, type3 *diff);
1726 bool __builtin_mul_overflow (type1 x, type2 y, type3 *prod);
1727 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum);
1728 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum);
1729 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum);
1730 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff);
1731 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff);
1732 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff);
1733 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod);
1734 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod);
1735 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod);
1736 bool __builtin_sadd_overflow (int x, int y, int *sum);
1737 bool __builtin_saddl_overflow (long x, long y, long *sum);
1738 bool __builtin_saddll_overflow(long long x, long long y, long long *sum);
1739 bool __builtin_ssub_overflow (int x, int y, int *diff);
1740 bool __builtin_ssubl_overflow (long x, long y, long *diff);
1741 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff);
1742 bool __builtin_smul_overflow (int x, int y, int *prod);
1743 bool __builtin_smull_overflow (long x, long y, long *prod);
1744 bool __builtin_smulll_overflow(long long x, long long y, long long *prod);
1746 Each builtin performs the specified mathematical operation on the
1747 first two arguments and stores the result in the third argument. If
1748 possible, the result will be equal to mathematically-correct result
1749 and the builtin will return 0. Otherwise, the builtin will return
1750 1 and the result will be equal to the unique value that is equivalent
1751 to the mathematically-correct result modulo two raised to the *k*
1752 power, where *k* is the number of bits in the result type. The
1753 behavior of these builtins is well-defined for all argument values.
1755 The first three builtins work generically for operands of any integer type,
1756 including boolean types. The operands need not have the same type as each
1757 other, or as the result. The other builtins may implicitly promote or
1758 convert their operands before performing the operation.
1760 Query for this feature with ``__has_builtin(__builtin_add_overflow)``, etc.
1762 Floating point builtins
1763 ---------------------------------------
1765 ``__builtin_canonicalize``
1766 --------------------------
1770 double __builtin_canonicalize(double);
1771 float __builtin_canonicalizef(float);
1772 long double__builtin_canonicalizel(long double);
1774 Returns the platform specific canonical encoding of a floating point
1775 number. This canonicalization is useful for implementing certain
1776 numeric primitives such as frexp. See `LLVM canonicalize intrinsic
1777 <http://llvm.org/docs/LangRef.html#llvm-canonicalize-intrinsic>`_ for
1778 more information on the semantics.
1783 Clang provides constant expression evaluation support for builtins forms of
1784 the following functions from the C standard library ``<string.h>`` header:
1799 In each case, the builtin form has the name of the C library function prefixed
1800 by ``__builtin_``. Example:
1804 void *p = __builtin_memchr("foobar", 'b', 5);
1806 In addition to the above, one further builtin is provided:
1810 char *__builtin_char_memchr(const char *haystack, int needle, size_t size);
1812 ``__builtin_char_memchr(a, b, c)`` is identical to
1813 ``(char*)__builtin_memchr(a, b, c)`` except that its use is permitted within
1814 constant expressions in C++11 onwards (where a cast from ``void*`` to ``char*``
1815 is disallowed in general).
1817 Support for constant expression evaluation for the above builtins be detected
1818 with ``__has_feature(cxx_constexpr_string_builtins)``.
1820 .. _langext-__c11_atomic:
1822 __c11_atomic builtins
1823 ---------------------
1825 Clang provides a set of builtins which are intended to be used to implement
1826 C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the
1827 ``_explicit`` form of the corresponding C11 operation, and are named with a
1828 ``__c11_`` prefix. The supported operations, and the differences from
1829 the corresponding C11 operations, are:
1831 * ``__c11_atomic_init``
1832 * ``__c11_atomic_thread_fence``
1833 * ``__c11_atomic_signal_fence``
1834 * ``__c11_atomic_is_lock_free`` (The argument is the size of the
1835 ``_Atomic(...)`` object, instead of its address)
1836 * ``__c11_atomic_store``
1837 * ``__c11_atomic_load``
1838 * ``__c11_atomic_exchange``
1839 * ``__c11_atomic_compare_exchange_strong``
1840 * ``__c11_atomic_compare_exchange_weak``
1841 * ``__c11_atomic_fetch_add``
1842 * ``__c11_atomic_fetch_sub``
1843 * ``__c11_atomic_fetch_and``
1844 * ``__c11_atomic_fetch_or``
1845 * ``__c11_atomic_fetch_xor``
1847 The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``,
1848 ``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are
1849 provided, with values corresponding to the enumerators of C11's
1850 ``memory_order`` enumeration.
1852 (Note that Clang additionally provides GCC-compatible ``__atomic_*``
1855 Low-level ARM exclusive memory builtins
1856 ---------------------------------------
1858 Clang provides overloaded builtins giving direct access to the three key ARM
1859 instructions for implementing atomic operations.
1863 T __builtin_arm_ldrex(const volatile T *addr);
1864 T __builtin_arm_ldaex(const volatile T *addr);
1865 int __builtin_arm_strex(T val, volatile T *addr);
1866 int __builtin_arm_stlex(T val, volatile T *addr);
1867 void __builtin_arm_clrex(void);
1869 The types ``T`` currently supported are:
1871 * Integer types with width at most 64 bits (or 128 bits on AArch64).
1872 * Floating-point types
1875 Note that the compiler does not guarantee it will not insert stores which clear
1876 the exclusive monitor in between an ``ldrex`` type operation and its paired
1877 ``strex``. In practice this is only usually a risk when the extra store is on
1878 the same cache line as the variable being modified and Clang will only insert
1879 stack stores on its own, so it is best not to use these operations on variables
1880 with automatic storage duration.
1882 Also, loads and stores may be implicit in code written between the ``ldrex`` and
1883 ``strex``. Clang will not necessarily mitigate the effects of these either, so
1884 care should be exercised.
1886 For these reasons the higher level atomic primitives should be preferred where
1889 Non-temporal load/store builtins
1890 --------------------------------
1892 Clang provides overloaded builtins allowing generation of non-temporal memory
1897 T __builtin_nontemporal_load(T *addr);
1898 void __builtin_nontemporal_store(T value, T *addr);
1900 The types ``T`` currently supported are:
1903 * Floating-point types.
1906 Note that the compiler does not guarantee that non-temporal loads or stores
1909 C++ Coroutines support builtins
1910 --------------------------------
1913 This is a work in progress. Compatibility across Clang/LLVM releases is not
1916 Clang provides experimental builtins to support C++ Coroutines as defined by
1917 http://wg21.link/P0057. The following four are intended to be used by the
1918 standard library to implement `std::experimental::coroutine_handle` type.
1924 void __builtin_coro_resume(void *addr);
1925 void __builtin_coro_destroy(void *addr);
1926 bool __builtin_coro_done(void *addr);
1927 void *__builtin_coro_promise(void *addr, int alignment, bool from_promise)
1933 template <> struct coroutine_handle<void> {
1934 void resume() const { __builtin_coro_resume(ptr); }
1935 void destroy() const { __builtin_coro_destroy(ptr); }
1936 bool done() const { return __builtin_coro_done(ptr); }
1942 template <typename Promise> struct coroutine_handle : coroutine_handle<> {
1944 Promise &promise() const {
1945 return *reinterpret_cast<Promise *>(
1946 __builtin_coro_promise(ptr, alignof(Promise), /*from-promise=*/false));
1948 static coroutine_handle from_promise(Promise &promise) {
1950 p.ptr = __builtin_coro_promise(&promise, alignof(Promise),
1951 /*from-promise=*/true);
1957 Other coroutine builtins are either for internal clang use or for use during
1958 development of the coroutine feature. See `Coroutines in LLVM
1959 <http://llvm.org/docs/Coroutines.html#intrinsics>`_ for
1960 more information on their semantics. Note that builtins matching the intrinsics
1961 that take token as the first parameter (llvm.coro.begin, llvm.coro.alloc,
1962 llvm.coro.free and llvm.coro.suspend) omit the token parameter and fill it to
1963 an appropriate value during the emission.
1969 size_t __builtin_coro_size()
1970 void *__builtin_coro_frame()
1971 void *__builtin_coro_free(void *coro_frame)
1973 void *__builtin_coro_id(int align, void *promise, void *fnaddr, void *parts)
1974 bool __builtin_coro_alloc()
1975 void *__builtin_coro_begin(void *memory)
1976 void __builtin_coro_end(void *coro_frame, bool unwind)
1977 char __builtin_coro_suspend(bool final)
1978 bool __builtin_coro_param(void *original, void *copy)
1980 Note that there is no builtin matching the `llvm.coro.save` intrinsic. LLVM
1981 automatically will insert one if the first argument to `llvm.coro.suspend` is
1982 token `none`. If a user calls `__builin_suspend`, clang will insert `token none`
1983 as the first argument to the intrinsic.
1985 Non-standard C++11 Attributes
1986 =============================
1988 Clang's non-standard C++11 attributes live in the ``clang`` attribute
1991 Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which
1992 are accepted with the ``__attribute__((foo))`` syntax are also accepted as
1993 ``[[gnu::foo]]``. This only extends to attributes which are specified by GCC
1994 (see the list of `GCC function attributes
1995 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable
1996 attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and
1997 `GCC type attributes
1998 <http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC
1999 implementation, these attributes must appertain to the *declarator-id* in a
2000 declaration, which means they must go either at the start of the declaration or
2001 immediately after the name being declared.
2003 For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and
2004 also applies the GNU ``noreturn`` attribute to ``f``.
2008 [[gnu::unused]] int a, f [[gnu::noreturn]] ();
2010 Target-Specific Extensions
2011 ==========================
2013 Clang supports some language features conditionally on some targets.
2015 ARM/AArch64 Language Extensions
2016 -------------------------------
2018 Memory Barrier Intrinsics
2019 ^^^^^^^^^^^^^^^^^^^^^^^^^
2020 Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined
2021 in the `ARM C Language Extensions Release 2.0
2022 <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_.
2023 Note that these intrinsics are implemented as motion barriers that block
2024 reordering of memory accesses and side effect instructions. Other instructions
2025 like simple arithmetic may be reordered around the intrinsic. If you expect to
2026 have no reordering at all, use inline assembly instead.
2028 X86/X86-64 Language Extensions
2029 ------------------------------
2031 The X86 backend has these language extensions:
2033 Memory references to specified segments
2034 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2036 Annotating a pointer with address space #256 causes it to be code generated
2037 relative to the X86 GS segment register, address space #257 causes it to be
2038 relative to the X86 FS segment, and address space #258 causes it to be
2039 relative to the X86 SS segment. Note that this is a very very low-level
2040 feature that should only be used if you know what you're doing (for example in
2047 #define GS_RELATIVE __attribute__((address_space(256)))
2048 int foo(int GS_RELATIVE *P) {
2052 Which compiles to (on X86-32):
2058 movl %gs:(%eax), %eax
2061 Extensions for Static Analysis
2062 ==============================
2064 Clang supports additional attributes that are useful for documenting program
2065 invariants and rules for static analysis tools, such as the `Clang Static
2066 Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented
2067 in the analyzer's `list of source-level annotations
2068 <http://clang-analyzer.llvm.org/annotations.html>`_.
2071 Extensions for Dynamic Analysis
2072 ===============================
2074 Use ``__has_feature(address_sanitizer)`` to check if the code is being built
2075 with :doc:`AddressSanitizer`.
2077 Use ``__has_feature(thread_sanitizer)`` to check if the code is being built
2078 with :doc:`ThreadSanitizer`.
2080 Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
2081 with :doc:`MemorySanitizer`.
2083 Use ``__has_feature(safe_stack)`` to check if the code is being built
2084 with :doc:`SafeStack`.
2087 Extensions for selectively disabling optimization
2088 =================================================
2090 Clang provides a mechanism for selectively disabling optimizations in functions
2093 To disable optimizations in a single function definition, the GNU-style or C++11
2094 non-standard attribute ``optnone`` can be used.
2098 // The following functions will not be optimized.
2099 // GNU-style attribute
2100 __attribute__((optnone)) int foo() {
2104 [[clang::optnone]] int bar() {
2108 To facilitate disabling optimization for a range of function definitions, a
2109 range-based pragma is provided. Its syntax is ``#pragma clang optimize``
2110 followed by ``off`` or ``on``.
2112 All function definitions in the region between an ``off`` and the following
2113 ``on`` will be decorated with the ``optnone`` attribute unless doing so would
2114 conflict with explicit attributes already present on the function (e.g. the
2115 ones that control inlining).
2119 #pragma clang optimize off
2120 // This function will be decorated with optnone.
2125 // optnone conflicts with always_inline, so bar() will not be decorated.
2126 __attribute__((always_inline)) int bar() {
2129 #pragma clang optimize on
2131 If no ``on`` is found to close an ``off`` region, the end of the region is the
2132 end of the compilation unit.
2134 Note that a stray ``#pragma clang optimize on`` does not selectively enable
2135 additional optimizations when compiling at low optimization levels. This feature
2136 can only be used to selectively disable optimizations.
2138 The pragma has an effect on functions only at the point of their definition; for
2139 function templates, this means that the state of the pragma at the point of an
2140 instantiation is not necessarily relevant. Consider the following example:
2144 template<typename T> T twice(T t) {
2148 #pragma clang optimize off
2149 template<typename T> T thrice(T t) {
2153 int container(int a, int b) {
2154 return twice(a) + thrice(b);
2156 #pragma clang optimize on
2158 In this example, the definition of the template function ``twice`` is outside
2159 the pragma region, whereas the definition of ``thrice`` is inside the region.
2160 The ``container`` function is also in the region and will not be optimized, but
2161 it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of
2162 these two instantiations, ``twice`` will be optimized (because its definition
2163 was outside the region) and ``thrice`` will not be optimized.
2165 Extensions for loop hint optimizations
2166 ======================================
2168 The ``#pragma clang loop`` directive is used to specify hints for optimizing the
2169 subsequent for, while, do-while, or c++11 range-based for loop. The directive
2170 provides options for vectorization, interleaving, unrolling and
2171 distribution. Loop hints can be specified before any loop and will be ignored if
2172 the optimization is not safe to apply.
2174 Vectorization and Interleaving
2175 ------------------------------
2177 A vectorized loop performs multiple iterations of the original loop
2178 in parallel using vector instructions. The instruction set of the target
2179 processor determines which vector instructions are available and their vector
2180 widths. This restricts the types of loops that can be vectorized. The vectorizer
2181 automatically determines if the loop is safe and profitable to vectorize. A
2182 vector instruction cost model is used to select the vector width.
2184 Interleaving multiple loop iterations allows modern processors to further
2185 improve instruction-level parallelism (ILP) using advanced hardware features,
2186 such as multiple execution units and out-of-order execution. The vectorizer uses
2187 a cost model that depends on the register pressure and generated code size to
2188 select the interleaving count.
2190 Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled
2191 by ``interleave(enable)``. This is useful when compiling with ``-Os`` to
2192 manually enable vectorization or interleaving.
2196 #pragma clang loop vectorize(enable)
2197 #pragma clang loop interleave(enable)
2202 The vector width is specified by ``vectorize_width(_value_)`` and the interleave
2203 count is specified by ``interleave_count(_value_)``, where
2204 _value_ is a positive integer. This is useful for specifying the optimal
2205 width/count of the set of target architectures supported by your application.
2209 #pragma clang loop vectorize_width(2)
2210 #pragma clang loop interleave_count(2)
2215 Specifying a width/count of 1 disables the optimization, and is equivalent to
2216 ``vectorize(disable)`` or ``interleave(disable)``.
2221 Unrolling a loop reduces the loop control overhead and exposes more
2222 opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling
2223 eliminates the loop and replaces it with an enumerated sequence of loop
2224 iterations. Full unrolling is only possible if the loop trip count is known at
2225 compile time. Partial unrolling replicates the loop body within the loop and
2226 reduces the trip count.
2228 If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the
2229 loop if the trip count is known at compile time. If the fully unrolled code size
2230 is greater than an internal limit the loop will be partially unrolled up to this
2231 limit. If the trip count is not known at compile time the loop will be partially
2232 unrolled with a heuristically chosen unroll factor.
2236 #pragma clang loop unroll(enable)
2241 If ``unroll(full)`` is specified the unroller will attempt to fully unroll the
2242 loop if the trip count is known at compile time identically to
2243 ``unroll(enable)``. However, with ``unroll(full)`` the loop will not be unrolled
2244 if the loop count is not known at compile time.
2248 #pragma clang loop unroll(full)
2253 The unroll count can be specified explicitly with ``unroll_count(_value_)`` where
2254 _value_ is a positive integer. If this value is greater than the trip count the
2255 loop will be fully unrolled. Otherwise the loop is partially unrolled subject
2256 to the same code size limit as with ``unroll(enable)``.
2260 #pragma clang loop unroll_count(8)
2265 Unrolling of a loop can be prevented by specifying ``unroll(disable)``.
2270 Loop Distribution allows splitting a loop into multiple loops. This is
2271 beneficial for example when the entire loop cannot be vectorized but some of the
2272 resulting loops can.
2274 If ``distribute(enable))`` is specified and the loop has memory dependencies
2275 that inhibit vectorization, the compiler will attempt to isolate the offending
2276 operations into a new loop. This optimization is not enabled by default, only
2277 loops marked with the pragma are considered.
2281 #pragma clang loop distribute(enable)
2282 for (i = 0; i < N; ++i) {
2283 S1: A[i + 1] = A[i] + B[i];
2284 S2: C[i] = D[i] * E[i];
2287 This loop will be split into two loops between statements S1 and S2. The
2288 second loop containing S2 will be vectorized.
2290 Loop Distribution is currently not enabled by default in the optimizer because
2291 it can hurt performance in some cases. For example, instruction-level
2292 parallelism could be reduced by sequentializing the execution of the
2293 statements S1 and S2 above.
2295 If Loop Distribution is turned on globally with
2296 ``-mllvm -enable-loop-distribution``, specifying ``distribute(disable)`` can
2297 be used the disable it on a per-loop basis.
2299 Additional Information
2300 ----------------------
2302 For convenience multiple loop hints can be specified on a single line.
2306 #pragma clang loop vectorize_width(4) interleave_count(8)
2311 If an optimization cannot be applied any hints that apply to it will be ignored.
2312 For example, the hint ``vectorize_width(4)`` is ignored if the loop is not
2313 proven safe to vectorize. To identify and diagnose optimization issues use
2314 `-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the
2315 user guide for details.
2317 Extensions to specify floating-point flags
2318 ====================================================
2320 The ``#pragma clang fp`` pragma allows floating-point options to be specified
2321 for a section of the source code. This pragma can only appear at file scope or
2322 at the start of a compound statement (excluding comments). When using within a
2323 compound statement, the pragma is active within the scope of the compound
2326 Currently, only FP contraction can be controlled with the pragma. ``#pragma
2327 clang fp contract`` specifies whether the compiler should contract a multiply
2328 and an addition (or subtraction) into a fused FMA operation when supported by
2331 The pragma can take three values: ``on``, ``fast`` and ``off``. The ``on``
2332 option is identical to using ``#pragma STDC FP_CONTRACT(ON)`` and it allows
2333 fusion as specified the language standard. The ``fast`` option allows fusiong
2334 in cases when the language standard does not make this possible (e.g. across
2340 #pragma clang fp contract(fast)
2346 The pragma can also be used with ``off`` which turns FP contraction off for a
2347 section of the code. This can be useful when fast contraction is otherwise
2348 enabled for the translation unit with the ``-ffp-contract=fast`` flag.
2350 Specifying an attribute for multiple declarations (#pragma clang attribute)
2351 ===========================================================================
2353 The ``#pragma clang attribute`` directive can be used to apply an attribute to
2354 multiple declarations. The ``#pragma clang attribute push`` variation of the
2355 directive pushes a new attribute to the attribute stack. The declarations that
2356 follow the pragma receive the attributes that are on the attribute stack, until
2357 the stack is cleared using a ``#pragma clang attribute pop`` directive. Multiple
2358 push directives can be nested inside each other.
2360 The attributes that are used in the ``#pragma clang attribute`` directives
2361 can be written using the GNU-style syntax:
2365 #pragma clang attribute push(__attribute__((annotate("custom"))), apply_to = function)
2367 void function(); // The function now has the annotate("custom") attribute
2369 #pragma clang attribute pop
2371 The attributes can also be written using the C++11 style syntax:
2375 #pragma clang attribute push([[noreturn]], apply_to = function)
2377 void function(); // The function now has the [[noreturn]] attribute
2379 #pragma clang attribute pop
2381 The ``__declspec`` style syntax is also supported:
2385 #pragma clang attribute push(__declspec(dllexport), apply_to = function)
2387 void function(); // The function now has the __declspec(dllexport) attribute
2389 #pragma clang attribute pop
2391 A single push directive accepts only one attribute regardless of the syntax
2397 The set of declarations that receive a single attribute from the attribute stack
2398 depends on the subject match rules that were specified in the pragma. Subject
2399 match rules are specified after the attribute. The compiler expects an
2400 identifier that corresponds to the subject set specifier. The ``apply_to``
2401 specifier is currently the only supported subject set specifier. It allows you
2402 to specify match rules that form a subset of the attribute's allowed subject
2403 set, i.e. the compiler doesn't require all of the attribute's subjects. For
2404 example, an attribute like ``[[nodiscard]]`` whose subject set includes
2405 ``enum``, ``record`` and ``hasType(functionType)``, requires the presence of at
2406 least one of these rules after ``apply_to``:
2410 #pragma clang attribute push([[nodiscard]], apply_to = enum)
2412 enum Enum1 { A1, B1 }; // The enum will receive [[nodiscard]]
2414 struct Record1 { }; // The struct will *not* receive [[nodiscard]]
2416 #pragma clang attribute pop
2418 #pragma clang attribute push([[nodiscard]], apply_to = any(record, enum))
2420 enum Enum2 { A2, B2 }; // The enum will receive [[nodiscard]]
2422 struct Record2 { }; // The struct *will* receive [[nodiscard]]
2424 #pragma clang attribute pop
2426 // This is an error, since [[nodiscard]] can't be applied to namespaces:
2427 #pragma clang attribute push([[nodiscard]], apply_to = any(record, namespace))
2429 #pragma clang attribute pop
2431 Multiple match rules can be specified using the ``any`` match rule, as shown
2432 in the example above. The ``any`` rule applies attributes to all declarations
2433 that are matched by at least one of the rules in the ``any``. It doesn't nest
2434 and can't be used inside the other match rules. Redundant match rules or rules
2435 that conflict with one another should not be used inside of ``any``.
2437 Clang supports the following match rules:
2439 - ``function``: Can be used to apply attributes to functions. This includes C++
2440 member functions, static functions, operators, and constructors/destructors.
2442 - ``function(is_member)``: Can be used to apply attributes to C++ member
2443 functions. This includes members like static functions, operators, and
2444 constructors/destructors.
2446 - ``hasType(functionType)``: Can be used to apply attributes to functions, C++
2447 member functions, and variables/fields whose type is a function pointer. It
2448 does not apply attributes to Objective-C methods or blocks.
2450 - ``type_alias``: Can be used to apply attributes to ``typedef`` declarations
2451 and C++11 type aliases.
2453 - ``record``: Can be used to apply attributes to ``struct``, ``class``, and
2454 ``union`` declarations.
2456 - ``record(unless(is_union))``: Can be used to apply attributes only to
2457 ``struct`` and ``class`` declarations.
2459 - ``enum``: Can be be used to apply attributes to enumeration declarations.
2461 - ``enum_constant``: Can be used to apply attributes to enumerators.
2463 - ``variable``: Can be used to apply attributes to variables, including
2464 local variables, parameters, global variables, and static member variables.
2465 It does not apply attributes to instance member variables or Objective-C
2468 - ``variable(is_thread_local)``: Can be used to apply attributes to thread-local
2471 - ``variable(is_global)``: Can be used to apply attributes to global variables
2474 - ``variable(is_parameter)``: Can be used to apply attributes to parameters
2477 - ``variable(unless(is_parameter))``: Can be used to apply attributes to all
2478 the variables that are not parameters.
2480 - ``field``: Can be used to apply attributes to non-static member variables
2481 in a record. This includes Objective-C ivars.
2483 - ``namespace``: Can be used to apply attributes to ``namespace`` declarations.
2485 - ``objc_interface``: Can be used to apply attributes to ``@interface``
2488 - ``objc_protocol``: Can be used to apply attributes to ``@protocol``
2491 - ``objc_category``: Can be used to apply attributes to category declarations,
2492 including class extensions.
2494 - ``objc_method``: Can be used to apply attributes to Objective-C methods,
2495 including instance and class methods. Implicit methods like implicit property
2496 getters and setters do not receive the attribute.
2498 - ``objc_method(is_instance)``: Can be used to apply attributes to Objective-C
2501 - ``objc_property``: Can be used to apply attributes to ``@property``
2504 - ``block``: Can be used to apply attributes to block declarations. This does
2505 not include variables/fields of block pointer type.
2507 The use of ``unless`` in match rules is currently restricted to a strict set of
2508 sub-rules that are used by the supported attributes. That means that even though
2509 ``variable(unless(is_parameter))`` is a valid match rule,
2510 ``variable(unless(is_thread_local))`` is not.
2512 Supported Attributes
2513 --------------------
2515 Not all attributes can be used with the ``#pragma clang attribute`` directive.
2516 Notably, statement attributes like ``[[fallthrough]]`` or type attributes
2517 like ``address_space`` aren't supported by this directive. You can determine
2518 whether or not an attribute is supported by the pragma by referring to the
2519 :doc:`individual documentation for that attribute <AttributeReference>`.
2521 The attributes are applied to all matching declarations individually, even when
2522 the attribute is semantically incorrect. The attributes that aren't applied to
2523 any declaration are not verified semantically.
2525 Specifying section names for global objects (#pragma clang section)
2526 ===================================================================
2528 The ``#pragma clang section`` directive provides a means to assign section-names
2529 to global variables, functions and static variables.
2531 The section names can be specified as:
2535 #pragma clang section bss="myBSS" data="myData" rodata="myRodata" text="myText"
2537 The section names can be reverted back to default name by supplying an empty
2538 string to the section kind, for example:
2542 #pragma clang section bss="" data="" text="" rodata=""
2544 The ``#pragma clang section`` directive obeys the following rules:
2546 * The pragma applies to all global variable, statics and function declarations
2547 from the pragma to the end of the translation unit.
2549 * The pragma clang section is enabled automatically, without need of any flags.
2551 * This feature is only defined to work sensibly for ELF targets.
2553 * If section name is specified through _attribute_((section("myname"))), then
2554 the attribute name gains precedence.
2556 * Global variables that are initialized to zero will be placed in the named
2557 bss section, if one is present.
2559 * The ``#pragma clang section`` directive does not does try to infer section-kind
2560 from the name. For example, naming a section "``.bss.mySec``" does NOT mean
2561 it will be a bss section name.
2563 * The decision about which section-kind applies to each global is taken in the back-end.
2564 Once the section-kind is known, appropriate section name, as specified by the user using
2565 ``#pragma clang section`` directive, is applied to that global.