Description

This class provides access to profiler measurements.

It parses XML export file and returns the parsed data through method calls. Since profiler export files may be very large - hundreds of megabytes or even gigabytes, this class parses one time-line item per iterator function call.

To get instance of this class call one of createInstance() factory methods.

Profiler data consists of three groups:

areas contain information about item, which was profiled: function name, variable name, variable value, source line, ... Each area also has an identifier value called handle. Information for area is stored in class CProfilerArea2.
statistics group contains statistics (min, max, average) of measurements for areas. In general each area has its statistics item. If there are more execution contexts, statistics is measured for each of them. Information for statistics is stored in class CProfilerStatistics2.
time-line group contains events for areas as they have happened during recording. Each time-line event contains time stamp and handle, among other data. The handle identifies the area, for which the event was recorded. Information for time-line events is stored in class CProfilerTimeEvent.

Items in all groups are identified by handles.

#include <CProfilerData2.h>

Public Member Functions
std::string	getParserWarnings ()
	This method returns warnings related to input XML document. More...

void	closeParser ()
	This method releases parser resources and closes XML file. More...

uint64_t	getBinTimelineEventSize ()
	Returns number of bytes for one event in profiler binary timeline. More...

size_t	getBinTimelineFileSize ()
	Returns size of file containing binary timeline. More...

int64_t	getTotalSessionTimeNs ()
	Returns total session time in nanoseconds. More...

CProfilerContextIterator	getContextIterator ()

CProfilerAreaIterator	getAreaIterator (CProfilerArea2::EAreaType areaType)
	Returns iterator for areas. More...

CProfilerArea2	getArea (areaHandle_t id)
	Returns profiler area for the given id. More...

CProfilerArea2	getArea (const std::string &areaQName)
	Returns profiler area for the given qualified area name. More...

bool	hasArea (const std::string &areaQName)
	Returns true, if the given area exists in profiler recording. More...

bool	hasArea (CProfilerArea2::EAreaType areaType, const std::string &areaName)

CProfilerArea2	getArea (CProfilerArea2::EAreaType areaType, const std::string &areaName)

CProfilerArea2	getArea (CProfilerArea2::EAreaType areaType, const std::string &areaPath, int64_t valueOrLineNumber)
	Returns profiler state area for the given type, parent name and state value. More...

CProfilerArea2	getArea (CProfilerArea2::EAreaType areaType, const std::string &areaPath, const std::string &stateAreaName)

CProfilerArea2	getArea (const std::string &areaPath, int64_t valueOrLineNumber)
	Returns state area for the given value. More...

bool	hasStatisticsForArea (areaHandle_t id)
	Returns true, if statistics for the given area exists. More...

bool	hasStatisticsForArea (const std::string &areaQName)
	Returns true, if statistics for the given area exists. More...

CProfilerStatistics2	getStatistics (areaHandle_t id)
	Returns statistics for the specified area Id. More...

CProfilerStatistics2	getStatistics (const std::string &areaQName)
	Returns statistics for the specified qualified area name. More...

bool	hasStatisticsForArea (CProfilerArea2::EAreaType areaType, const std::string &areaName)

CProfilerStatistics2	getStatistics (CProfilerArea2::EAreaType areaType, const std::string &areaName)

bool	hasStatisticsForStateArea (CProfilerArea2::EAreaType areaType, const std::string &parentAreaName, int64_t value)

bool	hasStatisticsForStateArea (const std::string &areaPath, int64_t value)
	Returns true, if statistics for the given state area exists. More...

CProfilerStatistics2	getStatistics (CProfilerArea2::EAreaType areaType, const std::string &parentAreaName, int64_t value)

CProfilerStatistics2	getStatistics (const std::string &areaPath, int64_t value)
	Returns statistics for the specified state area. More...

bool	hasStatisticsForFunction (areaHandle_t id, const std::string &contextName)
	Returns true, if the specified area was recorded in the specified context. More...

CProfilerStatistics2	getStatisticsForFunction (areaHandle_t id, const std::string &contextName)
	Returns statistics for the specified function area Id and context. More...

bool	hasStatisticsForFunction (CProfilerArea2::EAreaType areaType, const std::string &areaName, const std::string &contextName)
	Returns true, if the specified area was recorded in the specified context. More...

CProfilerStatistics2	getStatisticsForFunction (CProfilerArea2::EAreaType areaType, const std::string &areaName, const std::string &contextName)
	Returns statistics for the specified function area and context. More...

void	getContexts (iconnect::StrVector &contexts)
	Fills the given list with all contexts found in profiler results. More...

CProfilerTimelineIterator	getTimelineIterator (CProfilerTimeEvent::EEventType eventType=CProfilerTimeEvent::EEvAny)
	Returns iterator, which will iterate all time-line events of the given type. More...

CProfilerTimelineIterator	getTimelineIterator (CProfilerTimeEvent::EEventType eventType, DWORD handle)
	Returns iterator, which will iterate time-line events for area with the given handle. More...

CProfilerTimelineIterator	getTimelineIterator (CProfilerTimeEvent::EEventType eventType, DWORD handle, int64_t value)
	Returns iterator, which will iterate time-line events for state area with the given handle and value. More...

Static Public Member Functions
static CProfilerData2SPtr	createInstance (isys::CProfilerController2SPtr profilerCtrl, const std::string &exportFileName, bool isTimeline, const std::string &funcAreaNames, const std::string &dataAreaNames)
	This factory method exports data to file, then parses statistics information, and returns initialized object. More...

static CProfilerData2SPtr	createInstance (isys::CProfilerController2SPtr profilerCtrl, const std::string &exportFileName, bool isTimeline, const std::string &funcAreaNames, const std::string &dataAreaNames, isys::CProfilerExportConfig::EExportPartitionNameMode exportPNameMode)

static CProfilerData2SPtr	createInstance (const std::string &fileName, bool isBinaryTimeline=false)
	This factory method parses statistic information from profiler XML export file and returns initialized object. More...

Member Function Documentation

◆ closeParser()

void isys::CProfilerData2::closeParser ( )

This method releases parser resources and closes XML file.

It is recommended to call this method always after CProfilerTimelineIterator is no longer used. It must be called always when there is time-line data available, but we didn't fetch all time-line items (CProfilerTimelineIterator.hasNext() did not return false). Otherwise the XML file remains opened and can not be ovewritten or deleted until the application exits.

Python example: test_create_close_instance.py

◆ createInstance() [1/3]

static CProfilerData2SPtr isys::CProfilerData2::createInstance	(	const std::string &	fileName,
		bool	isBinaryTimeline = `false`
	)

static

This factory method parses statistic information from profiler XML export file and returns initialized object.

Parameters

fileName	name of the file with profiler XML export. If you use relative file path, be aware that script working directory is used as a starting point, not winIDEA workspace directory.
isBinaryTimeline	if true, time-line data is read from binary file. Set this parameter to true when export file was created with CProfilerXMLExportFormat::setTimelineBinary(true).

Python example: test_has_area.py

◆ createInstance() [2/3]

static CProfilerData2SPtr isys::CProfilerData2::createInstance	(	isys::CProfilerController2SPtr	profilerCtrl,
		const std::string &	exportFileName,
		bool	isTimeline,
		const std::string &	funcAreaNames,
		const std::string &	dataAreaNames
	)

static

This factory method exports data to file, then parses statistics information, and returns initialized object.

Use it, when you've just recorded data (have CProfilerController2 object available), and have not exported it yet. Note also that this method is not as flexible as direct export and method createInstance(fileName, isBinaryTimeline).

Note: if exportFileName is relative, it is saved relative to the workspace directory, not the script working directory. This method tries to do its best to open the saved file, but if winIDEA is on remote host, it will fail. In such cases try to export the profiler data with CProfilerController2::exportData() and use the overloaded method createInstance(fileName) instead.

Parameters

profilerCtrl	profiler document controller which will be used to obtain data.
exportFileName	name of the file to export data to
isTimeline	if true, time-line is also exported. Note that this may produce very large files in terms of gigabytes, so use it only when needed.
funcAreaNames	contains function areas separated by spaces to be exported. If '*' is specified, all function areas are exported. If empty, no function areas are exported.
dataAreaNames	contains data areas separated by spaces to be exported. If '*' is specified, all data areas are exported. If empty, no data areas are exported.

Python example: test_has_area.py

◆ createInstance() [3/3]

static CProfilerData2SPtr isys::CProfilerData2::createInstance	(	isys::CProfilerController2SPtr	profilerCtrl,
		const std::string &	exportFileName,
		bool	isTimeline,
		const std::string &	funcAreaNames,
		const std::string &	dataAreaNames,
		isys::CProfilerExportConfig::EExportPartitionNameMode	exportPNameMode
	)

static

See also: createInstance(isys::CProfilerController2SPtr, const std::string &, bool, const std::string &, const std::string &) for description.

Parameters

profilerCtrl	profiler document controller which will be used to obtain data.
exportFileName	name of the file to export data to
isTimeline	if true, time-line is also exported. Note that this may produce very large files in terms of gigabytes, so use it only when needed.
funcAreaNames	contains function areas separated by spaces to be exported. If '*' is specified, all function areas are exported. If empty, no function areas are exported.
dataAreaNames	contains data areas separated by spaces to be exported. If '*' is specified, all data areas are exported. If empty, no data areas are exported.
exportPNameMode	defines if download file name is appended to area names or not

◆ getArea() [1/6]

CProfilerArea2 isys::CProfilerData2::getArea ( areaHandle_t id )

Returns profiler area for the given id.

Python example: test_get_area.py

◆ getArea() [2/6]

CProfilerArea2 isys::CProfilerData2::getArea	(	const std::string &	areaPath,
		int64_t	valueOrLineNumber
	)

Returns state area for the given value.

Parameters

areaPath	path to area without area name, for example name of the state variable or function.
valueOrLineNumber	value for state variables, line number for lines

Python example: test_get_area.py

◆ getArea() [3/6]

CProfilerArea2 isys::CProfilerData2::getArea ( const std::string & areaQName )

Returns profiler area for the given qualified area name.

Parameters

areaQName qualified area name consisting of path and name.

Python example: test_get_area.py

◆ getArea() [4/6]

CProfilerArea2 isys::CProfilerData2::getArea	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaName
	)

Deprecated:: if there is more than one area with the same name, this method returns the first one only. Use getArea(string areaQName) instead.

Returns area of the given type and with the given name. If areaType is EStateVariables or EStateAUX, then area of the first value detected is returned.

Parameters

areaType	area type
areaName	function, variable or AUX name with full path. If area type is EStateVariables, or EStateAUX, then areaName is taken from type definition in recording. If the definition is not set, name of state var is empty and we can not search for it. Use getArea(EAreaType, std::string, DWORD) in such case. See also CProfilerController2::addStateVariable().

◆ getArea() [5/6]

CProfilerArea2 isys::CProfilerData2::getArea	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaPath,
		const std::string &	stateAreaName
	)

Deprecated:: if there is more than one area with the same name, this method returns the first one only. Use getArea(string areaQName) instead.

Returns profiler state area for the given type, parent name and state name.

Parameters

areaType	may be EStateVariables, or EStateAUX
areaPath	path to area without area name, for example name of the state variable or function.
stateAreaName	name of enum state value or function line number source code

◆ getArea() [6/6]

CProfilerArea2 isys::CProfilerData2::getArea	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaPath,
		int64_t	valueOrLineNumber
	)

Returns profiler state area for the given type, parent name and state value.

Parameters

areaType	may be EStateVariables, or EStateAUX
areaPath	path to area without area name, for example name of the state variable or function.
valueOrLineNumber	value of the state variable or function line number

Python example: test_get_area.py

◆ getAreaIterator()

CProfilerAreaIterator isys::CProfilerData2::getAreaIterator ( CProfilerArea2::EAreaType areaType )

Returns iterator for areas.

Use this method to get all recorded areas.

Python example: test_get_area_iterator.py

◆ getBinTimelineEventSize()

uint64_t isys::CProfilerData2::getBinTimelineEventSize ( )

Returns number of bytes for one event in profiler binary timeline.

This value can be used to get the number of events in timeline, if you know the size of binary timeline file. Python example: test_bin_timeline.py

◆ getBinTimelineFileSize()

size_t isys::CProfilerData2::getBinTimelineFileSize ( )

Returns size of file containing binary timeline.

If timeline is defined in XML, not in binary file, IllegalStateException is thrown. Python example: test_bin_timeline.py

◆ getContextIterator()

CProfilerContextIterator isys::CProfilerData2::getContextIterator ( )

Deprecated:: this method will be removed or changed in one of future releases

Returns iterator for contexts. Use this method to get all recorded contexts (tasks, threads, ISRs, ...).

◆ getContexts()

void isys::CProfilerData2::getContexts ( iconnect::StrVector & contexts )

Fills the given list with all contexts found in profiler results.

Parameters

contexts vector of strings to receive contexts.

Python example: test_get_contexts.py

◆ getParserWarnings()

std::string isys::CProfilerData2::getParserWarnings ( )

This method returns warnings related to input XML document.

If there were no warnings, an empty string is returned. Always call this method after createInstance(). If XML document is made with newer version of winIDEA than SDK, it will warn you about possible missing info.

Python example: test_get_parser_warnings.py

◆ getStatistics() [1/5]

CProfilerStatistics2 isys::CProfilerData2::getStatistics ( areaHandle_t id )

Returns statistics for the specified area Id.

If it is function area, then this method returns statistics for context 'Neutral', if it exists. If it does not exist, an exception is thrown. For other contexts use method getStatistics(id, contextName).

Parameters

id	area ID. Use `getArea(type, funcOrVarName).getAreaId()` to get the ID.

Python example: test_get_statistics.py

◆ getStatistics() [2/5]

CProfilerStatistics2 isys::CProfilerData2::getStatistics	(	const std::string &	areaPath,
		int64_t	value
	)

Returns statistics for the specified state area.

This is a convenience method - for best performance use getStatistics(id).

Parameters

areaPath	path to area without area name
value	value of the state variable to get statistics for

Python example: test_get_statistics.py

◆ getStatistics() [3/5]

CProfilerStatistics2 isys::CProfilerData2::getStatistics ( const std::string & areaQName )

Returns statistics for the specified qualified area name.

Parameters

areaQName qualified area name consisting of path and name.

Python example: test_get_statistics.py

◆ getStatistics() [4/5]

CProfilerStatistics2 isys::CProfilerData2::getStatistics	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaName
	)

Deprecated:: if there is more than one area with the same name, this method returns stats for the first one only. Use getStatistics(string areaQName) instead.

Returns statistics for the specified function or variable area. This is a convenience method - for best performance use getStatistics(id).

Parameters

areaType	area type
areaName	qualified area name, which includes path and area name (for example name of function or variable).

Python example: test_get_statistics.py

◆ getStatistics() [5/5]

CProfilerStatistics2 isys::CProfilerData2::getStatistics	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	parentAreaName,
		int64_t	value
	)

Deprecated:: use getStatistics(const std::string &areaPath, int64_t value); instead. Returns statistics for the specified state area. This is a convenience method - for best performance use getStatistics(id).

Parameters

areaType	are type may be EStateVariables, or EStateAUX
parentAreaName	path to area without area name
value	value of the state variable to get statistics for

◆ getStatisticsForFunction() [1/2]

CProfilerStatistics2 isys::CProfilerData2::getStatisticsForFunction	(	areaHandle_t	id,
		const std::string &	contextName
	)

Returns statistics for the specified function area Id and context.

Use this method when profiler data was exported with context set to 'All' or 'Current' (see CProfilerExportConfig::setContextScope()). If profiler data was exported with context 'Neutral', then specify 'Neutral' as context name or use method getStatistics(id).

Parameters

id	area ID. Use `getArea(type, funcOrVarName).getAreaId()` to get the ID.
contextName	name of the context.

Python example: test_get_statistics_for_function.py

◆ getStatisticsForFunction() [2/2]

CProfilerStatistics2 isys::CProfilerData2::getStatisticsForFunction	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaName,
		const std::string &	contextName
	)

Returns statistics for the specified function area and context.

Use this method when profiler data was exported with context set to 'All' or 'Current' (see CProfilerExportConfig::setContextScope()). If profiler data was exported with context 'Neutral', then specify 'Neutral' as context name or use method getStatistics(id).

Parameters

areaType	area type must be EFunctions. EFunctionLines is deprecated since 9.17.36.
areaName	name of function
contextName	name of the context.

Python example: test_get_statistics_for_function.py

◆ getTimelineIterator() [1/3]

CProfilerTimelineIterator isys::CProfilerData2::getTimelineIterator	(	CProfilerTimeEvent::EEventType	eventType,
		DWORD	handle
	)

Returns iterator, which will iterate time-line events for area with the given handle.

Python example: test_get_timeline_iterator.py

◆ getTimelineIterator() [2/3]

CProfilerTimelineIterator isys::CProfilerData2::getTimelineIterator	(	CProfilerTimeEvent::EEventType	eventType,
		DWORD	handle,
		int64_t	value
	)

Returns iterator, which will iterate time-line events for state area with the given handle and value.

Python example: test_get_timeline_iterator.py

◆ getTimelineIterator() [3/3]

CProfilerTimelineIterator isys::CProfilerData2::getTimelineIterator ( CProfilerTimeEvent::EEventType eventType = CProfilerTimeEvent::EEvAny )

Returns iterator, which will iterate all time-line events of the given type.

Python example: test_get_timeline_iterator.py

◆ getTotalSessionTimeNs()

int64_t isys::CProfilerData2::getTotalSessionTimeNs ( )

Returns total session time in nanoseconds.

Python example: test_get_total_session_time_ns.py

◆ hasArea() [1/2]

bool isys::CProfilerData2::hasArea ( const std::string & areaQName )

Returns true, if the given area exists in profiler recording.

Parameters

areaQName qualified area name consisting of path and name.

Python example: test_has_area.py

◆ hasArea() [2/2]

bool isys::CProfilerData2::hasArea	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaName
	)

Deprecated:: Use hasArea(string areaQName) instead.

Returns true, if the given area exists in profiler recording.

Parameters

areaType	area type
areaName	function, variable or AUX name with full path. If area type is EStateVariables, or EStateAUX, then areaName is taken from type definition in recording. If the definition is not set, name of state var is empty and we can not search for it. Use getArea(EAreaType, std::string, DWORD) in such case. See also CProfilerController2::addStateVariable().

◆ hasStatisticsForArea() [1/3]

bool isys::CProfilerData2::hasStatisticsForArea ( areaHandle_t id )

Returns true, if statistics for the given area exists.

Python example: test_has_statistics_for_area.py

◆ hasStatisticsForArea() [2/3]

bool isys::CProfilerData2::hasStatisticsForArea ( const std::string & areaQName )

Returns true, if statistics for the given area exists.

Parameters

areaQName qualified area name consisting of path and name.

Python example: test_has_statistics_for_area.py

◆ hasStatisticsForArea() [3/3]

bool isys::CProfilerData2::hasStatisticsForArea	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaName
	)

Deprecated:: Use hasStatisticsForArea(string areaQName) instead.

Returns true, if statistics for the given area exists.

Parameters

areaType	area type
areaName	qualified area name, which includes path and area name (for example name of function or variable).

◆ hasStatisticsForFunction() [1/2]

bool isys::CProfilerData2::hasStatisticsForFunction	(	areaHandle_t	id,
		const std::string &	contextName
	)

Returns true, if the specified area was recorded in the specified context.

Parameters

id	area ID. Use `getArea(type, funcOrVarName).getAreaId()` to get the ID.
contextName	name of the context.

Exceptions

IllegalArgumentException if area with the given ID does not exist.

Python example: test_has_statistics_for_function.py

◆ hasStatisticsForFunction() [2/2]

bool isys::CProfilerData2::hasStatisticsForFunction	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	areaName,
		const std::string &	contextName
	)

Returns true, if the specified area was recorded in the specified context.

Parameters

areaType	area type must be EFunctions. EFunctionLines is deprecated since 9.17.36.
areaName	name of function
contextName	name of the context.

Exceptions

IllegalArgumentException if area with the given type and name does not exist.

Python example: test_has_statistics_for_function.py

◆ hasStatisticsForStateArea() [1/2]

bool isys::CProfilerData2::hasStatisticsForStateArea	(	const std::string &	areaPath,
		int64_t	value
	)

Returns true, if statistics for the given state area exists.

Parameters

areaPath	path to area, without area name
value	state value

Python example: test_has_statistics_for_state_area.py

◆ hasStatisticsForStateArea() [2/2]

bool isys::CProfilerData2::hasStatisticsForStateArea	(	CProfilerArea2::EAreaType	areaType,
		const std::string &	parentAreaName,
		int64_t	value
	)

Deprecated:: use hasStatisticsForStateArea(const std::string &areaPath, int64_t value)

Returns true, if statistics for the given state area exists.

Parameters

areaType	type of area
parentAreaName	name of parent area
value	state value

Description

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ closeParser()

◆ createInstance() [1/3]

◆ createInstance() [2/3]

◆ createInstance() [3/3]

◆ getArea() [1/6]

◆ getArea() [2/6]

◆ getArea() [3/6]

◆ getArea() [4/6]

◆ getArea() [5/6]

◆ getArea() [6/6]

◆ getAreaIterator()

◆ getBinTimelineEventSize()

◆ getBinTimelineFileSize()

◆ getContextIterator()

◆ getContexts()

◆ getParserWarnings()

◆ getStatistics() [1/5]

◆ getStatistics() [2/5]

◆ getStatistics() [3/5]

◆ getStatistics() [4/5]

◆ getStatistics() [5/5]

◆ getStatisticsForFunction() [1/2]

◆ getStatisticsForFunction() [2/2]

◆ getTimelineIterator() [1/3]

◆ getTimelineIterator() [2/3]

◆ getTimelineIterator() [3/3]

◆ getTotalSessionTimeNs()

◆ hasArea() [1/2]

◆ hasArea() [2/2]

◆ hasStatisticsForArea() [1/3]

◆ hasStatisticsForArea() [2/3]

◆ hasStatisticsForArea() [3/3]

◆ hasStatisticsForFunction() [1/2]

◆ hasStatisticsForFunction() [2/2]

◆ hasStatisticsForStateArea() [1/2]

◆ hasStatisticsForStateArea() [2/2]