Revision control
++ // Copyright (C) 2023 The Qt Company Ltd.
++ // Copyright (C) 2023 Intel Corporation.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \fn qYieldCpu()
++ \inmodule QtCore
++ \ingroup thread
++ \relates QAtomicInteger
++ //! \relatesalso QAtomicPointer
++ \since 6.7
++
++ Pauses the execution of the current thread for an unspecified time, using
++ hardware instructions, without de-scheduling this thread. This function is
++ meant to be used in high-throughput loops where the code expects another
++ thread to modify an atomic variable. This is completely different from
++ QThread::yieldCurrentThread(), which is an OS-level operation that may take
++ the whole thread off the CPU and allow other threads (possibly belonging to
++ other processes) to run.
++
++ So, instead of
++ \code
++ while (!condition)
++ ;
++ \endcode
++
++ one should write
++ \code
++ while (!condition)
++ qYieldCpu();
++ \endcode
++
++ This is useful both with and without hardware multithreading on the same
++ core. In the case of hardware threads, it serves to prevent further
++ speculative execution filling up the pipeline, which could starve the
++ sibling thread of resources. Across cores and higher levels of separation,
++ it allows the cache coherency protocol to allocate the cache line being
++ modified and inspected to the logical processor whose result this code is
++ expecting.
++
++ It is also recommended to loop around code that does not modify the global
++ variable, to avoid contention in exclusively obtaining the memory location.
++ Therefore, an atomic modification loop such as a spinlock acquisition
++ should be:
++
++ \code
++ while (true) {
++ while (!readOnlyCondition(atomic))
++ qYieldCpu();
++ if (modify(atomic))
++ break;
++ }
++ \endcode
++
++ On x86 processors and on RISC-V processors with the \c{Zihintpause}
++ extension, this will emit the \c PAUSE instruction, which is ignored on
++ processors that don't support it; on ARMv7 or later ARM processors, it will
++ emit the \c{YIELD} instruction.
++ */