Sliding window counter for throughput measurement. More...

#include <sliding_window_counter.h>

Collaboration diagram for kcenon::thread::metrics::SlidingWindowCounter:

Classes
struct	Bucket
	Time bucket structure. More...

Public Member Functions
	SlidingWindowCounter (std::chrono::seconds window_size, std::size_t buckets_per_second=DEFAULT_BUCKETS_PER_SECOND)
	Constructs a sliding window counter.

	SlidingWindowCounter (const SlidingWindowCounter &other)
	Copy constructor.

	SlidingWindowCounter (SlidingWindowCounter &&other) noexcept
	Move constructor.

SlidingWindowCounter &	operator= (const SlidingWindowCounter &other)
	Copy assignment operator.

SlidingWindowCounter &	operator= (SlidingWindowCounter &&other) noexcept
	Move assignment operator.

	~SlidingWindowCounter ()=default
	Destructor.

void	increment (std::size_t count=1)
	Increment the counter.

double	rate_per_second () const
	Get the current rate per second.

std::uint64_t	total_in_window () const
	Get the total count within the current window.

std::uint64_t	all_time_total () const
	Get the all-time total count.

void	reset ()
	Reset the counter.

std::chrono::seconds	window_size () const
	Get the window size.

std::size_t	bucket_count () const
	Get the number of buckets.

Static Public Attributes
static constexpr std::size_t	DEFAULT_BUCKETS_PER_SECOND = 10
	Default number of buckets per second.

Private Member Functions
std::size_t	current_bucket_index () const
	Get the current bucket index based on current time.

std::size_t	bucket_index_for_time (std::uint64_t timestamp_ms) const
	Get the bucket index for a specific timestamp.

bool	is_bucket_valid (std::uint64_t bucket_timestamp_ms, std::uint64_t current_ms) const
	Check if a bucket is within the current window.

void	advance_bucket (std::size_t bucket_index, std::uint64_t current_ms)
	Advance bucket to current time period if needed.

Static Private Member Functions
static std::uint64_t	current_time_ms ()
	Get current time in milliseconds since epoch.

Private Attributes
std::chrono::seconds	window_size_
	The sliding window duration.

std::chrono::milliseconds	bucket_duration_
	Duration of each bucket.

std::vector< Bucket >	buckets_
	Circular buffer of time buckets.

std::atomic< std::uint64_t >	all_time_total_ {0}
	All-time total count.

Detailed Description

Sliding window counter for throughput measurement.

This class provides a lock-free, thread-safe counter that tracks events within a sliding time window. It uses a circular buffer of time buckets to maintain accurate rate calculations.

Design Principles

Lock-free: All operations use atomic instructions
Low overhead: O(1) increment, O(bucket_count) for rate calculation
Configurable: Window size and bucket granularity are configurable
Accurate: Sub-second precision with configurable bucket size

Implementation Details

The window is divided into multiple buckets (default: 10 per second). Each bucket covers a fixed time interval. As time advances, old buckets are automatically invalidated and reused for new time periods.

Example for a 1-second window with 10 buckets:

Time: [0ms - 100ms] [100ms - 200ms] ... [900ms - 1000ms]

Buckets: bucket[0] bucket[1] ... bucket[9]

Thread Safety:: Thread-safe for concurrent increment and rate queries.

See also: EnhancedThreadPoolMetrics

Definition at line 51 of file sliding_window_counter.h.

Constructor & Destructor Documentation

◆ SlidingWindowCounter() [1/3]

kcenon::thread::metrics::SlidingWindowCounter::SlidingWindowCounter	(	std::chrono::seconds	window_size,
		std::size_t	buckets_per_second = DEFAULT_BUCKETS_PER_SECOND )

explicit

Constructs a sliding window counter.

Parameters

window_size	The duration of the sliding window.
buckets_per_second	Number of buckets per second (default: 10).

Higher buckets_per_second provides more precision but uses more memory. For a 60-second window with 10 buckets/second, uses 600 * 16 bytes = ~10KB.

Definition at line 11 of file sliding_window_counter.cpp.

    : window_size_(window_size),
      bucket_duration_(std::chrono::milliseconds{1000 / buckets_per_second}),
      buckets_(static_cast<std::size_t>(window_size.count()) * buckets_per_second) {
    // Initialize all buckets
    for (auto& bucket : buckets_) {
        bucket.count.store(0, std::memory_order_relaxed);
        bucket.timestamp_ms.store(0, std::memory_order_relaxed);
    }
}

References buckets_.

◆ SlidingWindowCounter() [2/3]

kcenon::thread::metrics::SlidingWindowCounter::SlidingWindowCounter ( const SlidingWindowCounter & other )

Copy constructor.

Parameters

other The counter to copy from.

Definition at line 24 of file sliding_window_counter.cpp.

    : window_size_(other.window_size_),
      bucket_duration_(other.bucket_duration_),
      buckets_(other.buckets_.size()) {
    for (std::size_t i = 0; i < buckets_.size(); ++i) {
        buckets_[i].count.store(
            other.buckets_[i].count.load(std::memory_order_relaxed),
            std::memory_order_relaxed);
        buckets_[i].timestamp_ms.store(
            other.buckets_[i].timestamp_ms.load(std::memory_order_relaxed),
            std::memory_order_relaxed);
    }
    all_time_total_.store(
        other.all_time_total_.load(std::memory_order_relaxed),
        std::memory_order_relaxed);
}

References all_time_total_, and buckets_.

◆ SlidingWindowCounter() [3/3]

kcenon::thread::metrics::SlidingWindowCounter::SlidingWindowCounter ( SlidingWindowCounter && other )

noexcept

Move constructor.

Parameters

other The counter to move from.

Definition at line 41 of file sliding_window_counter.cpp.

    : window_size_(other.window_size_),
      bucket_duration_(other.bucket_duration_),
      buckets_(std::move(other.buckets_)) {
    all_time_total_.store(
        other.all_time_total_.exchange(0, std::memory_order_relaxed),
        std::memory_order_relaxed);
}

◆ ~SlidingWindowCounter()

kcenon::thread::metrics::SlidingWindowCounter::~SlidingWindowCounter ( )

default

Destructor.

Member Function Documentation

◆ advance_bucket()

void kcenon::thread::metrics::SlidingWindowCounter::advance_bucket	(	std::size_t	bucket_index,
		std::uint64_t	current_ms )

private

Advance bucket to current time period if needed.

Parameters

bucket_index	The bucket to advance.
current_ms	The current timestamp.

Definition at line 174 of file sliding_window_counter.cpp.

                            {
    auto& bucket = buckets_[bucket_index];
    const auto bucket_duration_ms =
        static_cast<std::uint64_t>(bucket_duration_.count());
 
    // Calculate the expected timestamp for this bucket at current time
    const auto expected_timestamp =
        (current_ms / bucket_duration_ms) * bucket_duration_ms;
 
    auto old_timestamp = bucket.timestamp_ms.load(std::memory_order_relaxed);
 
    // Check if bucket needs to be advanced (stale bucket from previous window)
    if (old_timestamp < expected_timestamp) {
        // Try to update the timestamp atomically
        if (bucket.timestamp_ms.compare_exchange_strong(
                old_timestamp, expected_timestamp,
                std::memory_order_relaxed, std::memory_order_relaxed)) {
            // We successfully claimed this bucket for the new time period
            // Reset the count (old data is now invalid)
            bucket.count.store(0, std::memory_order_relaxed);
        }
        // If CAS failed, another thread already advanced it - that's fine
    }
}

References bucket_duration_, and buckets_.

Referenced by increment().

Here is the caller graph for this function:

◆ all_time_total()

std::uint64_t kcenon::thread::metrics::SlidingWindowCounter::all_time_total ( ) const

nodiscard

Get the all-time total count.

Returns: The cumulative count since creation or last reset.

Definition at line 123 of file sliding_window_counter.cpp.

                                                       {
    return all_time_total_.load(std::memory_order_relaxed);
}

References all_time_total_.

◆ bucket_count()

std::size_t kcenon::thread::metrics::SlidingWindowCounter::bucket_count ( ) const

nodiscard

Get the number of buckets.

Returns: The total number of time buckets.

Definition at line 139 of file sliding_window_counter.cpp.

                                                   {
    return buckets_.size();
}

References buckets_.

◆ bucket_index_for_time()

std::size_t kcenon::thread::metrics::SlidingWindowCounter::bucket_index_for_time ( std::uint64_t timestamp_ms ) const

nodiscardprivate

Get the bucket index for a specific timestamp.

Parameters

timestamp_ms Timestamp in milliseconds since epoch.

Returns: The bucket index.

Definition at line 147 of file sliding_window_counter.cpp.

                                    {
    const auto bucket_duration_ms =
        static_cast<std::uint64_t>(bucket_duration_.count());
    return static_cast<std::size_t>(
        (timestamp_ms / bucket_duration_ms) % buckets_.size());
}

References bucket_duration_, and buckets_.

Referenced by current_bucket_index(), and increment().

Here is the caller graph for this function:

◆ current_bucket_index()

std::size_t kcenon::thread::metrics::SlidingWindowCounter::current_bucket_index ( ) const

nodiscardprivate

Get the current bucket index based on current time.

Returns: The index into the circular buffer.

Definition at line 143 of file sliding_window_counter.cpp.

                                                           {
    return bucket_index_for_time(current_time_ms());
}

References bucket_index_for_time(), and current_time_ms().

Here is the call graph for this function:

◆ current_time_ms()

std::uint64_t kcenon::thread::metrics::SlidingWindowCounter::current_time_ms ( )

staticnodiscardprivate

Get current time in milliseconds since epoch.

Returns: Current timestamp in milliseconds.

Definition at line 155 of file sliding_window_counter.cpp.

                                                  {
    return static_cast<std::uint64_t>(
        std::chrono::duration_cast<std::chrono::milliseconds>(
            std::chrono::steady_clock::now().time_since_epoch())
            .count());
}

Referenced by current_bucket_index(), increment(), and total_in_window().

Here is the caller graph for this function:

◆ increment()

void kcenon::thread::metrics::SlidingWindowCounter::increment ( std::size_t count = 1 )

Increment the counter.

Parameters

count The value to add (default: 1).

This operation is lock-free and thread-safe. Complexity: O(1).

Definition at line 89 of file sliding_window_counter.cpp.

                                                    {
    const auto current_ms = current_time_ms();
    const auto bucket_index = bucket_index_for_time(current_ms);
 
    // Advance bucket if it's stale
    advance_bucket(bucket_index, current_ms);
 
    // Increment the bucket and all-time total
    buckets_[bucket_index].count.fetch_add(
        static_cast<std::uint64_t>(count), std::memory_order_relaxed);
    all_time_total_.fetch_add(
        static_cast<std::uint64_t>(count), std::memory_order_relaxed);
}

References advance_bucket(), all_time_total_, bucket_index_for_time(), buckets_, and current_time_ms().

Referenced by kcenon::thread::metrics::EnhancedThreadPoolMetrics::record_execution().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_bucket_valid()

bool kcenon::thread::metrics::SlidingWindowCounter::is_bucket_valid	(	std::uint64_t	bucket_timestamp_ms,
		std::uint64_t	current_ms ) const

nodiscardprivate

Check if a bucket is within the current window.

Parameters

bucket_timestamp_ms	The bucket's timestamp.
current_ms	The current timestamp.

Returns: True if the bucket is valid (within window).

Definition at line 162 of file sliding_window_counter.cpp.

                                  {
    if (bucket_timestamp_ms == 0) {
        return false;
    }
 
    const auto window_ms =
        static_cast<std::uint64_t>(window_size_.count()) * 1000;
    return (current_ms - bucket_timestamp_ms) < window_ms;
}

References window_size_.

Referenced by total_in_window().

Here is the caller graph for this function:

◆ operator=() [1/2]

SlidingWindowCounter & kcenon::thread::metrics::SlidingWindowCounter::operator= ( const SlidingWindowCounter & other )

Copy assignment operator.

Parameters

other The counter to copy from.

Returns: Reference to this counter.

Definition at line 50 of file sliding_window_counter.cpp.

                                       {
    if (this != &other) {
        window_size_ = other.window_size_;
        bucket_duration_ = other.bucket_duration_;
 
        // Resize if needed
        if (buckets_.size() != other.buckets_.size()) {
            buckets_.resize(other.buckets_.size());
        }
 
        for (std::size_t i = 0; i < buckets_.size(); ++i) {
            buckets_[i].count.store(
                other.buckets_[i].count.load(std::memory_order_relaxed),
                std::memory_order_relaxed);
            buckets_[i].timestamp_ms.store(
                other.buckets_[i].timestamp_ms.load(std::memory_order_relaxed),
                std::memory_order_relaxed);
        }
        all_time_total_.store(
            other.all_time_total_.load(std::memory_order_relaxed),
            std::memory_order_relaxed);
    }
    return *this;
}

References all_time_total_, bucket_duration_, buckets_, and window_size_.

◆ operator=() [2/2]

SlidingWindowCounter & kcenon::thread::metrics::SlidingWindowCounter::operator= ( SlidingWindowCounter && other )

noexcept

Move assignment operator.

Parameters

other The counter to move from.

Returns: Reference to this counter.

Definition at line 76 of file sliding_window_counter.cpp.

                                           {
    if (this != &other) {
        window_size_ = other.window_size_;
        bucket_duration_ = other.bucket_duration_;
        buckets_ = std::move(other.buckets_);
        all_time_total_.store(
            other.all_time_total_.exchange(0, std::memory_order_relaxed),
            std::memory_order_relaxed);
    }
    return *this;
}

◆ rate_per_second()

double kcenon::thread::metrics::SlidingWindowCounter::rate_per_second ( ) const

nodiscard

Get the current rate per second.

Returns: The average rate over the sliding window.

This calculates the total count in the window divided by window duration.

Definition at line 103 of file sliding_window_counter.cpp.

                                                   {
    const auto total = total_in_window();
    const auto window_seconds = static_cast<double>(window_size_.count());
    return static_cast<double>(total) / window_seconds;
}

References total_in_window(), and window_size_.

Referenced by kcenon::thread::metrics::EnhancedThreadPoolMetrics::snapshot().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reset()

void kcenon::thread::metrics::SlidingWindowCounter::reset ( )

Reset the counter.

Clears all buckets and resets the all-time total.

Definition at line 127 of file sliding_window_counter.cpp.

                                 {
    for (auto& bucket : buckets_) {
        bucket.count.store(0, std::memory_order_relaxed);
        bucket.timestamp_ms.store(0, std::memory_order_relaxed);
    }
    all_time_total_.store(0, std::memory_order_relaxed);
}

References all_time_total_, and buckets_.

Referenced by kcenon::thread::metrics::EnhancedThreadPoolMetrics::reset().

Here is the caller graph for this function:

◆ total_in_window()

std::uint64_t kcenon::thread::metrics::SlidingWindowCounter::total_in_window ( ) const

nodiscard

Get the total count within the current window.

Returns: The sum of all counts in valid buckets.

Definition at line 109 of file sliding_window_counter.cpp.

                                                        {
    const auto current_ms = current_time_ms();
    std::uint64_t total = 0;
 
    for (const auto& bucket : buckets_) {
        const auto timestamp = bucket.timestamp_ms.load(std::memory_order_relaxed);
        if (is_bucket_valid(timestamp, current_ms)) {
            total += bucket.count.load(std::memory_order_relaxed);
        }
    }
 
    return total;
}

References buckets_, current_time_ms(), and is_bucket_valid().

Referenced by rate_per_second().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ window_size()

std::chrono::seconds kcenon::thread::metrics::SlidingWindowCounter::window_size ( ) const

nodiscard

Get the window size.

Returns: The configured sliding window duration.

Definition at line 135 of file sliding_window_counter.cpp.

                                                         {
    return window_size_;
}

References window_size_.

Member Data Documentation

◆ all_time_total_

std::atomic<std::uint64_t> kcenon::thread::metrics::SlidingWindowCounter::all_time_total_ {0}

private

All-time total count.

Definition at line 209 of file sliding_window_counter.h.

209{0};

Referenced by all_time_total(), increment(), operator=(), reset(), and SlidingWindowCounter().

◆ bucket_duration_

std::chrono::milliseconds kcenon::thread::metrics::SlidingWindowCounter::bucket_duration_

private

Duration of each bucket.

Definition at line 199 of file sliding_window_counter.h.

Referenced by advance_bucket(), bucket_index_for_time(), and operator=().

◆ buckets_

std::vector<Bucket> kcenon::thread::metrics::SlidingWindowCounter::buckets_

private

Circular buffer of time buckets.

Definition at line 204 of file sliding_window_counter.h.

Referenced by advance_bucket(), bucket_count(), bucket_index_for_time(), increment(), operator=(), reset(), SlidingWindowCounter(), SlidingWindowCounter(), and total_in_window().

◆ DEFAULT_BUCKETS_PER_SECOND

std::size_t kcenon::thread::metrics::SlidingWindowCounter::DEFAULT_BUCKETS_PER_SECOND = 10

staticconstexpr

Default number of buckets per second.

Definition at line 56 of file sliding_window_counter.h.

◆ window_size_

std::chrono::seconds kcenon::thread::metrics::SlidingWindowCounter::window_size_

private

The sliding window duration.

Definition at line 194 of file sliding_window_counter.h.

Referenced by is_bucket_valid(), operator=(), rate_per_second(), and window_size().

The documentation for this class was generated from the following files:

include/kcenon/thread/metrics/sliding_window_counter.h
src/metrics/sliding_window_counter.cpp

Classes

Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Design Principles

Implementation Details

Constructor & Destructor Documentation

◆ SlidingWindowCounter() [1/3]

◆ SlidingWindowCounter() [2/3]

◆ SlidingWindowCounter() [3/3]

◆ ~SlidingWindowCounter()

Member Function Documentation

◆ advance_bucket()

◆ all_time_total()

◆ bucket_count()

◆ bucket_index_for_time()

◆ current_bucket_index()

◆ current_time_ms()

◆ increment()

◆ is_bucket_valid()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ rate_per_second()

◆ reset()

◆ total_in_window()

◆ window_size()

Member Data Documentation

◆ all_time_total_

◆ bucket_duration_

◆ buckets_

◆ DEFAULT_BUCKETS_PER_SECOND

◆ window_size_