counter.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup perfc_counter
 * @copyright (c) Copyright ESO 2024
 * All Rights Reserved
 * ESO (eso.org) is an Intergovernmental Organisation, and therefore special legal conditions apply.
 *
 * @brief Performance counter implementation.
 *
 *
 * @defgroup perfc_counter Counters
 * @ingroup perfc
 * @brief Atomic counters types.
 *
 * For an introduction with examples see @ref counters.
 *
 * Three template specializations are provided. All satisfy the basic concept
 * @ref concept_atomic_counter :
 *
 * <table>
 * <tr>
 *   <th>`T` constraints</th>
 *   <th>`Clock` constraints</th>
 *   <th>`Counter::ValueType`</th>
 *   <th>Notes</th>
 *   <th>Link</th>
 * </tr>
 * <tr>
 *   <td>Integral</td>
 *   <td>-</td>
 *   <td>`T`</td>
 *   <td>
 *     - Specialization is lock-free if `std::atomic<T>` is lock-free.
 *     - Specialization can be fully lock-free on most architectures.
 *     - Provides additional member functions like pre/post increment, `FetchAdd`/`FetchSub`.
 *     - No internal timestamp.
 *   </td>
 *   <td>@ref counter_integral "Counter<T>" </td>
 * </tr>
 * <tr>
 *   <td>Non-Integral</td>
 *   <td>-</td>
 *   <td>`T`</td>
 *   <td>
 *     - Specialization is lock-free if `std::atomic<T>` is lock-free.
 *     - No internal timestamp.
 *   </td>
 *   <td>@ref counter_nonintegral "Counter<T>" </td>
 * </tr>
 * <tr>
 *   <td>None</td>
 *   <td>`Clock` satisfy *TrivialClock*</td>
 *   <td>@ref perfc::Timestamped "Timestamped<T, TimePoint>"</td>
 *   <td>
 *     - Default `Clock` is `std::chrono::steady_clock`.
 *     - Keeps internal timestamp.
 *     - Automatically updates timestamp on writes, if time is not provided by caller.
 *   </td>
 *   <td>@ref counter_clock "Counter<T, Clock>" </td>
 * </tr>
 * </table>
 *
 * Commonly used types have pre-defined aliases for double, signed and unsigned 64bit integer, with
 * and without timestamp, see list below.
 *
 * @note As counters are potential synchronization objects they provide no copy or move constructor.
 */
#ifndef PERFC_COUNTER_HPP_
#define PERFC_COUNTER_HPP_
#include <atomic>
#include <chrono>
#include <type_traits>
 
namespace perfc {
 
/**
 * Memory ordering constraints
 * @relatesalso Counter
 * @ingroup perfc_counter
 */
enum class MemoryOrder : std::underlying_type_t<std::memory_order> {
    /**
     * Store operations synchronizes with corresponding Acquire.
     */
    Release = static_cast<std::underlying_type_t<std::memory_order>>(std::memory_order_release),
 
    /**
     * Load operations synchronizes with corresponding Release.
     */
    Acquire = static_cast<std::underlying_type_t<std::memory_order>>(std::memory_order_acquire),
 
    /**
     * No memory ordering constraints (no synchronization).
     *
     * Use @ref CounterRelease() and @ref CounterAcquire() for synchronization.
     */
    Relaxed = static_cast<std::underlying_type_t<std::memory_order>>(std::memory_order_relaxed),
};
 
/**
 * Trivial type describing a counter value and associated timestamp.
 *
 * This type is used as the counter value for counters with internal timestamp.
 *
 * @tparam T Counter value type.
 * @tparam TimePoint Timestamp type.
 * @ingroup perfc_counter
 * @headerfile <> <perfc/counter.hpp>
 * @relatesalso Counter
 */
template <class T, class TimePoint>
struct Timestamped {
    T value;
    TimePoint timestamp;
};
 
template <class T, class Clock = std::chrono::steady_clock, class = void>
class Counter;
 
/**
 * @brief  **Integrals w/o timestamp** Partial specialization for integral types T and without
 * clock.
 * @anchor counter_integral
 * @headerfile <> <perfc/counter.hpp>
 *
 * Represents a thread safe performance counter primitive of type T.
 *
 * @note This is the only Counter specialization that is completely lock-free on most architectures.
 *
 * Satisfies @ref concept_atomic_counter requirements.
 *
 * @thread_safe{All operations are thread safe but not necessarily synchronized}
 *
 * @tparam T counter value type.
 * Type requirements:
 * - `std::is_integral<T>::value == true`
 * @ingroup perfc_counter
 */
template <class T>
class Counter<T, void, typename std::enable_if<std::is_integral<T>::value>::type> {
public:
    using ClockType = void;
    using TimePointType = void;
    using ValueType = T;
    using CounterType = std::atomic<T>;
 
    /**
     * Is true if counter is always lock free.
     */
    static constexpr bool IS_ALWAYS_LOCK_FREE = CounterType::is_always_lock_free;
 
    /**
     * Construct with value-initialized  T (`T()`)
     */
    explicit Counter() noexcept : Counter(T()) {
    }
 
    /**
     * Construct with initial value @a value.
     *
     * @param value Initial value.
     */
    explicit Counter(T value) noexcept : m_value(value) {
    }
    Counter(Counter const&) = delete;
 
    /**
     * Query if operations are lock free.
     * @returns true if operations are lock free.
     * @return false otherwise.
     */
    bool IsLockFree() const noexcept {
        return m_value.is_lock_free();
    }
 
    /**
     * Stores provided @a value in counter.
     *
     * @param value Counter value to store.
     * @param order Memory order constraints.
     */
    void Store(T value, MemoryOrder order = MemoryOrder::Release) noexcept {
        return m_value.store(value, static_cast<std::memory_order>(order));
    }
 
    /**
     * Load value from counter.
     *
     * @param order Memory order constraints.
     * @return Counter value.
     */
    [[nodiscard]] T Load(MemoryOrder order = MemoryOrder::Acquire) const noexcept {
        return m_value.load(static_cast<std::memory_order>(order));
    }
 
    /**
     * Perform post-increment with current value and @a value.
     *
     * @param value value to add.
     * @param order Memory order constraints.
     * @return Counter value immediately preceding the addition of @a value.
     */
    T FetchAdd(T value, MemoryOrder order = MemoryOrder::Release) noexcept {
        return m_value.fetch_add(value, static_cast<std::memory_order>(order));
    }
 
    /**
     * Load value from counter.
     *
     * @param value value to subtract.
     * @param order Memory order constraints.
     * @return Counter value immediately preceding the addition of @a value.
     * @return Counter value.
     */
    T FetchSub(T value, MemoryOrder order = MemoryOrder::Release) noexcept {
        return m_value.fetch_sub(value, static_cast<std::memory_order>(order));
    }
 
    /**
     * Pre-increment operator using default memory order.
     */
    T operator++() noexcept {
        return FetchAdd(1) + 1;
    }
 
    /**
     * Post-increment operator using default memory order.
     *
     * @returns Counter value before incrementation.
     */
    T operator++(int) noexcept {
        return FetchAdd(1);
    }
 
    /**
     * Pre-decrement operator using default memory order.
     */
    T operator--() noexcept {
        return FetchSub(1) - 1;
    }
 
    /**
     * Post-decrement operator using default memory order.
     *
     * @returns Counter value before decrementation.
     */
    T operator--(int) noexcept {
        return FetchSub(1);
    }
 
    /**
     * Performs addition (equivalent to `FetchAdd(value) + value`
     *
     * @param value value to add.
     * @returns Result of arithmetic operation.
     */
    T operator+=(T value) noexcept {
        return FetchAdd(value) + value;
    }
 
    /**
     * Performs subtraction (equivalent to `FetchSub(value) - value`
     *
     * @param value value to subtract.
     * @returns Result of arithmetic operation.
     */
    T operator-=(T value) noexcept {
        return FetchSub(value) - value;
    }
 
private:
    CounterType m_value;
};
 
/**
 * @brief **Non-integrals w/o timestamp** Partial specialization matching void clocks and
 * non-integral T's.
 * @anchor counter_nonintegral
 * @headerfile <> <perfc/counter.hpp>
 *
 * Satisfies @ref concept_atomic_counter requirements.
 *
 * @ingroup perfc_counter
 */
template <class T>
class Counter<T, void, typename std::enable_if<!std::is_integral<T>::value>::type> {
public:
    using ClockType = void;
    using TimePointType = void;
    using ValueType = T;
    using CounterType = std::atomic<ValueType>;
    /**
     * Is true if counter is always lock free.
     */
    static constexpr bool IS_ALWAYS_LOCK_FREE = CounterType::is_always_lock_free;
 
    /**
     * Construct with value-initialized  T (`T()`)
     */
    explicit Counter() noexcept : Counter(T()) {
    }
 
    /**
     * Initialze with provided value.
     *
     * @param value Initial value.
     */
    explicit Counter(T value) noexcept : m_value(value) {
    }
 
    Counter(Counter const&) = delete;
 
    /**
     * Query if operations are lock free.
     * @returns true if operations are lock free.
     * @return false otherwise.
     */
    bool IsLockFree() const noexcept {
        return m_value.is_lock_free();
    }
 
    /**
     * Store value in counter.
     *
     * @param value New counter value to store.
     * @param order Memory order constraints.
     */
    void Store(T value, MemoryOrder order = MemoryOrder::Release) noexcept {
        return m_value.store(value, static_cast<std::memory_order>(order));
    }
 
    /**
     * Load value from counter.
     *
     * @param order Memory order constraints.
     * @returns Counter value.
     */
    [[nodiscard]] ValueType Load(MemoryOrder order = MemoryOrder::Acquire) const noexcept {
        return m_value.load(static_cast<std::memory_order>(order));
    }
 
private:
    CounterType m_value;
};
 
/**
 * @brief **With timestamp** Partial specialization for non-void Clock type.
 * @anchor counter_clock
 * @headerfile <> <perfc/counter.hpp>
 *
 * @thread_safe{All operations are thread safe but not necessarily synchronized}
 *
 * Satisfies @ref concept_atomic_counter requirements.
 *
 * @tparam T counter value type.
 * Type requirements:
 * - *TriviallyCopyable*
 * - *CopyConstructible*
 * - *CopyAssignable*
 * @tparam Clock a clock satisfying @a TrivialClock requirements.
 * @ingroup perfc_counter
 */
template <class T, class Clock>
class Counter<T, Clock, typename std::enable_if<!std::is_void<Clock>::value>::type> {
public:
    using ClockType = Clock;
    using TimePointType = typename ClockType::time_point;
    using ValueType = Timestamped<T, TimePointType>;
    using CounterType = std::atomic<ValueType>;
 
    /**
     * Is true if counter is always lock free.
     */
    static constexpr bool IS_ALWAYS_LOCK_FREE = CounterType::is_always_lock_free;
 
    /**
     * Construct with value-initialized  T (`T()`)
     */
    explicit Counter() noexcept : Counter(T()) {
    }
 
    /**
     * Initialze with a value using current time.
     *
     * @param value Initial value.
     */
    explicit Counter(T value) noexcept : m_value({value, ClockType::now()}) {
    }
 
    /**
     * Initialze with value and time.
     *
     * @param value Initial value and timestamp.
     */
    explicit Counter(ValueType value) noexcept : m_value(value) {
    }
 
    Counter(Counter const&) = delete;
 
    /**
     * Query if operations are lock free.
     * @returns true if operations are lock free.
     * @return false otherwise.
     */
    bool IsLockFree() const noexcept {
        return m_value.is_lock_free();
    }
 
    /**
     * Stores provided @a value and with current time by querying clock.
     *
     * @param value Counter value to store.
     * @param order Memory order constraints.
     */
    void Store(T value, MemoryOrder order = MemoryOrder::Release) noexcept {
        return m_value.store({value, ClockType::now()}, static_cast<std::memory_order>(order));
    }
 
    /**
     * Store value with provided timestamp in counter.
     *
     * @param value Counter value and timestamp to store.
     * @param order Memory order constraints.
     */
    void Store(ValueType value, MemoryOrder order = MemoryOrder::Release) noexcept {
        return m_value.store(value, static_cast<std::memory_order>(order));
    }
 
    /**
     * Load value and timestamp from counter.
     *
     * @param order Memory order constraints.
     * @return Counter value with timestamp.
     */
    [[nodiscard]] ValueType Load(MemoryOrder order = MemoryOrder::Acquire) const noexcept {
        return m_value.load(static_cast<std::memory_order>(order));
    }
 
private:
    CounterType m_value;
};
 
/**
 * @name Synchronization functions
 *
 * Provides capability to synchronize relaxed atomic counter reads and writes.
 */
/// @{
/**
 * @a Synchronizes-with @ref CounterRelease() or Counter store operations using
 * MemoryOrder::Release.
 *
 * CounterRelease() is only necessary ensure that preceding relaxed operations to
 * Counter are synchronized with reads.
 *
 * @ingroup perfc_counter
 */
inline void CounterAcquire() noexcept {
    std::atomic_thread_fence(std::memory_order_acquire);
}
 
/**
 * @a Synchronizes-with @ref CounterAcquire() or counter load operations using
 * MemoryOrder::Acquire.
 *
 * CounterRelease() is only necessary ensure that preceding relaxed operations to
 * Counter are synchronized with reads.
 *
 * @ingroup perfc_counter
 */
inline void CounterRelease() noexcept {
    std::atomic_thread_fence(std::memory_order_release);
}
 
/// @}
 
/** @name Aliases of timestamped counters
 *
 * These aliases are using the clock @c std::steady_clock as a timestamp source.
 * @ingroup perfc_counter
 */
/// @{
/** @ingroup perfc_counter */
using CounterDoubleTs = Counter<double, std::chrono::steady_clock>;
using CounterU64Ts = Counter<std::uint64_t, std::chrono::steady_clock>;
using CounterI64Ts = Counter<std::int64_t, std::chrono::steady_clock>;
/// @}
 
/** @name Aliases of non-timestamped counters
 *
 * These counters aliases have no internal timestamp and are *very* light weight and on most
 * 64bit architectures they are fully lock-free.
 *
 * @ingroup perfc_counter
 */
/// @{
/** @ingroup perfc_counter */
using CounterDouble = Counter<double, void>;
using CounterU64 = Counter<std::uint64_t, void>;
using CounterI64 = Counter<std::int64_t, void>;
/// @}
 
}  // namespace perfc
#endif  // #ifndef PERFC_COUNTER_HPP_