striped_counter.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/concurrent/striped_counter.hpp
/// @brief @copybrief concurrent::StripedCounter
 
#include <cstdint>
 
#include <userver/utils/fast_pimpl.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace concurrent {
 
/// @ingroup userver_concurrency
///
/// @brief A contention-free sharded atomic counter, with memory consumption
/// and read performance traded for write performance. Intended to be used for
/// write-heavy counters, mostly in metrics.
///
/// @note Depending on the underlying platform is implemented either via a
/// single atomic variable, or an 'nproc'-sized array of interference-shielded
/// rseq-based (https://www.phoronix.com/news/Restartable-Sequences-Speed)
/// per-CPU counters.
/// In the second case, read is approx. `nproc` times slower than write.
class StripedCounter final {
public:
    /// @brief Constructs a zero-initialized counter.
    /// Might allocate up to kDestructiveInterferenceSize (64 bytes for x86_64) *
    /// number of available CPUs bytes.
    StripedCounter();
    ~StripedCounter();
 
    StripedCounter(const StripedCounter&) = delete;
    StripedCounter& operator=(const StripedCounter&) = delete;
 
    StripedCounter(StripedCounter&&) = delete;
    StripedCounter& operator=(StripedCounter&&) = delete;
 
    /// @brief The addition is done with a relaxed memory order.
    void Add(std::uintptr_t value) noexcept;
 
    /// @brief The subtraction is done with a relaxed memory order.
    void Subtract(std::uintptr_t value) noexcept {
        // Perfectly defined unsigned wrapping
        Add(-value);
    }
 
    /// @brief Read the total counter value. The counter uses the full range
    /// of `std::uintptr_t`, using wrap-around when necessary.
    /// @note The read is done with `std::memory_order_acquire`.
    ///
    /// Due to the underlying implementation being an array of counters, this
    /// function may return logically impossible values if `Subtract` is in play.
    /// For example, doing `Add(1)`, then `Subtract(1)` in one thread and `Read` in another thread in parallel
    /// may lead to this function returning -1 (wrapped).
    /// With `Subtract`, consider using `NonNegativeRead` instead.
    std::uintptr_t Read() const noexcept;
 
    /// @brief Read the non-negative total counter value.
    /// @note The read is done with `std::memory_order_acquire`.
    ///
    /// This is almost exactly like `Read`, but for an `Add-Subtract` race,
    /// instead of returning a negative value, this function returns `0`. Consider
    /// this a convenient shortcut to avoid seeing logically impossible negative
    /// values.
    std::uintptr_t NonNegativeRead() const noexcept;
 
private:
    struct Impl;
    utils::FastPimpl<Impl, 32, 8> impl_;
};
 
}  // namespace concurrent
 
USERVER_NAMESPACE_END