Revision control
++ // Copyright (C) 2022 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \headerfile <QtCompilerDetection>
++ \inmodule QtCore
++ \title Compiler-specific Macro Definitions
++ \ingroup funclists
++
++ \brief The <QtCompilerDetection> header file includes various
++ compiler-specific macros.
++
++ The <QtCompilerDetection> header file provides a range of macros (Q_CC_*)
++ that are defined if the application is compiled using the specified
++ compiler. For example, the Q_CC_SUN macro is defined if the application is
++ compiled using Forte Developer, or Sun Studio C++.
++
++ The purpose of these macros is to enable programmers to add
++ compiler-specific code to their application.
++ */
++
++ /*!
++ \macro Q_CC_SYM
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Digital Mars C/C++
++ (used to be Symantec C++).
++ */
++
++ /*!
++ \macro Q_CC_MSVC
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Microsoft Visual
++ C/C++, Intel C++ for Windows.
++ */
++
++ /*!
++ \macro Q_CC_CLANG
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Clang.
++ */
++
++ /*!
++ \macro Q_CC_BOR
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Borland/Turbo C++.
++ */
++
++ /*!
++ \macro Q_CC_WAT
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Watcom C++.
++ */
++
++ /*!
++ \macro Q_CC_GNU
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using GNU Compiler Collection (GCC).
++ */
++
++ /*!
++ \macro Q_CC_COMEAU
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Comeau C++.
++ */
++
++ /*!
++ \macro Q_CC_EDG
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Edison Design Group
++ C++.
++ */
++
++ /*!
++ \macro Q_CC_OC
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using CenterLine C++.
++ */
++
++ /*!
++ \macro Q_CC_SUN
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Forte Developer, or
++ Sun Studio C++.
++ */
++
++ /*!
++ \macro Q_CC_MIPS
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using MIPSpro C++.
++ */
++
++ /*!
++ \macro Q_CC_DEC
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using DEC C++.
++ */
++
++ /*!
++ \macro Q_CC_HPACC
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using HP aC++.
++ */
++
++ /*!
++ \macro Q_CC_USLC
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using SCO OUDK and UDK.
++ */
++
++ /*!
++ \macro Q_CC_CDS
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Reliant C++.
++ */
++
++ /*!
++ \macro Q_CC_KAI
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using KAI C++.
++ */
++
++ /*!
++ \macro Q_CC_INTEL
++ \relates <QtCompilerDetection>
++ \obsolete
++
++ This macro used to be defined if the application was compiled with the old
++ Intel C++ compiler for Linux, macOS or Windows. The new oneAPI C++ compiler
++ is just a build of Clang and therefore does not define this macro.
++
++ \sa Q_CC_CLANG
++ */
++
++ /*!
++ \macro Q_CC_HIGHC
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using MetaWare High C/C++.
++ */
++
++ /*!
++ \macro Q_CC_PGI
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Portland Group C++.
++ */
++
++ /*!
++ \macro Q_CC_GHS
++ \relates <QtCompilerDetection>
++
++ Defined if the application is compiled using Green Hills
++ Optimizing C++ Compilers.
++ */
++
++ /*!
++ \macro void Q_FALLTHROUGH()
++ \relates <QtCompilerDetection>
++ \since 5.8
++
++ Can be used in switch statements at the end of case block to tell the compiler
++ and other developers that the lack of a break statement is intentional.
++
++ This is useful since a missing break statement is often a bug, and some
++ compilers can be configured to emit warnings when one is not found.
++
++ \sa Q_UNREACHABLE(), Q_UNREACHABLE_RETURN()
++ */
++
++ /*!
++ \macro Q_LIKELY(expr)
++ \relates <QtCompilerDetection>
++ \since 4.8
++
++ \brief Hints to the compiler that the enclosed condition, \a expr, is
++ likely to evaluate to \c true.
++
++ Use of this macro can help the compiler to optimize the code.
++
++ Example:
++
++ \snippet code/src_corelib_global_qglobal.cpp qlikely
++
++ \sa Q_UNLIKELY(), Q_LIKELY_BRANCH, Q_UNLIKELY_BRANCH
++ */
++
++ /*!
++ \macro Q_UNLIKELY(expr)
++ \relates <QtCompilerDetection>
++ \since 4.8
++
++ \brief Hints to the compiler that the enclosed condition, \a expr, is
++ likely to evaluate to \c false.
++
++ Use of this macro can help the compiler to optimize the code.
++
++ Example:
++
++ \snippet code/src_corelib_global_qglobal.cpp qunlikely
++
++ \sa Q_LIKELY(), Q_LIKELY_BRANCH, Q_UNLIKELY_BRANCH
++ */
++
++ /*!
++ \macro Q_LIKELY_BRANCH
++ \relates <QtCompilerDetection>
++ \since 6.9
++
++ \brief Hints to the compiler that the following block is likely to be
++ executed.
++
++ Use of this macro can help the compiler to optimize the code.
++
++ It is defined as the C++20 attribute \c{[[likely]]}, and is a no-op on
++ compilers that don't support it.
++
++ \sa Q_LIKELY(), Q_UNLIKELY(), Q_UNLIKELY_BRANCH
++ */
++
++ /*!
++ \macro Q_UNLIKELY_BRANCH
++ \relates <QtCompilerDetection>
++ \since 6.9
++
++ \brief Hints to the compiler that the following block is unlikely to be
++ executed.
++
++ Use of this macro can help the compiler to optimize the code.
++
++ It is defined as the C++20 attribute \c{[[unlikely]]}, and is a no-op on
++ compilers that don't support it.
++
++ \sa Q_LIKELY(), Q_UNLIKELY(), Q_LIKELY_BRANCH
++ */
++
++ /*!
++ \macro Q_CONSTINIT
++ \relates <QtCompilerDetection>
++ \since 6.4
++
++ \brief Enforces constant initialization when supported by the compiler.
++
++ If the compiler supports the C++20 \c{constinit} keyword, Clang's
++ \c{[[clang::require_constant_initialization]]} or GCC's \c{__constinit},
++ then this macro expands to the first one of these that is available,
++ otherwise it expands to nothing.
++
++ Variables marked as \c{constinit} cause a compile-error if their
++ initialization would have to be performed at runtime.
++
++ \note Constant-initialized variables may still have load-time impact if
++ they have non-trivial destruction.
++
++ For constants, you can use \c{constexpr} since C++11, but \c{constexpr}
++ makes variables \c{const}, too, whereas \c{constinit} ensures constant
++ initialization, but doesn't make the variable \c{const}:
++
++ \table
++ \header \li Keyword \li Added \li immutable \li constant-initialized
++ \row \li \c{const} \li C++98 \li yes \li not required
++ \row \li \c{constexpr} \li C++11 \li yes \li required
++ \row \li \c{constinit} \li C++20 \li no \li required
++ \endtable
++
++ If declaration and definition of a Q_CONSTINIT variable are separate, this
++ macro goes only on the definition, and not on the declaration:
++
++ \code
++ class C {
++ ~~~~
++ static int count; // declaration, no Q_CONSTINIT here
++ };
++ ~~~
++ Q_CONSTINIT int C::count = 0; // definition
++ \endcode
++ */
++
++ /*!
++ \macro Q_DECL_EXPORT
++ \relates <QtCompilerDetection>
++
++ This macro marks a symbol for shared library export (see
++ \l{sharedlibrary.html}{Creating Shared Libraries}).
++
++ \sa Q_DECL_IMPORT
++ */
++
++ /*!
++ \macro Q_DECL_IMPORT
++ \relates <QtCompilerDetection>
++
++ This macro declares a symbol to be an import from a shared library (see
++ \l{sharedlibrary.html}{Creating Shared Libraries}).
++
++ \sa Q_DECL_EXPORT
++ */
++
++ /*!
++ \macro Q_DECL_CONSTEXPR
++ \relates <QtCompilerDetection>
++ \deprecated [6.4] Use the \c constexpr keyword instead.
++
++ This macro can be used to declare variable that should be constructed at compile-time,
++ or an inline function that can be computed at compile-time.
++
++ \sa Q_DECL_RELAXED_CONSTEXPR, Q_DECL_CONSTEXPR_DTOR
++ */
++
++ /*!
++ \macro Q_DECL_RELAXED_CONSTEXPR
++ \relates <QtCompilerDetection>
++ \deprecated [6.4] Use the \c constexpr keyword instead.
++
++ This macro can be used to declare an inline function that can be computed
++ at compile-time according to the relaxed rules from C++14.
++
++ \sa Q_DECL_CONSTEXPR, Q_DECL_CONSTEXPR_DTOR
++ */
++
++ /*!
++ \macro Q_DECL_CONSTEXPR_DTOR
++ \relates <QtCompilerDetection>
++ \since 6.9
++
++ Expands to \c{constexpr} on compilers that support C++20, where
++ \c{__cpp_constexpr} has a value greater than or equal to \c{201907L}.
++ Otherwise, it expands to \c{inline}.
++
++ Use this macro to declare a destructor that can be computed at
++ compile-time in C++20 or later.
++
++ \sa Q_CONSTEXPR_DTOR
++ */
++
++ /*!
++ \macro Q_CONSTEXPR_DTOR
++ \relates <QtCompilerDetection>
++ \since 6.9
++
++ Expands to \c{constexpr} on compilers that support C++20, where
++ \c{__cpp_constexpr} has a value greater than or equal to \c{201907L}.
++ Otherwise, it expands to \c{const}.
++
++ Use this macro to declare a variable that can be constructed at compile-time
++ in C++20 or later.
++
++ \sa Q_DECL_CONSTEXPR_DTOR
++ */
++
++ /*!
++ \macro Q_DECL_EQ_DELETE_X(reason)
++ \relates <QtCompilerDetection>
++ \since 6.9
++
++ Expands to \c{= delete(reason)} on compilers that support C++26, where
++ \c{__cpp_deleted_function} has a value greater than or equal to \c{202403L}.
++ Otherwise, it expands to \c{= delete}.
++
++ Use this macro to declare a deleted function and also supply an error
++ message (the \a reason) to the user in case the function gets used
++ (explaining why the function was deleted).
++ */
++
++ /*!
++ \macro Q_DECL_NOTHROW
++ \relates <QtCompilerDetection>
++ \since 5.0
++ \deprecated [6.4] Use the \c noexcept keyword instead.
++
++ This macro marks a function as never throwing, under no
++ circumstances. If the function does nevertheless throw, the
++ behavior is undefined.
++
++ \sa Q_DECL_NOEXCEPT, Q_DECL_NOEXCEPT_EXPR()
++ */
++
++ /*!
++ \macro Q_DECL_NOEXCEPT
++ \relates <QtCompilerDetection>
++ \since 5.0
++ \deprecated [6.4] Use the \c noexcept keyword instead.
++
++ This macro marks a function as never throwing. If the function
++ does nevertheless throw, the behavior is defined:
++ std::terminate() is called.
++
++
++ \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT_EXPR()
++ */
++
++ /*!
++ \macro Q_DECL_NOEXCEPT_EXPR(x)
++ \relates <QtCompilerDetection>
++ \since 5.0
++ \deprecated [6.4] Use the \c noexcept keyword instead.
++
++ This macro marks a function as non-throwing if \a x is \c true. If
++ the function does nevertheless throw, the behavior is defined:
++ std::terminate() is called.
++
++
++ \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT
++ */
++
++ /*!
++ \macro Q_DECL_OVERRIDE
++ \since 5.0
++ \deprecated [5.15]
++ \relates <QtCompilerDetection>
++
++ This macro can be used to declare an overriding virtual
++ function. Use of this markup will allow the compiler to generate
++ an error if the overriding virtual function does not in fact
++ override anything.
++
++ It expands to "override".
++
++ The macro goes at the end of the function, usually after the
++ \c{const}, if any:
++ \snippet code/src_corelib_global_qglobal.cpp qdecloverride
++
++ \sa Q_DECL_FINAL
++ */
++
++ /*!
++ \macro Q_DECL_FINAL
++ \since 5.0
++ \deprecated [5.15]
++ \relates <QtCompilerDetection>
++
++ This macro can be used to declare an overriding virtual or a class
++ as "final", with Java semantics. Further-derived classes can then
++ no longer override this virtual function, or inherit from this
++ class, respectively.
++
++ It expands to "final".
++
++ The macro goes at the end of the function, usually after the
++ \c{const}, if any:
++ \snippet code/src_corelib_global_qglobal.cpp qdeclfinal-1
++
++ For classes, it goes in front of the \c{:} in the class
++ definition, if any:
++ \snippet code/src_corelib_global_qglobal.cpp qdeclfinal-2
++
++ \sa Q_DECL_OVERRIDE
++ */
++
++ /*!
++ \macro const char *Q_FUNC_INFO
++ \relates <QtCompilerDetection>
++
++ Expands to a string that describe the function the macro resides in. How this string looks
++ more specifically is compiler dependent. With GNU GCC it is typically the function signature,
++ while with other compilers it might be the line and column number.
++
++ Q_FUNC_INFO can be conveniently used with qDebug(). For example, this function:
++
++ \snippet code/src_corelib_global_qglobal.cpp 22
++
++ when instantiated with the integer type, will with the GCC compiler produce:
++
++ \tt{const TInputType& myMin(const TInputType&, const TInputType&) [with TInputType = int] was called with value1: 3 value2: 4}
++
++ If this macro is used outside a function, the behavior is undefined.
++ */
++
++ /*!
++ \macro Q_NODISCARD_CTOR
++ \relates <QtCompilerDetection>
++ \since 6.6
++
++ \brief Expands to \c{[[nodiscard]]} on compilers that accept it on constructors.
++
++ Otherwise it expands to nothing.
++
++ Constructors marked as Q_NODISCARD_CTOR cause a compiler warning if a call
++ site doesn't use the resulting object.
++
++ This macro is exists solely to prevent warnings on compilers that don't
++ implement the feature. If your supported platforms all allow \c{[[nodiscard]]}
++ on constructors, we strongly recommend you use the C++ attribute directly instead
++ of this macro.
++
++ \sa Q_NODISCARD_CTOR_X
++ */
++
++ /*!
++ \macro Q_NODISCARD_X(message)
++ \macro Q_NODISCARD_CTOR_X(message)
++ \relates <QtCompilerDetection>
++ \since 6.7
++
++ \brief Expand to \c{[[nodiscard(message)]]} on compilers that support the feature.
++
++ Otherwise they expand to \c {[[nodiscard]]} and Q_NODISCARD_CTOR, respectively.
++
++ \sa Q_NODISCARD_CTOR
++ */
++
++ /*!
++ \macro Q_DECL_NONBLOCKING_FUNCTION
++ \relates <QtCompilerDetection>
++ \since 6.12
++
++ \brief Expands to \c{[[clang::nonblocking]]} on clang compilers that support the feature.
++
++ Declares that the function never blocks on a lock, heap-allocates memory or throws an exception.
++
++ Used by clang's \l{https://clang.llvm.org/docs/FunctionEffectAnalysis.html}{Function Effect Analysis}
++ and \l{https://clang.llvm.org/docs/RealtimeSanitizer.html}{Realtime Sanitizer}.
++
++ \sa Q_DECL_NONALLOCATING_FUNCTION
++ */
++
++ /*!
++ \macro Q_DECL_NONALLOCATING_FUNCTION
++ \relates <QtCompilerDetection>
++ \since 6.12
++
++ \brief Expands to \c{[[clang::nonallocating]]} on clang compilers that support the feature.
++
++ Declares that the function never heap-allocates memory or throws an exception.
++
++ Used by clang's \l{https://clang.llvm.org/docs/FunctionEffectAnalysis.html}{Function Effect Analysis}
++ and \l{https://clang.llvm.org/docs/RealtimeSanitizer.html}{Realtime Sanitizer}.
++
++ \sa Q_DECL_NONBLOCKING_FUNCTION
++ */