Describes one or more report to instantiate. More...

#include <ReportDescriptor.hpp>

Public Member Functions
void	disable ()
	Calling this method causes the simulation to skip this descriptor when it is setting up its reports. This operation cannot be undone.

bool	isEnabled () const
	See if this descriptor is enabled or not. Disabling a descriptor means that it will be filtered from report generation.

	ReportDescriptor (const std::string &_loc_pattern, const std::string &_def_file, const std::string &_dest_file, const std::string &_format="text")
	Construct a report decsriptor.

	ReportDescriptor (const ReportDescriptor &)=default
	Allow construction.

ReportDescriptor &	operator= (const ReportDescriptor &)=default
	Allow assignment.

	~ReportDescriptor ()
	Destructor (note that triggered reports are automatically flushed)

const std::string &	getDescriptorPattern () const
	Getter for this descriptor's pattern, e.g. "_global".

const std::string &	getDescriptorDefFile () const
	Getter for this descriptor's def_file, e.g. "simple_stats.yaml".

const std::string &	getDescriptorDestFile () const
	Getter for this descriptor's dest_file, e.g. "out.json".

const std::string &	getDescriptorFormat () const
	Getter for this descriptor's format, e.g. "json_reduced".

const std::string &	getDescriptorOrigDestFile () const
	This descriptor may have had its dest_file changed when the the Simulation::setupReports() method was called. The report file will still end up in the dest_file that you gave the descriptor, but this getter is added if you need to ask this descriptor what its immutable dest_file was from the beginning.

std::shared_ptr< statistics::ReportStatisticsArchive >	logOutputValuesToArchive (const std::string &dir)
	Tell the descriptor to send all of its writeOutput / updateOutput statistics values to a binary archive. Returns the archive object that will be responsible for feeding the data into the archive. Returns null if unable to connect to the database.

std::shared_ptr< statistics::StreamNode >	createRootStatisticsStream ()
	Create and return a StreamNode object that sits at the top of a tree hierarchy that describes the Report/Subreport/StatisticInstance layout of this descriptor's report.

bool	configSimDbReports (app::ReportStatsCollector *collector)
	Get ready for SimDB report collection.

void	ignoreFurtherUpdates ()
	Report descriptors may be triggered to stop early - ensure no further updates are written to disk.

std::string	stringize () const
	Represents this descriptor as a string.

report::format::BaseFormatter *	addInstantiation (Report r, Simulation sim, std::ostream *out=nullptr)
	Tracks a report instantiated based on this descriptor and allocates a new formatter for it. Later, these tracked reports can be iterated and saved to different destinations (or the same) depending on their order.

std::vector< inst_t >	getInstantiations () const
	Returns the vector of instantiated reports based on this descriptor.

std::vector< Report * >	getPendingInstantiations () const
	Returns a vector of reports that have not been instantiated yet, but will be when this report descriptor's start trigger fires.

std::vector< Report * >	getAllInstantiations () const
	Returns all report instantiations, including those already instantiated (no report start trigger) and pending report instantiations (they have a start trigger, and it hasn't fired yet)

void	disableLegacyReports ()
	In MAP v2.1, we provide report systems for both legacy reports and SimDB-exported reports. We allow using both at the same time in order to validate the SimDB reports for backwards compatibility.

uint32_t	writeOutput (std::ostream *out=nullptr)
	Saves all of the instantiations whose formatters do not support 'update' to their respective destinations. Returns the number of reports written in full in this call.

uint32_t	updateOutput (std::ostream *out=nullptr)
	Updates all of the instantiations whose formatters support 'update', possibly by writing to the destinations. Returns the number of reports updated in this call.

void	skipOutput ()
	Let the descriptor know to skip over one update of data.

void	capUpdatesToOncePerTick (const Scheduler *scheduler)
	Instruct this descriptor to automatically ignore any "duplicate" updates that occur at the exact same tick.

void	setSkippedAnnotator (std::shared_ptr< sparta::trigger::SkippedAnnotatorBase > annotator)
	Give this descriptor a specific annotator subclass for printing skipped update information to reports.

void	clearDestinationFiles (const Simulation &sim)
	Clears all destination files that will be filled with instances of this report descriptor.

void	teardown ()
	Called when the ReportRepository is shutting down.

uint32_t	getUsageCount () const
	Returns the usage count (incremented by addInstantiation)

uint32_t	getNumWrites () const
	Returns the number of writes done on this report descriptor's instantiated report formatters.

uint32_t	getNumUpdates () const
	Returns the number of updates done on this report descriptor's instantiated report formatters.

std::string	computeFilename (const Report *r, const std::string &sim_name, uint32_t idx) const
	Computes the filename to which this reportdescriptor will be saved using any necessary variables in the name based on its instantiation context and sim_name.

Static Public Member Functions
static bool	isValidFormatName (const std::string &format)
	Determines if format is a valid name for formatter. This allows the command line parser to disregard tokens at the end of a report command which are not formatters and instead interpret them as positional arguments.

Public Attributes
std::string	loc_pattern
	Node location string (pattern) on which report should be generated. Typically "" or top.

std::string	def_file
	Filename of report definition. If '@', auto generates reports with all counters and stats of loc_pattern.

std::string	dest_file
	Destination filename to which report will be written. Later this will represent other types of destination besides files.

std::string	format
	Optional formatting string (how to write to the file). This is converted to lower-case at construction.

NamedExtensions	extensions_
	Key-value extensions used by parsers to bind opaque report configurations to descriptors.

MetaDataKeyValues	header_metadata_
	Metadata to include in report headers.

Static Public Attributes
static const char *	GLOBAL_KEYWORD
	Global search scope node keyword for report locations.

Friends
class	ReportDescriptorCollection

Detailed Description

Describes one or more report to instantiate.

Definition at line 75 of file ReportDescriptor.hpp.

Constructor & Destructor Documentation

◆ ReportDescriptor()

sparta::app::ReportDescriptor::ReportDescriptor	(	const std::string &	_loc_pattern,
		const std::string &	_def_file,
		const std::string &	_dest_file,
		const std::string &	_format = "text" )

Construct a report decsriptor.

Parameters

_loc_pattern	Location patern identifying 1 or more nodes on which to construct a report
_def_file	Report definition file path relative to current working directory. Note, this may also be '@' to generate reports which each contain all counters and stats in the subtree(s) of the node(s) described by _loc_pattern.
_dest_file	File to which these reports should be written. This may contain report name wildcards to identify output files based on replacements made in _loc_pattern. Output formatter is chosen by the file extension of this path unless explicitly set in _format. If sparta::utils::COUT_FILENAME, will write to stdout. If sparta::utils::CERR_FILENAME, will write to stderr. Note that A formatter which supports ostream writing must be chosen to support this or an exception will be thrown
_format	Optional explicit format specificier. Extensions allowed are all those defined in sparta::report::format::BaseFormatter::FACTORIES. If omitted, deduces the format based on _dest_file.

Exceptions

SpartaException if the _dest_file is 1 or 2 and the formatter chosen (by _format if specified or the secondarily _dest_file) is not an ostream formatter (is not a sparta::report::format::BaseOstreamFormatter). This is tested in construction so that no time is wasted on failure - as opposed to checkout formatters when finally writing reports

Member Function Documentation

◆ addInstantiation()

report::format::BaseFormatter * sparta::app::ReportDescriptor::addInstantiation	(	Report *	r,
		Simulation *	sim,
		std::ostream *	out = nullptr )

Tracks a report instantiated based on this descriptor and allocates a new formatter for it. Later, these tracked reports can be iterated and saved to different destinations (or the same) depending on their order.

Parameters

r	Report to track. Caller maintains ownership of this. Must outlive this instance of ReportDescriptor. Must be fully populated because the formatter created by this fuction may be written to immediately
fmt	The output formatter associated with this report. Caller maintains ownership of this. Must outlive this instance of ReportDescriptor
out	Output stream to write actions to. If nullptr, no actions are written

Returns: Newly allocated BaseFormatter. Caller is resposible for deallocation. Allocated through sparta::report::format::FormatterFactory::factory method which allocates using 'new'. This new formatter will read the input report and be initialized based on its content. The header of the report may be written to the formatter immediately

◆ clearDestinationFiles()

void sparta::app::ReportDescriptor::clearDestinationFiles ( const Simulation & sim )

Clears all destination files that will be filled with instances of this report descriptor.

This is done at simulation startup so that reports are empty until written. After simulation, reports are appended to these files

◆ computeFilename()

std::string sparta::app::ReportDescriptor::computeFilename	(	const Report *	r,
		const std::string &	sim_name,
		uint32_t	idx ) const

Computes the filename to which this reportdescriptor will be saved using any necessary variables in the name based on its instantiation context and sim_name.

Parameters

r	Report whose filename should be computed.
idx	Index of the report in this ReportDescriptor's instantiations This is required to fill in wildcards in the report name where multiple reports are generated from one descriptor. Each can have its own index in its name.

See also: computeOutputFilename

Note: Does not attempt to open the filename

◆ disable()

void sparta::app::ReportDescriptor::disable ( )

inline

Calling this method causes the simulation to skip this descriptor when it is setting up its reports. This operation cannot be undone.

Definition at line 273 of file ReportDescriptor.hpp.

◆ disableLegacyReports()

void sparta::app::ReportDescriptor::disableLegacyReports ( )

inline

In MAP v2.1, we provide report systems for both legacy reports and SimDB-exported reports. We allow using both at the same time in order to validate the SimDB reports for backwards compatibility.

This function is called when these two command line options are used: –enable-simdb-reports –disable-legacy-reports

Using "--disable-legacy-reports" in MAP v2.1 is akin to saying "I have verified that the SimDB reports are the same and I only want to use SimDB now".

This method will be removed in a future release.

Definition at line 481 of file ReportDescriptor.hpp.

◆ getAllInstantiations()

std::vector< Report * > sparta::app::ReportDescriptor::getAllInstantiations ( ) const

inline

Returns all report instantiations, including those already instantiated (no report start trigger) and pending report instantiations (they have a start trigger, and it hasn't fired yet)

Definition at line 456 of file ReportDescriptor.hpp.

Here is the call graph for this function:

◆ getDescriptorDefFile()

const std::string & sparta::app::ReportDescriptor::getDescriptorDefFile ( ) const

inline

Getter for this descriptor's def_file, e.g. "simple_stats.yaml".

Definition at line 340 of file ReportDescriptor.hpp.

◆ getDescriptorDestFile()

const std::string & sparta::app::ReportDescriptor::getDescriptorDestFile ( ) const

inline

Getter for this descriptor's dest_file, e.g. "out.json".

Definition at line 345 of file ReportDescriptor.hpp.

◆ getDescriptorFormat()

const std::string & sparta::app::ReportDescriptor::getDescriptorFormat ( ) const

inline

Getter for this descriptor's format, e.g. "json_reduced".

Definition at line 350 of file ReportDescriptor.hpp.

◆ getDescriptorOrigDestFile()

const std::string & sparta::app::ReportDescriptor::getDescriptorOrigDestFile ( ) const

inline

This descriptor may have had its dest_file changed when the the Simulation::setupReports() method was called. The report file will still end up in the dest_file that you gave the descriptor, but this getter is added if you need to ask this descriptor what its immutable dest_file was from the beginning.

Definition at line 359 of file ReportDescriptor.hpp.

◆ getDescriptorPattern()

const std::string & sparta::app::ReportDescriptor::getDescriptorPattern ( ) const

inline

Getter for this descriptor's pattern, e.g. "_global".

Definition at line 335 of file ReportDescriptor.hpp.

◆ getInstantiations()

std::vector< inst_t > sparta::app::ReportDescriptor::getInstantiations ( ) const

inline

Returns the vector of instantiated reports based on this descriptor.

Definition at line 432 of file ReportDescriptor.hpp.

◆ getNumUpdates()

uint32_t sparta::app::ReportDescriptor::getNumUpdates ( ) const

inline

Returns the number of updates done on this report descriptor's instantiated report formatters.

Definition at line 547 of file ReportDescriptor.hpp.

◆ getNumWrites()

uint32_t sparta::app::ReportDescriptor::getNumWrites ( ) const

inline

Returns the number of writes done on this report descriptor's instantiated report formatters.

Definition at line 541 of file ReportDescriptor.hpp.

◆ getPendingInstantiations()

std::vector< Report * > sparta::app::ReportDescriptor::getPendingInstantiations ( ) const

inline

Returns a vector of reports that have not been instantiated yet, but will be when this report descriptor's start trigger fires.

Definition at line 440 of file ReportDescriptor.hpp.

◆ getUsageCount()

uint32_t sparta::app::ReportDescriptor::getUsageCount ( ) const

inline

Returns the usage count (incremented by addInstantiation)

Definition at line 535 of file ReportDescriptor.hpp.

◆ ignoreFurtherUpdates()

void sparta::app::ReportDescriptor::ignoreFurtherUpdates ( )

inline

Report descriptors may be triggered to stop early - ensure no further updates are written to disk.

Definition at line 386 of file ReportDescriptor.hpp.

◆ isEnabled()

bool sparta::app::ReportDescriptor::isEnabled ( ) const

inline

See if this descriptor is enabled or not. Disabling a descriptor means that it will be filtered from report generation.

Definition at line 281 of file ReportDescriptor.hpp.

◆ stringize()

std::string sparta::app::ReportDescriptor::stringize ( ) const

inline

Represents this descriptor as a string.

Definition at line 393 of file ReportDescriptor.hpp.

◆ updateOutput()

uint32_t sparta::app::ReportDescriptor::updateOutput ( std::ostream * out = nullptr )

Updates all of the instantiations whose formatters support 'update', possibly by writing to the destinations. Returns the number of reports updated in this call.

Parameters

out	Print reports being written to out unless nulltr

◆ writeOutput()

uint32_t sparta::app::ReportDescriptor::writeOutput ( std::ostream * out = nullptr )

Saves all of the instantiations whose formatters do not support 'update' to their respective destinations. Returns the number of reports written in full in this call.

Parameters

out	Print reports being written to out unless nulltr

Friends And Related Symbol Documentation

◆ ReportDescriptorCollection

friend class ReportDescriptorCollection

friend

Definition at line 224 of file ReportDescriptor.hpp.

Member Data Documentation

◆ def_file

std::string sparta::app::ReportDescriptor::def_file

Filename of report definition. If '@', auto generates reports with all counters and stats of loc_pattern.

Definition at line 243 of file ReportDescriptor.hpp.

◆ dest_file

std::string sparta::app::ReportDescriptor::dest_file

Destination filename to which report will be written. Later this will represent other types of destination besides files.

Definition at line 249 of file ReportDescriptor.hpp.

◆ extensions_

NamedExtensions sparta::app::ReportDescriptor::extensions_

Key-value extensions used by parsers to bind opaque report configurations to descriptors.

Definition at line 261 of file ReportDescriptor.hpp.

◆ format

std::string sparta::app::ReportDescriptor::format

Optional formatting string (how to write to the file). This is converted to lower-case at construction.

Definition at line 255 of file ReportDescriptor.hpp.

◆ GLOBAL_KEYWORD

const char* sparta::app::ReportDescriptor::GLOBAL_KEYWORD

static

Global search scope node keyword for report locations.

Definition at line 231 of file ReportDescriptor.hpp.

◆ header_metadata_

MetaDataKeyValues sparta::app::ReportDescriptor::header_metadata_

Metadata to include in report headers.

Definition at line 266 of file ReportDescriptor.hpp.

◆ loc_pattern

std::string sparta::app::ReportDescriptor::loc_pattern

Node location string (pattern) on which report should be generated. Typically "" or top.

Definition at line 237 of file ReportDescriptor.hpp.

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

/github/workspace/sparta/sparta/app/ReportDescriptor.hpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ReportDescriptor()

Member Function Documentation

◆ addInstantiation()

◆ clearDestinationFiles()

◆ computeFilename()

◆ disable()

◆ disableLegacyReports()

◆ getAllInstantiations()

◆ getDescriptorDefFile()

◆ getDescriptorDestFile()

◆ getDescriptorFormat()

◆ getDescriptorOrigDestFile()

◆ getDescriptorPattern()

◆ getInstantiations()

◆ getNumUpdates()

◆ getNumWrites()

◆ getPendingInstantiations()

◆ getUsageCount()

◆ ignoreFurtherUpdates()

◆ isEnabled()

◆ stringize()

◆ updateOutput()

◆ writeOutput()

Friends And Related Symbol Documentation

◆ ReportDescriptorCollection

Member Data Documentation

◆ def_file

◆ dest_file

◆ extensions_

◆ format

◆ GLOBAL_KEYWORD

◆ header_metadata_

◆ loc_pattern