profiling::TimedRegion Class Reference

Scope guard that records wall clock time elapsed and marks region beginning and end by writing to a given output stream. More...

#include <TimedRegion.hpp>

Public Types
enum class	Mode { REGION , SUBREGION }
	In Mode::REGION, TimedRegion must be used as a scope guard. More...

Public Member Functions
	TimedRegion (const char *aRegionLabel, Mode aMode=Mode::REGION, std::function< void(ut::log::MessageStream &)> aExtraStartingOutputFunc=nullptr, ut::log::MessageStream aOutputStream=ut::log::info())
	~TimedRegion ()
void	StartSubregion (const std::string &aStartMessage="")
	Logs a start message for a subregion and sets the time offset members with the current cpu and wall time.
void	StopSubregion (const std::string &aEndMessage="")
	Logs an end message containing cpu and wall time values for a subregion.
double	GetWallTime ()
	Returns the elapsed wall time since the last time its offsets was set.
double	GetCpuTime ()
	Returns the elapsed cpu time since the last time its offsets was set.
	TimedRegion ()=delete
	TimedRegion (const TimedRegion &)=delete
TimedRegion &	operator= (const TimedRegion &)=delete
	TimedRegion (TimedRegion &&)=delete
TimedRegion &	operator= (TimedRegion &&)=delete

Detailed Description

Scope guard that records wall clock time elapsed and marks region beginning and end by writing to a given output stream.

It owns one internal ProfilingRegion which uses the same region label as the given label. It is subject to all caveats and restrictions as ProfilingRegion.

Timing regions may be nested in Mode::REGION. TimedRegion instances should never be handled by pointer or passed as arguments to functions.

Example usage (Mode::REGION):

void InnerFunction() {
   TimedRegion r("Recording InnerFunction");
   ComputeOtherStuff();
}
void OuterFunction() {
   TimedRegion r("Recording OuterFunction");
   ComputeStuff();
   InnerFunction();
}

This results in the following logged output (with fake time values): Recording OuterFunction. Recording InnerFunction. Recording InnerFunction complete. Elapsed Wall Clock Time: 0.238954 Elapsed Processor Time : 0.15625 Recording OuterFunction complete. Elapsed Wall Clock Time: 3.92168 Elapsed Processor Time : 4.07812

Example usage (Mode::SUBREGION):

void Function() {
   TimedRegion r("A, B, and C", Mode::SUBREGION);
 
   r.StartSubregion("starting A and B");
   DoA();
   DoB();
   r.LogCurrentSubregion("finished A and B");
 
   r.StartSubregion("starting C");
   DoC();
   r.LogCurrentSubregion("finished C");
}

This results in the following logged output (with fake time values): starting A and B. finished A and B. Elapsed Wall Clock Time: 2.248954 Elapsed Processor Time : 2.25625 starting C. finished C. Elapsed Wall Clock Time: 0.92168 Elapsed Processor Time : 1.07812

Member Enumeration Documentation

Mode

enum class profiling::TimedRegion::Mode

strong

In Mode::REGION, TimedRegion must be used as a scope guard.

Logging information is automatically produced on construction and destruction of the TimedRegion object. In Mode::SUBREGION, TimedRegion must be used as a stopwatch, using @ StartSubregion and @ StopSubregion to produce logging output. Mode::SUBREGION is required if logging must occur within nested scopes, such as conditional statements, or if runtime generated information must be included as part of the logged output.

Enumerator
REGION	Use TimedRegion like scope guard. Regions may be nested.
SUBREGION	Use TimedRegion like stopwatch. Subregions must be disjoint.

Constructor & Destructor Documentation

TimedRegion() [1/4]

profiling::TimedRegion::TimedRegion	(	const char *	aRegionLabel,
		Mode	aMode = Mode::REGION,
		std::function< void(ut::log::MessageStream &)>	aExtraStartingOutputFunc = nullptr,
		ut::log::MessageStream	aOutputStream = ut::log::info() )

Parameters

aRegionLabel	Label used when writing to outputStream and logs to the loaded profiling library.
aMode	Flag which sets the behavior of TimedRegion to REGION/SUBREGION logging for its lifespan.
aExtraStartingOutputFunc	Callable object used for custom output on region initialization.
aOutputStream	Stream to which to write messages. Use this when a different logging level is needed, such as ut::log::debug().

References REGION.

Referenced by operator=(), operator=(), TimedRegion(), and TimedRegion().

~TimedRegion()

profiling::TimedRegion::~TimedRegion

(

)

Do nothing intentionally

References REGION.

TimedRegion() [2/4]

profiling::TimedRegion::TimedRegion ( )

delete

TimedRegion() [3/4]

profiling::TimedRegion::TimedRegion ( const TimedRegion & )

delete

References TimedRegion().

TimedRegion() [4/4]

profiling::TimedRegion::TimedRegion ( TimedRegion && )

delete

References TimedRegion().

Member Function Documentation

GetCpuTime()

double profiling::TimedRegion::GetCpuTime

(

)

Returns the elapsed cpu time since the last time its offsets was set.

Referenced by WsfStandardApplication::RunEventLoop().

GetWallTime()

double profiling::TimedRegion::GetWallTime

(

)

Returns the elapsed wall time since the last time its offsets was set.

Referenced by WsfStandardApplication::RunEventLoop().

operator=() [1/2]

TimedRegion & profiling::TimedRegion::operator= ( const TimedRegion & )

delete

References TimedRegion().

operator=() [2/2]

TimedRegion & profiling::TimedRegion::operator= ( TimedRegion && )

delete

References TimedRegion().

StartSubregion()

void profiling::TimedRegion::StartSubregion

(

const std::string &

aStartMessage = ""

)

Logs a start message for a subregion and sets the time offset members with the current cpu and wall time.

If profiling is enabled, will begin a ProfilingRegion. (Mode::SUBREGION only)

NOTE: Subregions must be disjointed. Calling this method while a subregion is active will close the active ProfilingRegion and emit a warning message.

Parameters

aStartMessage

Added to the start output message. If left empty, mRegionLabel will be used in its place.

References SUBREGION.

Referenced by WsfStandardApplication::RunEventLoop().

StopSubregion()

void profiling::TimedRegion::StopSubregion

(

const std::string &

aEndMessage = ""

)

Logs an end message containing cpu and wall time values for a subregion.

If profiling is enabled, will end an active ProfilingRegion. (Mode::SUBREGION only)

NOTE: It is legal to call this method without an active subregion. The elapsed cpu and wall time since the last time their offsets were set will be used.

Parameters

aEndMessage

Added to the end output message. If left empty, mRegionLabel + " complete." will be used in its place.

References SUBREGION.

Referenced by WsfStandardApplication::RunEventLoop().

---

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

• TimedRegion.hpp
• TimedRegion.cpp