qlatch.cpp

Go to the documentation of this file.

// Copyright (C) 2025 Intel Corporation.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
 
#include "qlatch_p.h"
 
#include "qatomicwait_p.h"
#include "qfutex_p.h"
 
QT_BEGIN_NAMESPACE
 
using namespace QtFutex;
 
#if defined(QATOMICWAIT_USE_FALLBACK)
static constexpr bool ForcedFallbackAtomicWait = true;
namespace atomicwait = QtFallbackAtomicWait;
#else
static constexpr bool ForcedFallbackAtomicWait = false;
namespace atomicwait = q20;
#endif
 
/*!
    \class QLatch
    \internal
 
    Implements the same API as \c std::latch (C++20), allowing a single
    synchronization between threads.
 
    \section2 Typical uses
    \section3 Waiting for threaded work to finish
 
    For this use-case, one or more threads perform some work, which needs to
    finish before the caller thread can proceed. For this, each worker thread
    calls countDown() once they have finished their work, while the caller
    thread suspends execution by calling wait().
 
    The operation is best seen in:
    \code
        QLatch latch(segments);
        int y = 0;
        for (int i = 0; i < segments; ++i) {
            int yn = (data->height - y) / (segments - i);
            threadPool->start([&, y, yn]() {
                convertSegment(y, y + yn);
                latch.countDown();
            });
            y += yn;
        }
        latch.wait();
    \endcode
 
    Or, for a single thread:
    \code
        QLatch latch(1);
        QMetaObject::invokeMethod(object, [&]() {
            doSomething();
            latch.countDown();
        }, Qt::QueuedConnection);
        latch.wait();
    \endcode
 
    In fact, the above is exactly what Qt::BlockingQueued connection does.
 
    \section3 Synchronizing execution
 
    For this use-case, multiple threads must reach a particular state before
    any of them may proceed. In this case, all of them call arriveAndWait(),
    causing all but the last one of them to suspend execution until that last
    one also arrives.
 
    \code
        QLatch latch(n);
        for (int i = 0; i < n; ++i) {
            threadPool->start([] {
                latch.arriveAndWait();
                doStressfulWork();
            });
        }
    \endcode
 
    \section2 Differences from \c std::latch
 
    \list
      \li Uses \c{int} in the API instead of \c{ptrdiff_t} (note that the max()
          is the same as libstdc++'s on Linux).
      \li count_down() is not \c{const} (libstdc++ implementation is).
    \endlist
 
    \omit
    \section2 Implementation details
 
    countDown() must call wakeUp() if the latch counter reaches zero and there
    are threads waiting to be woken up. Or, conversely, countDown() needs to do
    nothing after decrementing if the latch counter is still non-zero or there
    are no waiters. Therefore, we choose the bits so that a non-zero
    \c{counter} member implies no action required.
 
    \endomit
*/
 
/*!
    \fn QLatch::QLatch(int expected) noexcept
 
    Initializes the QLatch to indicate that countDown() will be called \a
    expected times. You probably want to pass a value greater than zero.
*/
 
/*!
    \fn int QLatch::pending() noexcept
    \internal
 
    Returns the counter.
 
    Don't use; for the unit test only.
*/
 
/*!
    \fn void QLatch::countDown(int n) noexcept
    \fn void QLatch::count_down(int n) noexcept
 
    Decrements the internal counter by \a n. If the internal counter drops to
    zero after this operation, any threads currently waiting will be woken up.
    If \a n is greater than the value of the internal counter or is negative,
    the behavior is undefined.
 
    This function does not block and may be used to notify waiters that this
    thread has reached a particular point and they may proceed. To synchronize
    all threads so they all resume work at the same time, use arriveAndWait().
 
    This function implements release memory ordering.
 
    \sa arriveAndWait(), wait()
*/
 
/*!
    \fn bool QLatch::tryWait() const noexcept
    \fn void QLatch::try_wait() const noexcept
 
    Returns true if the internal counter in this latch has dropped to zero,
    false otherwise. This function does not block.
 
    This function implements acquire memory ordering.
 
    \sa wait(), countDown()
*/
 
/*!
    \fn void QLatch::wait() noexcept
 
    Waits for the internal counter in this latch to drop to zero.
 
    This function implements acquire memory ordering.
 
    \sa tryWait(), arriveAndWait(), countDown()
*/
 
/*!
    \fn void QLatch::arriveAndWait(int n) noexcept
    \fn void QLatch::arrive_and_wait(int n) noexcept
 
    This function decrements the internal counter by \a n. If the counter
    remains non-zero after this operation, it suspends the current thread until
    it does become zero. Otherwise it wakes all other current waiters.
 
    This function is useful to synchronize multiple threads so they may start
    some execution at (nearly) exactly the same time.
 
    This function is exactly equivalent to:
    \code
       countDown(n);
       wait();
    \endcode
 
    This function implements acquire-and-release memory ordering.
 
    \sa countDown(), wait()
*/
 
/*!
    \fn int QLatch::max() noexcept
 
    Returns the maximum number that can be passed to the constructor.
*/
 
void QLatch::waitInternal(int current) noexcept
{
    // mark that there is a waiter -> clear the bit that there are no waiters
    if (current & NoWaiters) {
#if __has_builtin(__atomic_and_fetch)
        // Modern GCC and Clang are able to generate loop-free code for this
        // operation on x86-64, ARMv8.1 and RISC-V.
        if (__atomic_and_fetch(reinterpret_cast<int *>(&counter._q_value), ~NoWaiters,
                               int(std::memory_order_relaxed)) == 0)
            return;
#else
        // Do it in two steps, which is usually better than a compare_exchange
        // loop. This is not exactly the same as above (it's not atomic!) but
        // is correct for our purposes because the counter never changes from 0
        // once it reaches that.
        counter.fetchAndAndRelaxed(~NoWaiters);
        if (counter.loadRelaxed() == 0)
            return;     // no need to wait!
#endif
    }
    current &= ~NoWaiters;
 
    auto waitLoop = [&](auto waiter) {
        do {
            waiter(current);
        } while ((current = counter.loadAcquire()) != 0);
    };
 
    if (futexAvailable() && !ForcedFallbackAtomicWait)
        waitLoop([&](int current) { futexWait(counter, current); });
    else
        waitLoop([&](int current) {
            atomicwait::atomic_wait_explicit(&counter._q_value, current, std::memory_order_relaxed);
        });
}
 
void QLatch::wakeUp() noexcept
{
    if (futexAvailable() && !ForcedFallbackAtomicWait)
        futexWakeAll(counter);
    else
        atomicwait::atomic_notify_all(&counter._q_value);
}
 
QT_END_NAMESPACE