Circular-buffer moving statistics: query average, sum and per-second throughput over recent time windows. More...

#include <MovingAverage.h>

Collaboration diagram for cmlabs::MovingAverage:

Public Member Functions
	MovingAverage (uint32 binTimeMS=100, uint16 binCount=600)
	Create a tracker.
	~MovingAverage ()
bool	add (double val, uint32 count=1, uint64 time=GetTimeNow())
	Record a sample.
bool	getThroughput (uint32 ms, double &valPerSec, double &countPerSec, uint64 now=GetTimeNow())
	Compute rates over the last `ms` milliseconds.
bool	getThroughputMulti (uint32 ms1, uint32 ms2, uint32 ms3, double &valPerSec1, double &countPerSec1, double &valPerSec2, double &countPerSec2, double &valPerSec3, double &countPerSec3, uint64 now=GetTimeNow())
	Compute throughput for three windows in one locked pass (cheaper than three getThroughput() calls).
bool	getAverage (uint32 ms, double &val, uint64 &count, uint64 now=GetTimeNow())
	Average value over the last `ms` milliseconds.
bool	getAverageMulti (uint32 ms1, uint32 ms2, uint32 ms3, double &avg1, uint64 &count1, double &avg2, uint64 &count2, double &avg3, uint64 &count3, uint64 now=GetTimeNow())
	Averages for three windows in one locked pass; parameters parallel getThroughputMulti().
bool	getSum (uint32 ms, double &val, uint64 &count, uint64 now=GetTimeNow())
	Value sum over the last `ms` milliseconds.
bool	getSumMulti (uint32 ms1, uint32 ms2, uint32 ms3, double &sum1, uint64 &count1, double &sum2, uint64 &count2, double &sum3, uint64 &count3, uint64 now=GetTimeNow())
	Sums for three windows in one locked pass; parameters parallel getThroughputMulti().
bool	getTotal (double &val, uint64 &count)
	Lifetime totals since construction (not limited to the bin window).
std::string	getPerfXML (uint32 binMS=1000, uint32 binNum=60)
	Render recent history as XML performance bins.
std::string	getPerfJSON (uint32 binMS=1000, uint32 binNum=60)
	Render recent history as JSON performance bins.

Static Public Member Functions
static bool	UnitTest ()
	Self test.

Protected Member Functions
bool	shiftBins (uint64 now)
	Advance the circular buffer so the bin containing `now` becomes current, zeroing expired bins.

Protected Attributes
StatEntry *	entries
utils::Mutex	mutex
uint32	binTime
	Bin duration in µs (constructor's binTimeMS multiplied by 1000).
uint32	binCount
uint32	currentBin
uint64	currentBinStart
double	totalValue
uint64	totalCount

Detailed Description

Circular-buffer moving statistics: query average, sum and per-second throughput over recent time windows.

The tracker divides time into binCount consecutive bins of binTimeMS milliseconds each and keeps only the per-bin sums (StatEntry), so memory use is constant regardless of sample rate. When a sample or query arrives, the circular buffer is rotated forward so that the bin containing the reference time becomes current; bins that fell out of the window are zeroed and recycled. Queries aggregate whole bins, so results are quantized to bin granularity: a window of ms milliseconds actually covers ceil(ms/binTimeMS) bins including the (partially filled) current bin. With the defaults (100 ms x 600 bins) you can query any window up to one minute with 100 ms resolution.

Time handling: all timestamps are PsyTime GetTimeNow() values in microseconds. The constructor's binTimeMS is converted to µs internally (stored as binTimeMS*1000), while the query window arguments (ms) remain in milliseconds — do not mix the two up. Samples with timestamps slightly in the past are credited to the correct earlier bin if it is still within the window; samples older than the whole window only count towards the lifetime totals. If the clock jumps forward by more than the full window (e.g. after system sleep), all bins are reset and only getTotal() retains history.

Thread-safe: every public method takes the internal mutex, and the Multi() variants aggregate several windows under a single lock, which is cheaper and yields mutually consistent numbers.

MovingAverage msgRate(100, 600);          // 100 ms bins, 60 s of history
 
// On every message received:
msgRate.add((double)messageBytes);        // count defaults to 1 event
 
// Periodic monitoring:
double bytesPerSec, msgsPerSec;
msgRate.getThroughput(5000, bytesPerSec, msgsPerSec);  // last 5 seconds
 
double avgSize; uint64 n;
msgRate.getAverage(60000, avgSize, n);    // mean message size, last 60 s

Warning: Query windows longer than binTimeMS*binCount cannot be answered from the retained bins; keep ms within the configured history.

Definition at line 66 of file MovingAverage.h.

Constructor & Destructor Documentation

◆ MovingAverage()

cmlabs::MovingAverage::MovingAverage	(	uint32	binTimeMS = 100,
		uint16	binCount = 600 )

Create a tracker.

Parameters

binTimeMS	Duration of each bin in ms.
binCount	Number of bins kept (history = binTimeMS*binCount).

Definition at line 15 of file MovingAverage.cpp.

References binCount, binTime, currentBin, currentBinStart, entries, mutex, totalCount, and totalValue.

Referenced by UnitTest().

◆ ~MovingAverage()

cmlabs::MovingAverage::~MovingAverage ( )

Definition at line 28 of file MovingAverage.cpp.

References entries, and mutex.

Member Function Documentation

◆ add()

bool cmlabs::MovingAverage::add	(	double	val,
		uint32	count = 1,
		uint64	time = GetTimeNow() )

Record a sample.

Parameters

val	Value to add (e.g. bytes, latency).
count	How many events this value represents (added to the bin's count).
time	Sample timestamp in µs (a GetTimeNow() value); defaults to now. Slightly-past timestamps land in the correct earlier bin; timestamps older than the whole window are added to the lifetime totals only.

Returns: true on success.

Note: Passing an explicit time avoids a second clock read when the caller already has a fresh GetTimeNow() value.

Definition at line 65 of file MovingAverage.cpp.

References binCount, binTime, currentBin, currentBinStart, entries, mutex, totalCount, and totalValue.

Referenced by UnitTest().

◆ getAverage()

bool cmlabs::MovingAverage::getAverage	(	uint32	ms,
		double &	val,
		uint64 &	count,
		uint64	now = GetTimeNow() )

Average value over the last ms milliseconds.

Parameters

	ms	Window length in milliseconds.
[out]	val	Average value (unchanged sum when `count` is 0).
[out]	count	Number of events in the window.
	now	Reference time in µs (GetTimeNow() value).

Returns: true on success.

Definition at line 124 of file MovingAverage.cpp.

References getSum().

Referenced by UnitTest().

◆ getAverageMulti()

bool cmlabs::MovingAverage::getAverageMulti	(	uint32	ms1,
		uint32	ms2,
		uint32	ms3,
		double &	avg1,
		uint64 &	count1,
		double &	avg2,
		uint64 &	count2,
		double &	avg3,
		uint64 &	count3,
		uint64	now = GetTimeNow() )

Averages for three windows in one locked pass; parameters parallel getThroughputMulti().

Returns: true on success.

Definition at line 133 of file MovingAverage.cpp.

References getSumMulti().

◆ getPerfJSON()

std::string cmlabs::MovingAverage::getPerfJSON	(	uint32	binMS = 1000,
		uint32	binNum = 60 )

Render recent history as JSON performance bins.

Parameters

binMS	Output bin size in ms.
binNum	Number of output bins.

Returns: JSON text.

Definition at line 354 of file MovingAverage.cpp.

References binCount, binTime, cmlabs::StatEntry::count, currentBin, currentBinStart, entries, cmlabs::GetTimeNow(), mutex, shiftBins(), cmlabs::utils::StringFormat(), and cmlabs::StatEntry::value.

◆ getPerfXML()

std::string cmlabs::MovingAverage::getPerfXML	(	uint32	binMS = 1000,
		uint32	binNum = 60 )

Render recent history as XML performance bins.

Parameters

binMS	Output bin size in ms.
binNum	Number of output bins.

Returns: XML text.

Definition at line 299 of file MovingAverage.cpp.

References binCount, binTime, cmlabs::StatEntry::count, currentBin, currentBinStart, entries, cmlabs::GetTimeNow(), mutex, shiftBins(), cmlabs::utils::StringFormat(), and cmlabs::StatEntry::value.

◆ getSum()

bool cmlabs::MovingAverage::getSum	(	uint32	ms,
		double &	val,
		uint64 &	count,
		uint64	now = GetTimeNow() )

Value sum over the last ms milliseconds.

Parameters

	ms	Window length in milliseconds.
[out]	val	Sum.
[out]	count	Number of events.
	now	Reference time in µs (GetTimeNow() value).

Returns: true on success.

Definition at line 154 of file MovingAverage.cpp.

References binCount, binTime, cmlabs::StatEntry::count, currentBin, currentBinStart, entries, mutex, shiftBins(), and cmlabs::StatEntry::value.

Referenced by getAverage(), getThroughput(), and UnitTest().

◆ getSumMulti()

bool cmlabs::MovingAverage::getSumMulti	(	uint32	ms1,
		uint32	ms2,
		uint32	ms3,
		double &	sum1,
		uint64 &	count1,
		double &	sum2,
		uint64 &	count2,
		double &	sum3,
		uint64 &	count3,
		uint64	now = GetTimeNow() )

Sums for three windows in one locked pass; parameters parallel getThroughputMulti().

Returns: true on success.

Definition at line 192 of file MovingAverage.cpp.

References binCount, binTime, clmax, cmlabs::StatEntry::count, currentBin, currentBinStart, entries, mutex, shiftBins(), and cmlabs::StatEntry::value.

Referenced by getAverageMulti(), and getThroughputMulti().

◆ getThroughput()

bool cmlabs::MovingAverage::getThroughput	(	uint32	ms,
		double &	valPerSec,
		double &	countPerSec,
		uint64	now = GetTimeNow() )

Compute rates over the last ms milliseconds.

Parameters

	ms	Window length in milliseconds (quantized up to whole bins).
[out]	valPerSec	Value sum per second.
[out]	countPerSec	Event count per second.
	now	Reference time in µs (GetTimeNow() value).

Returns: true on success.

Definition at line 257 of file MovingAverage.cpp.

References getSum().

Referenced by UnitTest().

◆ getThroughputMulti()

bool cmlabs::MovingAverage::getThroughputMulti	(	uint32	ms1,
		uint32	ms2,
		uint32	ms3,
		double &	valPerSec1,
		double &	countPerSec1,
		double &	valPerSec2,
		double &	countPerSec2,
		double &	valPerSec3,
		double &	countPerSec3,
		uint64	now = GetTimeNow() )

Compute throughput for three windows in one locked pass (cheaper than three getThroughput() calls).

Parameters

	ms1,ms2,ms3	Window lengths.
[out]	valPerSec1,countPerSec1	Rates for window 1.
[out]	valPerSec2,countPerSec2	Rates for window 2.
[out]	valPerSec3,countPerSec3	Rates for window 3.
	now	Reference time in µs (GetTimeNow() value).

Returns: true on success.

Definition at line 271 of file MovingAverage.cpp.

References getSumMulti().

Referenced by UnitTest().

◆ getTotal()

bool cmlabs::MovingAverage::getTotal	(	double &	val,
		uint64 &	count )

Lifetime totals since construction (not limited to the bin window).

Parameters

[out]	val	Total value sum.
[out]	count	Total event count.

Returns: true on success.

Definition at line 249 of file MovingAverage.cpp.

References mutex, totalCount, and totalValue.

Referenced by UnitTest().

◆ shiftBins()

bool cmlabs::MovingAverage::shiftBins ( uint64 now )

protected

Advance the circular buffer so the bin containing now becomes current, zeroing expired bins.

Caller must hold the mutex. A jump of more than binCount bins clears the entire buffer.

Parameters

now	Time in µs (GetTimeNow() value).

Returns: true on success.

Definition at line 35 of file MovingAverage.cpp.

References binCount, binTime, currentBin, currentBinStart, and entries.

Referenced by getPerfJSON(), getPerfXML(), getSum(), and getSumMulti().

◆ UnitTest()

bool cmlabs::MovingAverage::UnitTest ( )

static

Self test.

Returns: true when all checks pass.

Definition at line 425 of file MovingAverage.cpp.

References add(), cmlabs::utils::BytifyRate(), cmlabs::unittest::detail(), cmlabs::unittest::fail(), getAverage(), getSum(), getThroughput(), getThroughputMulti(), cmlabs::GetTimeAge(), cmlabs::GetTimeNow(), getTotal(), cmlabs::unittest::metric(), MovingAverage(), and cmlabs::unittest::progress().

Referenced by cmlabs::Register_MovingAverage_Tests().

Member Data Documentation

◆ binCount

uint32 cmlabs::MovingAverage::binCount

protected

Definition at line 140 of file MovingAverage.h.

Referenced by add(), getPerfJSON(), getPerfXML(), getSum(), getSumMulti(), MovingAverage(), and shiftBins().

◆ binTime

uint32 cmlabs::MovingAverage::binTime

protected

Bin duration in µs (constructor's binTimeMS multiplied by 1000).

Definition at line 139 of file MovingAverage.h.

Referenced by add(), getPerfJSON(), getPerfXML(), getSum(), getSumMulti(), MovingAverage(), and shiftBins().

◆ currentBin

uint32 cmlabs::MovingAverage::currentBin

protected

Definition at line 141 of file MovingAverage.h.

Referenced by add(), getPerfJSON(), getPerfXML(), getSum(), getSumMulti(), MovingAverage(), and shiftBins().

◆ currentBinStart

uint64 cmlabs::MovingAverage::currentBinStart

protected

Definition at line 142 of file MovingAverage.h.

Referenced by add(), getPerfJSON(), getPerfXML(), getSum(), getSumMulti(), MovingAverage(), and shiftBins().

◆ entries

StatEntry* cmlabs::MovingAverage::entries

protected

Definition at line 136 of file MovingAverage.h.

Referenced by add(), getPerfJSON(), getPerfXML(), getSum(), getSumMulti(), MovingAverage(), shiftBins(), and ~MovingAverage().

◆ mutex

utils::Mutex cmlabs::MovingAverage::mutex

protected

Definition at line 137 of file MovingAverage.h.

Referenced by add(), getPerfJSON(), getPerfXML(), getSum(), getSumMulti(), getTotal(), MovingAverage(), and ~MovingAverage().

◆ totalCount

uint64 cmlabs::MovingAverage::totalCount

protected

Definition at line 144 of file MovingAverage.h.

Referenced by add(), getTotal(), and MovingAverage().

◆ totalValue

double cmlabs::MovingAverage::totalValue

protected

Definition at line 143 of file MovingAverage.h.

Referenced by add(), getTotal(), and MovingAverage().

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

/home/ubuntu/c/partner/psyclone2/CMSDK/include/MovingAverage.h
/home/ubuntu/c/partner/psyclone2/CMSDK/src/MovingAverage.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MovingAverage()

◆ ~MovingAverage()

Member Function Documentation

◆ add()

◆ getAverage()

◆ getAverageMulti()

◆ getPerfJSON()

◆ getPerfXML()

◆ getSum()

◆ getSumMulti()

◆ getThroughput()

◆ getThroughputMulti()

◆ getTotal()

◆ shiftBins()

◆ UnitTest()

Member Data Documentation

◆ binCount

◆ binTime

◆ currentBin

◆ currentBinStart

◆ entries

◆ mutex

◆ totalCount

◆ totalValue