latch.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup ion_barriers
 *
 * @brief ion::Latch
 *
 * @copyright
 *   SPDX-FileCopyrightText: 2022-2024 European Southern Observatory (ESO)
 
 *   SPDX-License-Identifier: LGPL-3.0-only
 */
#ifndef ION_LATCH_HPP
#define ION_LATCH_HPP
#include <atomic>
#include <cassert>
#include <cstddef>
#include <limits>
 
#include <ion/detail/macros.hpp>
 
namespace ion {
 
/**
 * Single use thread-coordination mechanism modelled after `std::latch`.
 *
 * Modelled after C++20 std::latch but does not perform system calls or yields and as such is more
 * suitable in a real-time environment. Notable differences:
 * - Methods are noexcept
 *
 * Latch has two states:
 * 1. *arrival*, when threads fetch and decrement the expected count
 * 2. *departure*, when all threads have arrived and will depart.
 *
 * After *departure* the only allowed operation is to delete the latch.
 *
 * @memory_order{
 *   @synchronizes_with{All calls to `ArriveAndWait()` or `CountDown()`, any calls to
 *   `ArriveAndWait()` or `Wait()`.
 *   }
 * }
 * @thread_safe
 * @ingroup ion_barriers
 * @headerfile <> <ion/latch.hpp>
 */
class Latch {
public:
    /**
     * Construct latch with expected number of arrivals.
     *
     * @param expected Expected number of arrivals.
     */
    inline constexpr explicit Latch(std::ptrdiff_t expected) noexcept;
 
    /**
     * @name Latch requires stable address and is neither copyable or movable.
     */
    /// @{
    Latch(Latch const&) = delete;
    Latch& operator=(Latch const&) = delete;
    /// @}
 
    /**
     * Decrements expected count by @a n without waiting.
     *
     * @param n the value by which the internal counter is decreased.
     */
    inline void CountDown(std::ptrdiff_t n = 1) noexcept;
 
    /**
     * Equivalent to Wait().
     *
     * @note Method is only provided for *conceptual* compatibility of `std::latch`.
     *
     * @return true
     */
    inline bool TryWait() const noexcept;
 
    /**
     * Block until expected count reaches zero.
     */
    inline void Wait() const noexcept;
 
    /**
     * Decrements expected count by @a n and waits.
     * @pre @a n must be > 0 and <= the expected count.
     * @param n the value by which the internal counter is decreased.
     */
    inline void ArriveAndWait(std::ptrdiff_t n = 1) noexcept;
 
    /**
     * @return Maximum possible value for expected count.
     */
    inline static constexpr std::ptrdiff_t Max() noexcept;
 
private:
    // @returns true iff this call triggered the synchronization condition.
    ION_FORCE_INLINE inline bool Arrive(std::ptrdiff_t n) noexcept;
 
    /**
     * Remaining number of arrivals in current iteration.
     */
    std::atomic<std::ptrdiff_t> m_remaining;
};
 
constexpr Latch::Latch(std::ptrdiff_t expected) noexcept : m_remaining(expected) {
    assert(expected >= 0 && expected <= Max());
}
 
bool Latch::Arrive(std::ptrdiff_t n) noexcept {
    // note: Memory order release to *synchronize with* memory order acquire in Wait()
    return m_remaining.fetch_sub(n, std::memory_order_release) == n;
}
 
void Latch::CountDown(std::ptrdiff_t n) noexcept {
    (void)Arrive(n);
}
 
void Latch::Wait() const noexcept {
    while (true) {
        auto remaining = m_remaining.load(std::memory_order_relaxed);
        if (remaining == 0) {
            // synchronization condition readed -> synchronize with other calls to Wait()
            std::atomic_thread_fence(std::memory_order_acquire);
            return;
        }
        ION_PAUSE();
    }
}
 
bool Latch::TryWait() const noexcept {
    Wait();
    return true;
}
 
constexpr std::ptrdiff_t Latch::Max() noexcept {
    return std::numeric_limits<std::ptrdiff_t>::max();
}
 
void Latch::ArriveAndWait(std::ptrdiff_t n) noexcept {
    if (Arrive(n)) {
        // *this* thread triggered synchronization condition ->
        // *Synchronize with* all other Wait()
        std::atomic_thread_fence(std::memory_order_acquire);
        return;
    }
    Wait();
}
 
}  // namespace ion
#endif  // ION_LATCH_HPP