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.

bool	isSingleTimeseriesReport () const
	Check if this descriptor holds only one report instantiation, and that it is a timeseries report (.csv)

bool	isSingleNonTimeseriesReport () const
	Check if this descriptor holds only one report instantiation, and that it is not a timeseries report. For example, .html, .json, .txt, and so on.

void	configureAsyncTimeseriesReport (simdb::AsyncTaskEval task_queue, simdb::ObjectManager sim_db, const Clock &root_clk)
	Switch this descriptor's timeseries report generation from synchronous .csv generation to asynchronous database persistence.

void	configureAsyncNonTimeseriesReport (simdb::AsyncTaskEval task_queue, simdb::ObjectManager sim_db)
	Switch this descriptor's report generation from synchronous to asynchronous database persistence. This method is intended only for descriptors that have just one non-timeseries report format.

db::ReportHeader *	getTimeseriesDatabaseHeader ()
	Give access to the database timeseries header. This will return null when this descriptor is used for any non- timeseries report format (json, json_reduced, txt, etc.) or when the "simdb" feature has been disabled.

void	doPostProcessing (simdb::AsyncTaskEval task_queue, simdb::ObjectManager sim_db)
	Do any post-simulation post processing steps needed. This is typically used for final wrap-up this descriptor needs to do in the simulation database, so the two inputs are the SimDB and the AsyncTaskEval objects that belong to the app::Simulation and sparta::ReportRepository objects, but other non-database work may need to be completed post- simulation as well.

std::map< std::string, std::shared_ptr< report::format::BaseFormatter > >	getFormattersByFilename () const
	Provide access to the formatters we have been using so they can coordinate with the reporting infrastructure to write various metadata to the database.

	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
	When SimDB has automatic report verification enabled, this descriptor may have had its dest_file changed when 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.

void	inspectSimulatorFeatureValues (const app::FeatureConfiguration *feature_config)
	Give the descriptor a chance to see the –feature values that were set at the command line, if any. This is called just prior to the main simulation loop.

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)

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.

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 88 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

◆ configureAsyncNonTimeseriesReport()

void sparta::app::ReportDescriptor::configureAsyncNonTimeseriesReport	(	simdb::AsyncTaskEval *	task_queue,
		simdb::ObjectManager *	sim_db
	)

Switch this descriptor's report generation from synchronous to asynchronous database persistence. This method is intended only for descriptors that have just one non-timeseries report format.

Call "isSingleNonTimeseriesReport()" first before calling this method to be sure, otherwise this method may throw.

◆ configureAsyncTimeseriesReport()

void sparta::app::ReportDescriptor::configureAsyncTimeseriesReport	(	simdb::AsyncTaskEval *	task_queue,
		simdb::ObjectManager *	sim_db,
		const Clock &	root_clk
	)

Switch this descriptor's timeseries report generation from synchronous .csv generation to asynchronous database persistence.

The task queue object passed in is the worker thread object, which is shared among all report descriptors in the simulation.

The simulation database passed in is the object with the actual connection to the physical database. This object is shared with the Simulation class and other descriptors.

The Scheduler passed in is the one our simulation is running on, and the Clock passed in is the simulation's root clock. Both of these objects are used in order to get the "current time" value at each report update (current cycle, simulated time, etc.)

◆ 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 285 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 548 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 430 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 435 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 440 of file ReportDescriptor.hpp.

◆ getDescriptorOrigDestFile()

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

inline

When SimDB has automatic report verification enabled, this descriptor may have had its dest_file changed when 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 450 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 425 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 524 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 616 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 610 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 532 of file ReportDescriptor.hpp.

◆ getUsageCount()

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

inline

Returns the usage count (incremented by addInstantiation)

Definition at line 604 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 478 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 293 of file ReportDescriptor.hpp.

◆ stringize()

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

inline

Represents this descriptor as a string.

Definition at line 485 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 236 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 255 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 261 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 273 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 267 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 243 of file ReportDescriptor.hpp.

◆ header_metadata_

MetaDataKeyValues sparta::app::ReportDescriptor::header_metadata_

Metadata to include in report headers.

Definition at line 278 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 249 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()

◆ configureAsyncNonTimeseriesReport()

◆ configureAsyncTimeseriesReport()

◆ disable()

◆ 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