Provides an abstraction for a shared memory buffer that can be used to pass entry, exit, epoch and short region events from Profile to ApplicationSampler. More...

#include <ApplicationRecordLog.hpp>

Inheritance diagram for geopm::ApplicationRecordLog:

[legend]

Public Member Functions
virtual	~ApplicationRecordLog ()=default
	Destructor for pure virtual base class.

virtual void	enter (uint64_t hash, const geopm_time_s &time)=0
	Create a message in the log defining a region entry.

virtual void	exit (uint64_t hash, const geopm_time_s &time)=0
	Create a message in the log defining a region exit.

virtual void	epoch (const geopm_time_s &time)=0
	Create a message in the log defining an epoch event.

virtual void	dump (std::vector< record_s > &records, std::vector< short_region_s > &short_regions)=0
	Get all events that have occurred since the last call to dump().

virtual void	affinity (const geopm_time_s &time, int cpu_idx)=0

virtual void	cpuset_changed (const geopm_time_s &time)=0

virtual void	start_profile (const geopm_time_s &time, const std::string &profile_name)=0

virtual void	stop_profile (const geopm_time_s &time, const std::string &profile_name)=0

virtual void	overhead (const geopm_time_s &time, double overhead_sec)=0

Static Public Member Functions
static std::unique_ptr< ApplicationRecordLog >	make_unique (std::shared_ptr< SharedMemory > shmem)
	Factory constructor.

static size_t	buffer_size (void)
	Gets the shared memory size requirement.

static size_t	max_record (void)
	Gets the maximum number of records.

static size_t	max_region (void)
	Gets the maximum number of short region events.

Protected Member Functions
	ApplicationRecordLog ()=default

Static Protected Attributes
static constexpr size_t	M_LAYOUT_SIZE = 57384

static constexpr int	M_MAX_RECORD = 1024

static constexpr int	M_MAX_REGION = M_MAX_RECORD + 1

Detailed Description

Provides an abstraction for a shared memory buffer that can be used to pass entry, exit, epoch and short region events from Profile to ApplicationSampler.

This class provides a compression of short running regions to avoid overwhelming the controller with too many records.

If the Profile calls entry() and then exit() for the same region hash within a control interval (between two calls to dump()) the entry event is converted into a short region event. All future pairs of entry() and exit() using this hash but prior to the next dump() call will be aggregated into this short region event.

If a region hash was observed as a short region during a control interval (it was both entered and exited), but the dump() call occurs prior to an exit() call that would close the region, the subsequent exit() call to this region will be classified as a short region event and the intervening interval of time will be recorded in this event created by the exit() call.

There is a loss of information when a region is entered and exited within one control loop when compared to the case where a dump() call is made between an entry() and exit() call. In the former case, the exact timestamp associated with all region exit and entry events for a particular hash that occur after the first enter() call for that hash and prior to the next dump() call are lost. The short region event records the number of calls to the hashed region and the total amount of time in the region, but the exact sequence and timing of events following the first enter() is not recorded.

Constructor & Destructor Documentation

◆ ~ApplicationRecordLog()

virtual geopm::ApplicationRecordLog::~ApplicationRecordLog ( )

virtualdefault

Destructor for pure virtual base class.

◆ ApplicationRecordLog()

geopm::ApplicationRecordLog::ApplicationRecordLog ( )

protecteddefault

Member Function Documentation

◆ affinity()

virtual void geopm::ApplicationRecordLog::affinity	(	const geopm_time_s &	time,
		int	cpu_idx
	)

pure virtual

Implemented in geopm::ApplicationRecordLogImp.

◆ buffer_size()

size_t geopm::ApplicationRecordLog::buffer_size ( void )

static

Gets the shared memory size requirement.

This method returns the value to use when sizing the SharedMemory object used to construct the ApplicationRecordLog.

Returns: Size requirement for SharedMemory object.

◆ cpuset_changed()

virtual void geopm::ApplicationRecordLog::cpuset_changed ( const geopm_time_s & time )

pure virtual

Implemented in geopm::ApplicationRecordLogImp.

◆ dump()

virtual void geopm::ApplicationRecordLog::dump	(	std::vector< record_s > &	records,
		std::vector< short_region_s > &	short_regions
	)

pure virtual

Get all events that have occurred since the last call to dump().

Called by the ApplicationSampler to gather all records that have been created by the Profile object since the last time the method was called. The call effectively removes all of the records and short region data from the table.

For optimal performance the user should reserve space in the output vectors using the max_record() and max_region() static methods:

records.reserve(ApplicationRecordLog::max_record());
short_regions.reserve(ApplicationRecordLog::max_region());

Note that the "signal" in any sort region events in the records output vector is the index into the short_regions output vector, and the length of the short_regions vector will be equal to the number of events with type "EVENT_SHORT_REGION" in the records output vector.

Parameters

[out]	records	Vector of records written since last dump().
[out]	short_regions	Vector of short region data about any short regions events in the records output vector.

Implemented in geopm::ApplicationRecordLogImp.

◆ enter()

virtual void geopm::ApplicationRecordLog::enter	(	uint64_t	hash,
		const geopm_time_s &	time
	)

pure virtual

Create a message in the log defining a region entry.

Called by the Profile object when a region is entered. This creates a record_s in the log indicating entry if the region is entered for the first time since the last dump() call, or it sets the start time for a short region if the region was entered and exited since the last call to dump().

Parameters

[in]	hash	The region hash that is entered.
[in]	time	The timestamp when the entry event occurred.

Implemented in geopm::ApplicationRecordLogImp.

◆ epoch()

virtual void geopm::ApplicationRecordLog::epoch ( const geopm_time_s & time )

pure virtual

Create a message in the log defining an epoch event.

Called by the Profile object when an epoch event occurs. This creates a record_s in the log indicating that an epoch event occurred.

Parameters

time	[in] The timestamp when the epoch event occurred.

Implemented in geopm::ApplicationRecordLogImp.

◆ exit()

virtual void geopm::ApplicationRecordLog::exit	(	uint64_t	hash,
		const geopm_time_s &	time
	)

pure virtual

Create a message in the log defining a region exit.

Called by the Profile object when a region is exited. This creates a record_s in the log indicating exit if the matching entry for the region was called prior to the last dump() call. If the region was entered since the last call to dump(), the first entry event will be converted into a short region event. The call to exit() for short regions has the effect of updating the short region event time and count values.

Parameters

hash	[in] The region hash that was exited.
time	[in] The timestamp when the exit event occurred.

Implemented in geopm::ApplicationRecordLogImp.

◆ make_unique()

std::unique_ptr< ApplicationRecordLog > geopm::ApplicationRecordLog::make_unique ( std::shared_ptr< SharedMemory > shmem )

static

Factory constructor.

Parameters

[in] shmem Shared memory object of at least the size returned by buffer_size().

◆ max_record()

size_t geopm::ApplicationRecordLog::max_record ( void )

static

Gets the maximum number of records.

This method returns the value to use when reserving elements in the records vector passed to dump().

Returns: The maximum length of the records vector after a call to dump().

◆ max_region()

size_t geopm::ApplicationRecordLog::max_region ( void )

static

Gets the maximum number of short region events.

This method returns the value to use when reserving elements in the short_regions vector passed to dump().

Returns: The maximum length of the short_regions vector after a call to dump().

◆ overhead()

virtual void geopm::ApplicationRecordLog::overhead	(	const geopm_time_s &	time,
		double	overhead_sec
	)

pure virtual

Implemented in geopm::ApplicationRecordLogImp.

◆ start_profile()

virtual void geopm::ApplicationRecordLog::start_profile	(	const geopm_time_s &	time,
		const std::string &	profile_name
	)

pure virtual

Implemented in geopm::ApplicationRecordLogImp.

◆ stop_profile()

virtual void geopm::ApplicationRecordLog::stop_profile	(	const geopm_time_s &	time,
		const std::string &	profile_name
	)

pure virtual

Implemented in geopm::ApplicationRecordLogImp.

Member Data Documentation

◆ M_LAYOUT_SIZE

constexpr size_t geopm::ApplicationRecordLog::M_LAYOUT_SIZE = 57384

staticconstexprprotected

◆ M_MAX_RECORD

constexpr int geopm::ApplicationRecordLog::M_MAX_RECORD = 1024

staticconstexprprotected

◆ M_MAX_REGION

constexpr int geopm::ApplicationRecordLog::M_MAX_REGION = M_MAX_RECORD + 1

staticconstexprprotected

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~ApplicationRecordLog()

◆ ApplicationRecordLog()

Member Function Documentation

◆ affinity()

◆ buffer_size()

◆ cpuset_changed()

◆ dump()

◆ enter()

◆ epoch()

◆ exit()

◆ make_unique()

◆ max_record()

◆ max_region()

◆ overhead()

◆ start_profile()

◆ stop_profile()

Member Data Documentation

◆ M_LAYOUT_SIZE

◆ M_MAX_RECORD

◆ M_MAX_REGION