signal.hpp

Go to the documentation of this file.

/**
 * @defgroup ion_signals Signals
 * Thread safe atomic signals.
 *
 * @code
 * #include <cstdint>
 * #include <thread>
 *
 * #include <ion/signal.hpp>
 *
 *
 * int main() {
 *     auto source = ion::SignalSource<int>();
 *
 *     // To avoid race-condition between storing new signal value and what token
 *     // initializes to we create the token in the main thread.
 *     std::thread thread([token=ion::SignalToken<int>(&source)]() mutable {
 *         auto current = Wait(token);
 *         std::cout << "Got signal: " << current << std::endl;
 *     });
 *
 *     // Update signal
 *     source.Store(42);
 *
 *     thread.join();
 * }
 * @endcode
 * @ingroup ion
 *
 * @file
 * @ingroup ion_signals
 *
 * @brief ion::{SignalSource, SignalToken} and algorithms
 *
 * @copyright
 *   SPDX-FileCopyrightText: 2023-2025 European Southern Observatory (ESO)
 
 *   SPDX-License-Identifier: LGPL-3.0-only
 */
#ifndef ION_SIGNAL_HPP
#define ION_SIGNAL_HPP
#include <atomic>
#include <cassert>
#include <cstdint>
#include <optional>
#include <tuple>
#include <type_traits>
 
#include <ion/detail/macros.hpp>
 
namespace ion {
 
/**
 * Atomic signal source.
 *
 * See @ref ion_signals for example.
 *
 * @tparam T Value type of atomic signal. Must be trivial type and
 * `std::atomic<T>::is_always_lock_free == true`.
 * @relates SignalToken
 * @thread_safe
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T>
class SignalSource {
public:
    using ValueType = T;
 
    /**
     * Construct signal source.
     * @param initial Initial value.
     */
    explicit SignalSource(ValueType initial = ValueType{}) noexcept;
 
    /**
     * SignalSource requires stable address so copy and move operations are disabled.
     */
    SignalSource(SignalSource const&) = delete;
    SignalSource& operator=(SignalSource const&) = delete;
 
    /**
     * Load signal value.
     *
     * @returns current value.
     * @memory_order{Relaxed memory order without any synchronization.}
     */
    [[nodiscard]] auto Load() const noexcept -> ValueType;
 
    /**
     * Store signal value.
     *
     * @param value New value to store.
     * @memory_order{Relaxed memory order without any synchronization.}
     */
    void Store(ValueType value) noexcept;
 
    /**
     * Set signal value using read-modify-write semantics.
     *
     * @note Weak version is allowed to spuriously fail which will yield better performance on some
     * platforms.
     *
     * @param [in,out] expected Reference to value expected to be found in the signal. This value is
     * updated if the bitwise comparison failed.
     * @param [in] desired Value to write if expected value comparison succeeds.
     * @returns true if exchange was made.
     * @returns false otherwise.
     * @memory_order{Relaxed memory order without any synchronization.}
     *
     * @sa CompareExchangeTransform()
     */
    [[nodiscard]] auto CompareExchangeWeak(ValueType& expected, ValueType desired) noexcept -> bool;
 
    /**
     * Set signal value using read-modify-write semantics.
     *
     * @param [in,out] expected Reference to value expected to be found in the signal. This value is
     * updated if the bitwise comparison failed.
     * @param [in] desired Desired value to write.
     * @returns true if exchange was made.
     * @returns false otherwise.
     * @memory_order{Relaxed memory order without any synchronization.}
     *
     * @sa CompareExchangeTransform()
     */
    [[nodiscard]] auto
    CompareExchangeStrong(ValueType& expected, ValueType desired) noexcept -> bool;
 
private:
    using SignalType = std::atomic<ValueType>;
    static_assert(SignalType::is_always_lock_free);
 
    SignalType m_signal;
};
 
/**
 * Performs atomic compare-exchange transformation of signal value.
 *
 * @note Provided transform operation `op` will potentially be invoked any number of times - until
 * underlying compare exchange operation is successful.
 *
 * Example where `S::second` is reset to `0` without clobbering `S::first` - even if signal is
 * modified from multiple threads.
 * @code
 * struct S {
 *    std::uint32_t first;
 *    std::uint32_t second;
 * };
 *
 * void ResetSecond(ion::SignalSource<S>& signal) {
 *     CompareExchangeTransform(s, [](S value) noexcept {
 *         // Leave value.first as is.
 *         value.second = 0u;
 *         return value;
 *     });
 * }
 *
 * @endcode
 * @param signal Signal to transform value on.
 * @param op transform operation.
 * @return Transformed value that was successfully stored in signal.
 *
 * @tparam UnaryOperation Noexcept callable invocable as `T callable(T const& t) noexcept`,
 * (which means `T callable(T t) noexcept` is also valid).
 *
 * @ingroup ion_signals
 * @relatesalso SignalSource
 * @headerfile <> <ion/signal.hpp>
 */
template <class T, class UnaryOperation>
auto CompareExchangeTransform(SignalSource<T>& signal, UnaryOperation op) noexcept -> T;
 
/**
 * Signal token that has an associated SignalSource and last known value.
 *
 * A SignalToken is valid (`IsValid() == true`) if it is associated with a SignalSource.
 *
 * Moving a SignalToken will leave the moved-from object invalid.
 *
 * See @ref ion_signals for example.
 * @thread_compatible
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T>
class SignalToken {
public:
    using ValueType = T;
 
    /**
     * @name Initialization.
     */
    /// @{
    /**
     * Default-initialized token.
     *
     * @post `IsValid() == false`
     */
    SignalToken() noexcept = default;
 
    /**
     * Initialize token.
     *
     * @param signal Associated signal.
     * @param last Optional value to set as last known signal value. If `nullopt` is used and
     * `signal` is valid the last value will be initialized from signal source.
     */
    explicit SignalToken(SignalSource<T> const* signal,
                         std::optional<ValueType> last = std::nullopt) noexcept;
    SignalToken(SignalToken const&) noexcept = default;
 
    auto operator=(SignalToken const&) noexcept -> SignalToken& = default;
    /**
     * Move-construct token, leaving `other` in an invalid state.
     *
     * @param other SignalToken to move from.
     * @post `other.IsValid() == false`
     */
    SignalToken(SignalToken&& other) noexcept;
 
    /**
     * Move-assign token, leaving `other` in an invalid state.
     *
     * @param other SignalToken to move from.
     * @post `other.IsValid() == false`
     */
    auto operator=(SignalToken&& other) noexcept -> SignalToken&;
    /// @}
 
    /**
     * @name Observers
     */
    /// @{
    /**
     * @returns true if SignalToken is associated with a SignalSource.
     * @returns false otherwise.
     */
    [[nodiscard]] constexpr auto IsValid() const noexcept -> bool;
 
    /**
     * Loads signal value but *does not* set last value.
     *
     * @pre `IsValid() == true`
     * @sa Update()
     * @memory_order{Loads value from associated signal source using relaxed memory order (no
     * synchronize-with relationships).}
     */
    [[nodiscard]] auto Load() const noexcept -> ValueType;
 
    /**
     * @return Signal source associated with this SignalToken.
     */
    [[nodiscard]] constexpr auto GetSource() const -> SignalSource<ValueType> const*;
 
    /**
     * Get last observed value.
     */
    [[nodiscard]] constexpr auto GetLast() const noexcept -> ValueType;
    /// @}
    /**
     * @name Modifiers
     */
    /// @{
    /**
     * Set last observed value.
     *
     * @param last Value to set as "last" known value from signal.
     */
    constexpr void SetLast(ValueType last) noexcept;
 
    /**
     * Load from signal and set last value.
     *
     * @pre IsValid() == true
     * @return New signal source value.
     * @post `r.Update() == r.GetLast()`
     * @sa Load()
     * @memory_order{Loads value from associated signal source using relaxed memory order (no
     * synchronize-with relationships).}
     */
    auto Update() noexcept -> ValueType;
    /// @}
 
private:
    SignalSource<ValueType> const* m_signal = nullptr;
    ValueType m_last = ValueType();
};
 
/**
 * Equality comparison.
 *
 * @param lhs Left hand side of comparison.
 * @param rhs RIght hand side of comparison.
 * @returns true if both `lhs` and `rhs` are associated with the same signal source and have the
 * same last value.
 * @returns false otherwise.
 * @tparam T ValueType that must provide `bool operator==(T const&, T const&) noexcept`.
 *
 * @ingroup ion_signals
 * @relatesalso SignalToken
 */
template <class T>
[[nodiscard]] constexpr auto
operator==(SignalToken<T> const& lhs, SignalToken<T> const& rhs) noexcept -> bool;
 
/**
 * Inequality comparison.
 *
 * @param lhs Left hand side of comparison.
 * @param rhs RIght hand side of comparison.
 * @returns false if both `lhs` and `rhs` are associated with the same signal source and have the
 * same last value.
 * @returns true otherwise.
 * @tparam T ValueType that must provide `bool operator==(T const&, T const&) noexcept`.
 *
 * @ingroup ion_signals
 * @relatesalso SignalToken
 */
template <class T>
[[nodiscard]] constexpr auto
operator!=(SignalToken<T> const& lhs, SignalToken<T> const& rhs) noexcept -> bool;
 
/**
 * Represents signal source previous (old) and current (new) value.
 * @ingroup ion_signals
 */
template <class T>
struct Status {
    using ValueType = T;
 
    ValueType previous;
    ValueType current;
};
 
/**
 * Represents wait result from one of multiple possible signals.
 *
 * @sa WaitAny()
 * @ingroup ion_signals
 */
template <class T1, class T2>
struct WaitAnyResult {
    /**
     * Index in *result* that unblocked `WaitAny()`
     */
    std::size_t index;
    /**
     * Result of wait operation.
     */
    std::tuple<T1, T2> result;
};
 
/**
 * @name Tag-invoke types
 */
/// @{
/**
 * Select algorithm overload that returns signal status.
 * @ingroup ion_signals
 */
struct StatusTag {
    explicit StatusTag() = default;
};
 
/**
 * Constant instance of StatusTag.
 * @ingroup ion_signals
 */
inline constexpr StatusTag status_tag{};  // NOLINT(readability-identifier-naming)
 
/**
 * Select algorithm overload that returns signal difference.
 * @ingroup ion_signals
 */
struct DifferenceTag {
    explicit DifferenceTag() = default;
};
 
/**
 * Constant instance of DifferenceTag.
 * @ingroup ion_signals
 */
inline constexpr DifferenceTag difference_tag{};  // NOLINT(readability-identifier-naming)
/// @}
 
/**
 * @name Wait and yield current signal value.
 */
/// @{
 
/**
 * Wait until signal source changes and return current value.
 *
 * @code
 * void Example(ion::SignalToken<int>& token) {
 *     assert(token.IsValid());
 *     int current = Wait(token);
 * }
 * @endcode
 *
 * @pre `token.IsValid() == true`
 *
 * @param token Signal token.
 * @returns New signal source value.
 *
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T>
auto Wait(SignalToken<T>& token) noexcept -> T;
 
/**
 * Wait with predicate.
 *
 * Example using a predicate that waits until signal value is even.
 * @code
 * void Example(ion::SignalToken<int>& token) {
 *     assert(token.IsValid());
 *     int current = Wait(token, [](int value) noexcept -> bool {
 *         return value % 2;
 *     });
 * }
 * @endcode
 *
 * @pre `token.IsValid() == true`
 *
 * @param token Signal token.
 * @param stop_waiting Predicate invoked with each new signal value and should return true when to
 * stop waiting.
 * @returns New signal source value.
 *
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T, class Predicate>
auto Wait(SignalToken<T>& token, Predicate&& stop_waiting) noexcept -> T;
/// @}
 
/**
 * @name Wait and yield Status<T>.
 */
/// @{
 
/**
 * Wait until signal source changes and return current and previous values.
 *
 * @code
 * void Example(ion::SignalToken<int>& token) {
 *     assert(token.IsValid());
 *     ion::Status<int> status = Wait(ion::status_tag, token);
 *     // or
 *     auto [previous, current] = Wait(ion::status_tag, token);
 * }
 * @endcode
 *
 * @pre `token.IsValid() == true`
 *
 * @param token Signal token.
 * @returns Status containing current and previous values.
 *
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T>
auto Wait(StatusTag, SignalToken<T>& token) noexcept -> Status<T>;
 
/**
 * Wait with predicate
 *
 * @pre `token.IsValid() == true`
 *
 * @param token Signal token.
 * @returns Status containing current and previous values.
 * @param stop_waiting Predicate invoked with each new signal value and should return true when to
 * stop waiting.
 * @tparam Predicate Callable invokable with signature `bool(T)`.
 * @see Wait(StatusTag,SignalToken<T>&)
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T, class Predicate>
auto Wait(StatusTag, SignalToken<T>& token, Predicate&& stop_waiting) noexcept -> Status<T>;
/// @}
 
/**
 * @name Wait and yield changes since last.
 */
/// @{
/**
 * Wait until signal source changes and return difference (current - previous) value.
 *
 * @note Requires that `T t2=t1-t0` is a valid expression where `t0..t2` denotes an identifier
 * of type `T`.
 *
 * @code
 * void Example(ion::SignalToken<int>& token) {
 *     assert(token.IsValid());
 *     int difference = Wait(ion::difference_tag, token);
 * }
 * @endcode
 *
 * @pre `token.IsValid() == true`
 *
 * @param token Signal token.
 * @returns Difference between current and previous signal value (current - previous).
 *
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T>
auto Wait(DifferenceTag, SignalToken<T>& token) noexcept -> T;
 
/**
 * Wait until signal source changes and return difference (current - previous) value.
 *
 * @note Requires that `T t2=t1-t0` is a valid expression where `t0..t2` denotes an identifier
 * of type `T`.
 *
 * @code
 * void Example(ion::SignalToken<int>& token) {
 *     assert(token.IsValid());
 *     int difference = Wait(ion::difference_tag, token);
 * }
 * @endcode
 *
 * @pre `token.IsValid() == true`
 *
 * @param token Signal token.
 * @param stop_waiting Predicate invoked with each new signal value and should return true when to
 * stop waiting.
 * @returns Difference between current and previous signal value (current - previous).
 *
 * @tparam Predicate Callable invokable with signature `bool(T)`.
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T, class Predicate>
auto Wait(DifferenceTag, SignalToken<T>& token, Predicate&& stop_waiting) noexcept -> T;
/// @}
 
/**
 * @name Wait for either of two signals.
 *
 * *Effects* Load and compare each of the signals with previous value. The first one to change will
 * be recorded in the `WaitAnyResult::index`. Depending on the selected overload the result of
 * `WaitAnyResult::result` is either the *current*, *difference* or the *Status* containing both
 * previous and current value.
 */
/// @{
/**
 * Wait for either of two signals to change.
 *
 * @pre `token1.IsValid() && token2.IsValid()`
 *
 * @param token1 First signal token.
 * @param token2 Second signal token.
 * @returns Wait result in which member `index` specify which of the two signals has a new value.
 * Member `result` contains the current value of the signals.
 *
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T1, class T2>
auto WaitAny(SignalToken<T1>& token1, SignalToken<T2>& token2) noexcept -> WaitAnyResult<T1, T2>;
 
/**
 * Wait for either of two signals to change.
 *
 * @pre `token1.IsValid() && token2.IsValid()`
 *
 * @param token1 First signal token.
 * @param token2 Second signal token.
 * @returns Wait result in which member `index` specify which of the two signals has a new value.
 * Member `result` contains the current and previous value of the signals.
 *
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T1, class T2>
auto WaitAny(StatusTag, SignalToken<T1>& token1, SignalToken<T2>& token2) noexcept
    -> WaitAnyResult<Status<T1>, Status<T2>>;
 
/**
 * Wait for either of two signals to change.
 *
 * @pre `token1.IsValid() && token2.IsValid()`
 *
 * @param token1 First signal token.
 * @param token2 Second signal token.
 * @returns Wait result in which member `index` specify which of the two signals has a new value.
 * Member `result` contains the difference as "current value" - "previous value" of the signals.
 *
 * @relatesalso SignalToken
 * @ingroup ion_signals
 * @headerfile <> <ion/signal.hpp>
 */
template <class T1, class T2>
auto WaitAny(DifferenceTag, SignalToken<T1>& token1, SignalToken<T2>& token2) noexcept
    -> WaitAnyResult<T1, T2>;
/// @}
 
#if !defined(DOXYGEN)
template <class T>
SignalSource<T>::SignalSource(ValueType initial) noexcept : m_signal(initial) {
}
 
template <class T>
auto SignalSource<T>::Load() const noexcept -> ValueType {
    return m_signal.load(std::memory_order_relaxed);
}
 
template <class T>
void SignalSource<T>::Store(ValueType value) noexcept {
    m_signal.store(value, std::memory_order_relaxed);
}
 
template <class T>
auto SignalSource<T>::CompareExchangeWeak(ValueType& expected, ValueType desired) noexcept -> bool {
    return m_signal.compare_exchange_weak(expected, desired, std::memory_order_relaxed);
}
 
template <class T>
auto SignalSource<T>::CompareExchangeStrong(ValueType& expected, ValueType desired) noexcept
    -> bool {
    return m_signal.compare_exchange_strong(expected, desired, std::memory_order_relaxed);
}
 
template <class T, class UnaryOperation>
[[maybe_unused]] auto
CompareExchangeTransform(SignalSource<T>& signal, UnaryOperation op) noexcept -> T {
    static_assert(
        std::is_nothrow_invocable_r<T, UnaryOperation, T>::value,
        "UnaryOperation must be noexcept invocable with signature `T op(T const&) noexcept`");
    auto expected = signal.Load();
    T desired = expected;
    while (!signal.CompareExchangeWeak(expected, (desired = op(expected)))) {
        ION_PAUSE();
    }
    return desired;
}
 
template <class T>
SignalToken<T>::SignalToken(SignalToken&& other) noexcept
    : m_signal(other.m_signal), m_last(other.m_last) {
    other.m_signal = nullptr;
}
template <class T>
SignalToken<T>::SignalToken(SignalSource<T> const* signal, std::optional<ValueType> last) noexcept
    : m_signal(signal), m_last(last.value_or(ValueType{})) {
    if (!last.has_value() && m_signal) {
        m_last = m_signal->Load();
    }
}
 
template <class T>
constexpr auto SignalToken<T>::IsValid() const noexcept -> bool {
    return m_signal != nullptr;
}
 
template <class T>
auto SignalToken<T>::Load() const noexcept -> ValueType {
    assert(IsValid());
    return m_signal->Load();
}
 
template <class T>
constexpr auto SignalToken<T>::GetSource() const -> SignalSource<ValueType> const* {
    return m_signal;
}
 
template <class T>
constexpr auto SignalToken<T>::GetLast() const noexcept -> ValueType {
    return m_last;
}
 
template <class T>
constexpr void SignalToken<T>::SetLast(ValueType last) noexcept {
    m_last = last;
}
 
template <class T>
auto SignalToken<T>::Update() noexcept -> ValueType {
    m_last = Load();
    return m_last;
}
 
template <class T>
auto SignalToken<T>::operator=(SignalToken&& other) noexcept -> SignalToken& {
    m_signal = other.m_signal;
    m_last = other.m_last;
    other.m_signal = nullptr;
    return *this;
}
 
template <class T>
constexpr bool operator==(SignalToken<T> const& lhs, SignalToken<T> const& rhs) noexcept {
    return lhs.GetSource() == rhs.GetSource() && lhs.GetLast() == rhs.GetLast();
}
 
template <class T>
constexpr bool operator!=(SignalToken<T> const& lhs, SignalToken<T> const& rhs) noexcept {
    return !(lhs == rhs);
}
 
template <class T>
auto Wait(SignalToken<T>& token) noexcept -> T {
    return Wait(StatusTag{}, token).current;
}
 
template <class T, class Predicate>
auto Wait(SignalToken<T>& token, Predicate&& stop_waiting) noexcept -> T {
    return Wait(StatusTag{}, token, std::forward<Predicate>(stop_waiting)).current;
}
 
template <class T>
auto Wait(StatusTag, SignalToken<T>& token) noexcept -> Status<T> {
    auto previous = token.GetLast();
    auto current = token.Load();
    for (; current == previous; current = token.Load()) {
        ION_PAUSE();
    }
 
    token.SetLast(current);
    return {previous, current};
}
 
template <class T, class Predicate>
auto Wait(StatusTag, SignalToken<T>& token, Predicate&& stop_waiting) noexcept -> Status<T> {
    static_assert(std::is_invocable_r<bool, Predicate, T>::value,
                  "Predicate must be invocable with signature `bool(T current_value)`");
    auto previous = token.GetLast();
    auto current = token.Load();
    while (!stop_waiting(current)) {
        current = Wait(token);
    };
    // If wait condition is already satisfied Wait() is never called in the body of the loop and
    // "current" value is never updated, hence we store it here again.
    token.SetLast(current);
    return {previous, current};
}
 
template <class T>
auto Wait(DifferenceTag, SignalToken<T>& token) noexcept -> T {
    static_assert(std::is_same_v<T, decltype(T() - T())>);
    auto [previous, current] = Wait(StatusTag{}, token);
    return current - previous;
}
 
template <class T, class Predicate>
auto Wait(DifferenceTag, SignalToken<T>& token, Predicate&& stop_waiting) noexcept -> T {
    static_assert(std::is_same_v<T, decltype(T() - T())>);
    auto [previous, current] = Wait(StatusTag{}, token, std::forward<Predicate>(stop_waiting));
    return current - previous;
}
 
template <class T1, class T2>
auto WaitAny(StatusTag, SignalToken<T1>& token1, SignalToken<T2>& token2) noexcept
    -> WaitAnyResult<Status<T1>, Status<T2>> {
    std::size_t index;
 
    Status<T1> first = {token1.GetLast(), token1.Load()};
    Status<T2> second = {token2.GetLast(), token2.Load()};
 
    while (true) {
        if (first.current != first.previous) {
            index = 0u;
            break;
        }
        if (second.current != second.previous) {
            index = 1u;
            break;
        }
 
        ION_PAUSE();
        first.current = token1.Load();
        second.current = token2.Load();
    }
 
    token1.SetLast(first.current);
    token2.SetLast(second.current);
    return {index, {first, second}};
}
 
template <class T1, class T2>
auto WaitAny(DifferenceTag, SignalToken<T1>& token1, SignalToken<T2>& token2) noexcept
    -> WaitAnyResult<T1, T2> {
    auto r = WaitAny(StatusTag{}, token1, token2);
    return {r.index,
            {std::get<0>(r.result).current - std::get<0>(r.result).previous,
             std::get<1>(r.result).current - std::get<1>(r.result).previous}};
}
 
template <class T1, class T2>
auto WaitAny(SignalToken<T1>& token1, SignalToken<T2>& token2) noexcept -> WaitAnyResult<T1, T2> {
    auto r = WaitAny(StatusTag{}, token1, token2);
 
    return {r.index, {std::get<0>(r.result).current, std::get<1>(r.result).current}};
}
 
#endif  // if !defined(DOXYGEN)
}  // namespace ion
#endif  // ION_SIGNAL_HPP