diff options
Diffstat (limited to 'docs/LanguageExtensions.rst')
| -rw-r--r-- | docs/LanguageExtensions.rst | 236 |
1 files changed, 207 insertions, 29 deletions
diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index 35f759f4cf97..035b50d10824 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -109,12 +109,42 @@ following ``__`` (double underscore) to avoid interference from a macro with the same name. For instance, ``__cxx_rvalue_references__`` can be used instead of ``cxx_rvalue_references``. +``__has_cpp_attribute`` +----------------------- + +This function-like macro takes a single argument that is the name of a +C++11-style attribute. The argument can either be a single identifier, or a +scoped identifier. If the attribute is supported, a nonzero value is returned. +If the attribute is a standards-based attribute, this macro returns a nonzero +value based on the year and month in which the attribute was voted into the +working draft. If the attribute is not supported by the current compliation +target, this macro evaluates to 0. It can be used like this: + +.. code-block:: c++ + + #ifndef __has_cpp_attribute // Optional of course. + #define __has_cpp_attribute(x) 0 // Compatibility with non-clang compilers. + #endif + + ... + #if __has_cpp_attribute(clang::fallthrough) + #define FALLTHROUGH [[clang::fallthrough]] + #else + #define FALLTHROUGH + #endif + ... + +The attribute identifier (but not scope) can also be specified with a preceding +and following ``__`` (double underscore) to avoid interference from a macro with +the same name. For instance, ``gnu::__const__`` can be used instead of +``gnu::const``. + ``__has_attribute`` ------------------- This function-like macro takes a single identifier argument that is the name of -an attribute. It evaluates to 1 if the attribute is supported by the current -compilation target, or 0 if not. It can be used like this: +a GNU-style attribute. It evaluates to 1 if the attribute is supported by the +current compilation target, or 0 if not. It can be used like this: .. code-block:: c++ @@ -134,6 +164,33 @@ The attribute name can also be specified with a preceding and following ``__`` (double underscore) to avoid interference from a macro with the same name. For instance, ``__always_inline__`` can be used instead of ``always_inline``. + +``__has_declspec_attribute`` +---------------------------- + +This function-like macro takes a single identifier argument that is the name of +an attribute implemented as a Microsoft-style ``__declspec`` attribute. It +evaluates to 1 if the attribute is supported by the current compilation target, +or 0 if not. It can be used like this: + +.. code-block:: c++ + + #ifndef __has_declspec_attribute // Optional of course. + #define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers. + #endif + + ... + #if __has_declspec_attribute(dllexport) + #define DLLEXPORT __declspec(dllexport) + #else + #define DLLEXPORT + #endif + ... + +The attribute name can also be specified with a preceding and following ``__`` +(double underscore) to avoid interference from a macro with the same name. For +instance, ``__dllexport__`` can be used instead of ``dllexport``. + ``__is_identifier`` ------------------- @@ -357,23 +414,27 @@ The table below shows the support for each operation by vector extension. A dash indicates that an operation is not accepted according to a corresponding specification. -============================== ====== ======= === ==== - Opeator OpenCL AltiVec GCC NEON -============================== ====== ======= === ==== -[] yes yes yes -- -unary operators +, -- yes yes yes -- -++, -- -- yes yes yes -- -+,--,*,/,% yes yes yes -- -bitwise operators &,|,^,~ yes yes yes -- ->>,<< yes yes yes -- -!, &&, || no -- -- -- -==, !=, >, <, >=, <= yes yes -- -- -= yes yes yes yes -:? yes -- -- -- -sizeof yes yes yes yes -============================== ====== ======= === ==== - -See also :ref:`langext-__builtin_shufflevector`. +============================== ======= ======= ======= ======= + Opeator OpenCL AltiVec GCC NEON +============================== ======= ======= ======= ======= +[] yes yes yes -- +unary operators +, -- yes yes yes -- +++, -- -- yes yes yes -- ++,--,*,/,% yes yes yes -- +bitwise operators &,|,^,~ yes yes yes -- +>>,<< yes yes yes -- +!, &&, || yes -- -- -- +==, !=, >, <, >=, <= yes yes -- -- += yes yes yes yes +:? yes -- -- -- +sizeof yes yes yes yes +C-style cast yes yes yes no +reinterpret_cast yes no yes no +static_cast yes no yes no +const_cast no no no no +============================== ======= ======= ======= ======= + +See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`. Messages on ``deprecated`` and ``unavailable`` Attributes ========================================================= @@ -454,6 +515,13 @@ features are enabled. The ``__has_extension`` macro can be used to query if language features are available as an extension when compiling for a standard which does not provide them. The features which can be tested are listed here. +Since Clang 3.4, the C++ SD-6 feature test macros are also supported. +These are macros with names of the form ``__cpp_<feature_name>``, and are +intended to be a portable way to query the supported features of the compiler. +See `the C++ status page <http://clang.llvm.org/cxx_status.html#ts>`_ for +information on the version of SD-6 supported by each Clang release, and the +macros provided by that revision of the recommendations. + C++98 ----- @@ -502,6 +570,9 @@ C++11 alignment specifiers Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to determine if support for alignment specifiers using ``alignas`` is enabled. +Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to +determine if support for the ``alignof`` keyword is enabled. + C++11 attributes ^^^^^^^^^^^^^^^^ @@ -747,6 +818,13 @@ Use ``__has_feature(cxx_aggregate_nsdmi)`` or ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support for default initializers in aggregate members is enabled. +C++1y digit separators +^^^^^^^^^^^^^^^^^^^^^^ + +Use ``__cpp_digit_separators`` to determine if support for digit separators +using single quotes (for instance, ``10'000``) is enabled. At this time, there +is no corresponding ``__has_feature`` name + C++1y generalized lambda capture ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -809,13 +887,25 @@ C11 alignment specifiers Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine if support for alignment specifiers using ``_Alignas`` is enabled. +Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine +if support for the ``_Alignof`` keyword is enabled. + C11 atomic operations ^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine if support for atomic types using ``_Atomic`` is enabled. Clang also provides :ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement -the ``<stdatomic.h>`` operations on ``_Atomic`` types. +the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use +``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header +is available. + +Clang will use the system's ``<stdatomic.h>`` header when one is available, and +will otherwise use its own. When using its own, implementations of the atomic +operations are provided as macros. In the cases where C11 also requires a real +function, this header provides only the declaration of that function (along +with a shadowing macro implementation), and you must link to a library which +provides a definition of the function if you use it instead of the macro. C11 generic selections ^^^^^^^^^^^^^^^^^^^^^^ @@ -1224,8 +1314,9 @@ Builtin Functions Clang supports a number of builtin library functions with the same syntax as GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``, ``__builtin_choose_expr``, ``__builtin_types_compatible_p``, -``__sync_fetch_and_add``, etc. In addition to the GCC builtins, Clang supports -a number of builtins that GCC does not, which are listed here. +``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to +the GCC builtins, Clang supports a number of builtins that GCC does not, which +are listed here. Please note that Clang does not and will not support all of the GCC builtins for vector operations. Instead of using builtins, you should use the functions @@ -1235,6 +1326,42 @@ implemented directly in terms of :ref:`extended vector support <langext-vectors>` instead of builtins, in order to reduce the number of builtins that we need to implement. +``__builtin_assume`` +------------------------------ + +``__builtin_assume`` is used to provide the optimizer with a boolean +invariant that is defined to be true. + +**Syntax**: + +.. code-block:: c++ + + __builtin_assume(bool) + +**Example of Use**: + +.. code-block:: c++ + + int foo(int x) { + __builtin_assume(x != 0); + + // The optimizer may short-circuit this check using the invariant. + if (x == 0) + return do_something(); + + return do_something_else(); + } + +**Description**: + +The boolean argument to this function is defined to be true. The optimizer may +analyze the form of the expression provided as the argument and deduce from +that information used to optimize the program. If the condition is violated +during execution, the behavior is undefined. The argument itself is never +evaluated, so any side effects of the expression will be discarded. + +Query for this feature with ``__has_builtin(__builtin_assume)``. + ``__builtin_readcyclecounter`` ------------------------------ @@ -1324,6 +1451,8 @@ indices specified. Query for this feature with ``__has_builtin(__builtin_shufflevector)``. +.. _langext-__builtin_convertvector: + ``__builtin_convertvector`` --------------------------- @@ -1354,7 +1483,7 @@ type must have the same number of elements. // convert from a vector of 4 shorts to a vector of 4 floats. __builtin_convertvector(vs, vector4float) // equivalent to: - (vector4float) { (float) vf[0], (float) vf[1], (float) vf[2], (float) vf[3] } + (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] } **Description**: @@ -1554,12 +1683,14 @@ __c11_atomic builtins Clang provides a set of builtins which are intended to be used to implement C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the ``_explicit`` form of the corresponding C11 operation, and are named with a -``__c11_`` prefix. The supported operations are: +``__c11_`` prefix. The supported operations, and the differences from +the corresponding C11 operations, are: * ``__c11_atomic_init`` * ``__c11_atomic_thread_fence`` * ``__c11_atomic_signal_fence`` -* ``__c11_atomic_is_lock_free`` +* ``__c11_atomic_is_lock_free`` (The argument is the size of the + ``_Atomic(...)`` object, instead of its address) * ``__c11_atomic_store`` * ``__c11_atomic_load`` * ``__c11_atomic_exchange`` @@ -1571,6 +1702,11 @@ C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the * ``__c11_atomic_fetch_or`` * ``__c11_atomic_fetch_xor`` +The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, +``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are +provided, with values corresponding to the enumerators of C11's +``memory_order`` enumeration. + Low-level ARM exclusive memory builtins --------------------------------------- @@ -1780,15 +1916,17 @@ it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of these two instantiations, ``twice`` will be optimized (because its definition was outside the region) and ``thrice`` will not be optimized. -.. _langext-pragma-loop: - Extensions for loop hint optimizations ====================================== The ``#pragma clang loop`` directive is used to specify hints for optimizing the subsequent for, while, do-while, or c++11 range-based for loop. The directive -provides options for vectorization and interleaving. Loop hints can be specified -before any loop and will be ignored if the optimization is not safe to apply. +provides options for vectorization, interleaving, and unrolling. Loop hints can +be specified before any loop and will be ignored if the optimization is not safe +to apply. + +Vectorization and Interleaving +------------------------------ A vectorized loop performs multiple iterations of the original loop in parallel using vector instructions. The instruction set of the target @@ -1831,6 +1969,46 @@ width/count of the set of target architectures supported by your application. Specifying a width/count of 1 disables the optimization, and is equivalent to ``vectorize(disable)`` or ``interleave(disable)``. +Loop Unrolling +-------------- + +Unrolling a loop reduces the loop control overhead and exposes more +opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling +eliminates the loop and replaces it with an enumerated sequence of loop +iterations. Full unrolling is only possible if the loop trip count is known at +compile time. Partial unrolling replicates the loop body within the loop and +reduces the trip count. + +If ``unroll(full)`` is specified the unroller will attempt to fully unroll the +loop if the trip count is known at compile time. If the loop count is not known +or the fully unrolled code size is greater than the limit specified by the +`-pragma-unroll-threshold` command line option the loop will be partially +unrolled subject to the same limit. + +.. code-block:: c++ + + #pragma clang loop unroll(full) + for(...) { + ... + } + +The unroll count can be specified explicitly with ``unroll_count(_value_)`` where +_value_ is a positive integer. If this value is greater than the trip count the +loop will be fully unrolled. Otherwise the loop is partially unrolled subject +to the `-pragma-unroll-threshold` limit. + +.. code-block:: c++ + + #pragma clang loop unroll_count(8) + for(...) { + ... + } + +Unrolling of a loop can be prevented by specifying ``unroll(disable)``. + +Additional Information +---------------------- + For convenience multiple loop hints can be specified on a single line. .. code-block:: c++ |