The Statistics class provides an interface for gathering process statistics, such as memory usage, system time, etc. More...

#include <be_process_statistics.h>

Public Member Functions
	Statistics ()
	Constructor with no parameters. More...

	Statistics (const std::shared_ptr< IO::FileLogCabinet > &logCabinet, bool doTasksLogging=false)
	Construct a Statistics object with the associated FileLogCabinet. More...

	Statistics (const std::shared_ptr< IO::Logsheet > &logSheet, std::optional< std::shared_ptr< IO::Logsheet > > tasksLogSheet=std::nullopt)
	Construct a Statistic object that logs to an existing Logsheet. More...

	~Statistics ()

std::tuple< uint64_t, uint64_t >	getCPUTimes ()
	Obtain the total user and system times for the process, in microseconds. More...

std::vector< std::tuple< pid_t, float, float > >	getTasksStats ()
	Obtain the current child tasks statistics for the process. More...

std::tuple< uint64_t, uint64_t, uint64_t, uint64_t, uint64_t >	getMemorySizes ()
	Obtain the current virtual memory (VM) set sizes for the process, in kilobytes. More...

uint32_t	getNumThreads ()
	Obtain the number of threads composing this process. More...

void	logStats ()
	Create a snapshot of the current process statistics in the FileLogsheet created in the FileLogCabinet. More...

void	startAutoLogging (uint64_t interval)
	Start logging process statistics automatically, in intervals of microseconds. More...

void	stopAutoLogging ()
	Stop the automatic logging of process statistics. More...

void	callStatistics_logStats ()
	Helper function in C++ space that has access to this object, and is called from C space by the logging thread. More...

Detailed Description

The Statistics class provides an interface for gathering process statistics, such as memory usage, system time, etc.

There are two groups of statistics: Memory and time info for the process, and system/user time for all tasks (threads) created by the process. The information gathered by objects of this class are for the current process, and can automatically be logged to a FileLogsheet object contained within the provided FileLogCabinet. The task statistics are optionally logged.

Note: The resolution of a returned value for many methods may not match the resolution allowed by the interface. For example, the operating system my allow for second resolution whereas the interface allows microsecond resolution.

Definition at line 45 of file be_process_statistics.h.

Constructor & Destructor Documentation

◆ Statistics() [1/3]

BiometricEvaluation::Process::Statistics::Statistics ( )

Constructor with no parameters.

◆ Statistics() [2/3]

BiometricEvaluation::Process::Statistics::Statistics	(	const std::shared_ptr< IO::FileLogCabinet > &	logCabinet,
		bool	doTasksLogging = `false`
	)

Construct a Statistics object with the associated FileLogCabinet.

Parameters

[in]	logCabinet	The FileLogCabinet obejct where this object will create a FileLogsheet to contain the statistic information for the process.
[in]	doTasksLogging	If true, create a second log sheet containing information for each task owned by the PID.

Exceptions

Error::NotImplemented	Logging is not supported on this OS. This exception can be thrown when any portion of the statistics gathering cannot be completed.
Error::ObjectExists	The FileLogsheet already exists. This exception should rarely, if ever, occur.
Error::StrategyError	Failure to create the FileLogsheet in the cabinet.

◆ Statistics() [3/3]

BiometricEvaluation::Process::Statistics::Statistics	(	const std::shared_ptr< IO::Logsheet > &	logSheet,
		std::optional< std::shared_ptr< IO::Logsheet > >	tasksLogSheet = `std::nullopt`
	)

Construct a Statistic object that logs to an existing Logsheet.

Parameters

[in]	logSheet	Existing Logsheet that will be appended.
	tasksLogSheet	Optional log sheet that will contain information for each task owned by the PID.

Exceptions

Error::NotImplemented Logging is not supported on this OS. This exception can be thrown when any portion of the statistics gathering cannot be completed.

◆ ~Statistics()

BiometricEvaluation::Process::Statistics::~Statistics ( )

Member Function Documentation

◆ getCPUTimes()

std::tuple< uint64_t, uint64_t > BiometricEvaluation::Process::Statistics::getCPUTimes ( )

Obtain the total user and system times for the process, in microseconds.

An example call:

 uint64_t utime, stime;
 std::tie(utime, stime) = stats.getCPUTimes();

Note: This method may not be implemented in all operating systems.

Returns: A std::tuple<> containing user time, system time.

Exceptions

Error::StrategyError	An error occurred when obtaining the process statistics from the operating system. The exception information string contains the error reason.
Error::NotImplemented	This method is not implemented on this OS.

◆ getTasksStats()

std::vector< std::tuple< pid_t, float, float > > BiometricEvaluation::Process::Statistics::getTasksStats ( )

Obtain the current child tasks statistics for the process.

The time values are in units of seconds.

An example call and processing: auto allStats = stats.getTasksStats(); for (auto [tid, utime, stime]: allStats) { cout << "TID is " << tid << " utime is " << utime << ", stime is " << stime << '
'; }

Note: This method may not be implemented in all operating systems.

Returns: A std::vector<> containing std::tuple<> elements containing Task ID, user time, system time.

Exceptions

Error::StrategyError	An error occurred when obtaining the process statistics from the operating system. The exception information string contains the error reason.
Error::NotImplemented	This method is not implemented on this OS.

◆ getMemorySizes()

std::tuple< uint64_t, uint64_t, uint64_t, uint64_t, uint64_t > BiometricEvaluation::Process::Statistics::getMemorySizes ( )

Obtain the current virtual memory (VM) set sizes for the process, in kilobytes.

An example call:

 uint64_t vmrss, vmsize, vmpeak, vmdata, vmstack;
 std::tie(vmrss, vmsize, vmpeak, vmdata, vmstack)
   = stats.getMemorySizes();

Note: This method may not be implemented in all operating systems.

Returns: A std::tuple<> containing VM resident size, VM size, VM peak, VM data size, VM stack size.

Exceptions

Error::StrategyError	An error occurred when obtaining the process statistics from the operating system. The exception information string contains the error reason.
Error::NotImplemented	This method is not implemented on this OS.

◆ getNumThreads()

uint32_t BiometricEvaluation::Process::Statistics::getNumThreads ( )

Obtain the number of threads composing this process.

Note: This method may not be implemented in all operating systems.

Exceptions

Error::StrategyError	An error occurred when obtaining the process info from the operating system. The exception information string contains the error reason.
Error::NotImplemented	This method is not implemented on this OS.

◆ logStats()

void BiometricEvaluation::Process::Statistics::logStats ( )

Create a snapshot of the current process statistics in the FileLogsheet created in the FileLogCabinet.

Exceptions

Error::ObjectDoesNotExist	The FileLogsheet does not exist; this object was not created with FileLogCabinet object.
Error::StrategyError	An error occurred when writing to the FileLogsheet.
Error::NotImplemented	The statistics gathering is not implemented for this operating system.

◆ startAutoLogging()

void BiometricEvaluation::Process::Statistics::startAutoLogging ( uint64_t interval )

Start logging process statistics automatically, in intervals of microseconds.

The first log entry will occur soon after the call to this method as the delay interval is invoked after the first entry.

Note: It is unrealistic to expect that log entries can be made at a rate of one per microsecond.; If stopAutoLogging() is called very soon after the start, a log entry may not be made.

Parameters

[in] interval The gap between logging snapshots, in microseconds.

Exceptions

Error::ObjectDoesNotExist	The FileLogsheet does not exist; this object was not created with FileLogCabinet object.
Error::ObjectExists	Autologging is currently invoked.
Error::StrategyError	An error occurred when writing to the FileLogsheet.
Error::NotImplemented	The statistics gathering is not implemented for this operating system.

◆ stopAutoLogging()

void BiometricEvaluation::Process::Statistics::stopAutoLogging ( )

Stop the automatic logging of process statistics.

Exceptions

Error::ObjectDoesNotExist	Not currently autologging.
Error::StrategyError	An error occurred when stopping, most likely because the logging thread died.

◆ callStatistics_logStats()

void BiometricEvaluation::Process::Statistics::callStatistics_logStats ( )

Helper function in C++ space that has access to this object, and is called from C space by the logging thread.

Applications should not call this function.

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

be_process_statistics.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Statistics() [1/3]

◆ Statistics() [2/3]

◆ Statistics() [3/3]

◆ ~Statistics()

Member Function Documentation

◆ getCPUTimes()

◆ getTasksStats()

◆ getMemorySizes()

◆ getNumThreads()

◆ logStats()

◆ startAutoLogging()

◆ stopAutoLogging()

◆ callStatistics_logStats()