#include <SampleAggregator.hpp>

Inheritance diagram for geopm::SampleAggregator:

Public Member Functions
virtual	~SampleAggregator ()=default
	Default destructor of pure virtual base. More...

virtual int	push_signal (const std::string &signal_name, int domain_type, int domain_idx)=0
	Push a signal to be accumulated per-region. More...

virtual int	push_signal_total (const std::string &signal_name, int domain_type, int domain_idx)=0
	Push a signal to be accumulated per-region as a total. More...

virtual int	push_signal_average (const std::string &signal_name, int domain_type, int domain_idx)=0
	Push a signal to be accumulated per-region as an average. More...

virtual void	update (void)=0
	Update stored totals for each signal. More...

virtual double	sample_application (int signal_idx)=0
	Get the aggregated value of a signal. More...

virtual double	sample_epoch (int signal_idx)=0
	Get the aggregated value of a signal since the first epoch. More...

virtual double	sample_region (int signal_idx, uint64_t region_hash)=0
	Get the aggregated value of a signal during the execution of a particular region. More...

virtual double	sample_epoch_last (int signal_idx)=0
	Get the aggregated value of a signal over the last completed epoch interval. More...

virtual double	sample_region_last (int signal_idx, uint64_t region_hash)=0
	Get the aggregated value of a signal during the the last completed execution of a particular region. More...

virtual void	period_duration (double duration)=0
	Set the time period for sample_period_last() More...

virtual int	get_period (void)=0
	Get the index of the current time period. More...

virtual double	sample_period_last (int signal_idx)=0
	Get the aggregated value of a signal during the last completed time interval. More...

Static Public Member Functions
static std::unique_ptr< SampleAggregator >	make_unique (void)
	Returns a unique_ptr to a concrete object constructed using the underlying implementation. More...

Protected Member Functions
	SampleAggregator ()=default

Constructor & Destructor Documentation

◆ ~SampleAggregator()

virtual geopm::SampleAggregator::~SampleAggregator ( )

virtualdefault

Default destructor of pure virtual base.

◆ SampleAggregator()

geopm::SampleAggregator::SampleAggregator ( )

protecteddefault

Member Function Documentation

◆ get_period()

virtual int geopm::SampleAggregator::get_period ( void )

pure virtual

Get the index of the current time period.

Provides an index of completed durations. Will return zero if periodic sampling is not enabled (when period_duration() was not called prior to update()). When periodic sampling is enabled, the sample_period_last() method will return 0.0 until a full period has elapsed, this corresponds to when get_period() returns a value greater than zero.

Returns: The number of completed durations since the application start.

Implemented in geopm::SampleAggregatorImp.

◆ make_unique()

std::unique_ptr< SampleAggregator > geopm::SampleAggregator::make_unique ( void )

static

Returns a unique_ptr to a concrete object constructed using the underlying implementation.

◆ period_duration()

virtual void geopm::SampleAggregator::period_duration ( double duration )

pure virtual

Set the time period for sample_period_last()

Calling this method prior to the first call to update() enables signals to be accumulated on a periodic basis. The sample_period_last() method is used to sample an accumulated value over the last completed time interval, and the period of the interval is configured by calling this method.

The sample_period_last() method will always return NAN If period_duration() is not called prior to the first call to update(). The period_duration() method will throw an Exception if it is called after the first call to update().

Parameters

[in] duration Time interval in seconds over which the sample_region_last() method is aggregated (must be greater than 0.0).

Implemented in geopm::SampleAggregatorImp.

◆ push_signal()

virtual int geopm::SampleAggregator::push_signal	(	const std::string &	signal_name,
		int	domain_type,
		int	domain_idx
	)

pure virtual

Push a signal to be accumulated per-region.

Check the signal behavior and call push_signal_total() or push_signal_average() accordingly.

Parameters

[in]	signal_name	Name of the signal to sample and aggregate.
[in]	domain_type	Domain type over which the region hash and signal should be sampled.
[in]	domain_idx	Domain over which the region hash and signal should be sampled.

Returns: Index of signal to be used with sample(). This index matches the return value of PlatformIO::push_signal() for the same signal.

Implemented in geopm::SampleAggregatorImp.

◆ push_signal_average()

virtual int geopm::SampleAggregator::push_signal_average	(	const std::string &	signal_name,
		int	domain_type,
		int	domain_idx
	)

pure virtual

Push a signal to be accumulated per-region as an average.

The signal name must be a valid signal available through PlatformIO. Note that unlike other signals this is an average value accumulated per region by a time weighted mean of the values sampled while in the region. Region entry and exit are not exact and are determined by the value of the REGION_HASH signal at the time of read_batch(). This aggregation should be used for signals that vary up and down over time such as the CPU frequency.

Parameters

[in]	signal_name	Name of the signal to sample and aggregate.
[in]	domain_type	Domain type over which the region hash and signal should be sampled.
[in]	domain_idx	Domain over which the region hash and signal should be sampled.

Returns: Index of signal to be used with sample(). This index matches the return value of PlatformIO::push_signal() for the same signal.

Implemented in geopm::SampleAggregatorImp.

◆ push_signal_total()

virtual int geopm::SampleAggregator::push_signal_total	(	const std::string &	signal_name,
		int	domain_type,
		int	domain_idx
	)

pure virtual

Push a signal to be accumulated per-region as a total.

The signal name must be a valid signal available through PlatformIO. Note that unlike other signals this is a total accumulated per region by subtracting the value of the signal at the region exit from the region entry. Region entry and exit are not exact and are determined by the value of the REGION_HASH signal at the time of read_batch(). This aggregation should only be used for signals that are monotonically increasing, such as time.

Parameters

[in]	signal_name	Name of the signal to sample and aggregate.
[in]	domain_type	Domain type over which the region hash and signal should be sampled.
[in]	domain_idx	Domain over which the region hash and signal should be sampled.

Returns: Index of signal to be used with sample(). This index matches the return value of PlatformIO::push_signal() for the same signal.

Implemented in geopm::SampleAggregatorImp.

◆ sample_application()

virtual double geopm::SampleAggregator::sample_application ( int signal_idx )

pure virtual

Get the aggregated value of a signal.

The aggregation type is determined by which method was used to push the signal: push_signal_total() or push_signal_average(). The value returned is aggregated over all samples since the application start.

Parameters

[in] signal_idx Index returned by a previous call to push_signal_total() or push_signal_average().

Returns: Aggregated value for the signal regardless of region or epoch.

Implemented in geopm::SampleAggregatorImp.

◆ sample_epoch()

virtual double geopm::SampleAggregator::sample_epoch ( int signal_idx )

pure virtual

Get the aggregated value of a signal since the first epoch.

The aggregation type is determined by which method was used to push the signal: push_signal_total() or push_signal_average(). The value returned is aggregated over all samples since the first epoch observed over the domain specified when the signal was pushed.

Parameters

[in] signal_idx Index returned by a previous call to push_signal_total() or push_signal_average().

Returns: Aggregated value for the signal since first epoch, or NAN if called before first call to update().

Implemented in geopm::SampleAggregatorImp.

◆ sample_epoch_last()

virtual double geopm::SampleAggregator::sample_epoch_last ( int signal_idx )

pure virtual

Get the aggregated value of a signal over the last completed epoch interval.

The aggregation type is determined by which method was used to push the signal: push_signal_total() or push_signal_average(). The value returned is aggregated over all samples between the last two samples when the epoch count changed.

Parameters

[in] signal_idx Index returned by a previous call to push_signal_total() or push_signal_average().

Returns: Aggregated value for the signal over last epoch, or NAN if called before first call to update().

Implemented in geopm::SampleAggregatorImp.

◆ sample_period_last()

virtual double geopm::SampleAggregator::sample_period_last ( int signal_idx )

pure virtual

Get the aggregated value of a signal during the last completed time interval.

Implemented in geopm::SampleAggregatorImp.

◆ sample_region()

virtual double geopm::SampleAggregator::sample_region	(	int	signal_idx,
		uint64_t	region_hash
	)

pure virtual

Get the aggregated value of a signal during the execution of a particular region.

The aggregation type is determined by which method was used to push the signal: push_signal_total() or push_signal_average(). The value returned is aggregated over all samples where the REGION_HASH signal matched the value specified for the domain pushed. The returned value is zero for push_signal_total() aggregation, and NAN for push_signal_average() aggregation if the region was not observed for any samples.

Parameters

[in]	signal_idx	Index returned by a previous call to push_signal_total() or push_signal_average().
[in]	region_hash	The region hash to look up data for.

Returns: Aggregated value for the signal during the region, or NAN if called before first call to update().

Implemented in geopm::SampleAggregatorImp.

◆ sample_region_last()

virtual double geopm::SampleAggregator::sample_region_last	(	int	signal_idx,
		uint64_t	region_hash
	)

pure virtual

Get the aggregated value of a signal during the the last completed execution of a particular region.

The aggregation type is determined by which method was used to push the signal: push_signal_total() or push_signal_average(). The value returned is aggregated over the last contiguous set of samples where the REGION_HASH signal matched the value specified for the domain pushed. Note that if the region is currently executing, the value reported is aggregated over the last region interval, not the currently executing interval. The returned value is zero for push_signal_total() aggregation, and NAN for push_signal_average() aggregation if a completed region with the specified hash has not been observed.

Parameters

[in]	signal_idx	Index returned by a previous call to push_signal_total() or push_signal_average().
[in]	region_hash	The region hash to look up data for.

Returns: Aggregated value for the signal during the last execution of the region, or NAN if called before first call to update() or if period_duration() was not called.

Implemented in geopm::SampleAggregatorImp.

◆ update()

virtual void geopm::SampleAggregator::update ( void )

pure virtual

Update stored totals for each signal.

This method is to be called after each call to PlatformIO::read_batch(). This should be called with every PlatformIO update because sample_total() maybe not be called until the end of execution.

Implemented in geopm::SampleAggregatorImp.

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ ~SampleAggregator()

◆ SampleAggregator()

Member Function Documentation

◆ get_period()

◆ make_unique()

◆ period_duration()

◆ push_signal()

◆ push_signal_average()

◆ push_signal_total()

◆ sample_application()

◆ sample_epoch()

◆ sample_epoch_last()

◆ sample_period_last()

◆ sample_region()

◆ sample_region_last()

◆ update()