orb5x::profiler Namespace Reference

Profiling facilities implemented by the profiler module. More...

Functions
void	profiler_add_region_time (const std::string &region_name, double seconds, long long calls=1)
	Add an externally measured sample to window and cumulative totals.
void	profiler_begin_region_impl (const char *region_name, const char *file, int line)
	Begin profiling for a specific region.
void	profiler_begin_region_species_impl (int isp, const char *file, int line)
	Open a subregion for a specific species.
void	profiler_end_region (const char *region_name)
	End profiling for a specific region.
void	profiler_end_region_species (int isp)
	Close a subregion for a specific species.
void	profiler_off ()
	Deactivate the profiling.
void	profiler_on ()
	Activate the profiling (ON by default)
void	profiler_print_summary (const std::string &label)
	Print current-window regions in descending elapsed-time order.
void	profiler_reset_summary ()
	Reset wall-clock totals for the current reporting window.
void	profiler_write_summary_file (const std::string &label)
	Write the top cumulative regions to a per-rank text file.

Detailed Description

Profiling facilities implemented by the profiler module.

Named-region profiling and process-local wall-clock summaries.

Author

Emmanuel Lanti (original Fortran), C++ conversion

Date

04/2017 (original), 2024 (C++ conversion)

The namespace optionally emits Score-P regions and independently accumulates thread-safe process-local wall-clock statistics. Built-in summaries are controlled by ORB5X_PROFILE_SUMMARY (or the CMake default). File output can be tuned with ORB5X_PROFILE_WRITE_FILE, ORB5X_PROFILE_TOP_N, ORB5X_PROFILE_FILE_PREFIX, and ORB5X_PROFILE_OUTPUT_DIR. Timings are not reduced across MPI ranks.

Function Documentation

profiler_add_region_time()

void orb5x::profiler::profiler_add_region_time	(	const std::string &	region_name,
		double	seconds,
		long long	calls = 1
	)

Add an externally measured sample to window and cumulative totals.

Parameters

[in]	region_name	Region receiving the sample.
[in]	seconds	Positive elapsed wall-clock time in seconds.
[in]	calls	Positive number of calls represented by the sample.

Note

Non-positive times or call counts are ignored.

profiler_begin_region_impl()

void orb5x::profiler::profiler_begin_region_impl	(	const char *	region_name,
		const char *	file,
		int	line
	)

Begin profiling for a specific region.

Parameters

[in]	region_name	Non-empty name of the region to profile.
[in]	file	Source-file name supplied by the profiling macro.
[in]	line	Source line supplied by the profiling macro.

Opens a new region of code to profile. If this routine is called several times with the same region_name, the timings will be combined. When Score-P is not available, this function does nothing.

profiler_begin_region_species_impl()

void orb5x::profiler::profiler_begin_region_species_impl	(	int	isp,
		const char *	file,
		int	line
	)

Open a subregion for a specific species.

Parameters

[in]	isp	Species number embedded in the name Species N.
[in]	file	Source-file name supplied by the profiling macro.
[in]	line	Source line supplied by the profiling macro.

Creates a region name "Species N" and begins profiling for it. When Score-P is not available, this function does nothing.

profiler_end_region()

void orb5x::profiler::profiler_end_region

(

const char *

region_name

)

End profiling for a specific region.

Parameters

[in]

region_name

Name passed to the matching begin call.

Closes a profiling region. When Score-P is not available, this function does nothing.

profiler_end_region_species()

void orb5x::profiler::profiler_end_region_species

(

int

isp

)

Close a subregion for a specific species.

Parameters

[in]

isp

Species number used by the matching begin call.

Ends profiling for the region "Species N". When Score-P is not available, this function does nothing.

profiler_off()

void orb5x::profiler::profiler_off

(

)

Deactivate the profiling.

Disables Score-P recording if Score-P is available

profiler_on()

void orb5x::profiler::profiler_on

(

)

Activate the profiling (ON by default)

Enables Score-P recording if Score-P is available

profiler_print_summary()

void orb5x::profiler::profiler_print_summary

(

const std::string &

label

)

Print current-window regions in descending elapsed-time order.

Parameters

[in]

label

Heading identifying the reporting window.

Note

Times are process-local seconds and nested regions may overlap.

profiler_reset_summary()

void orb5x::profiler::profiler_reset_summary

(

)

Reset wall-clock totals for the current reporting window.

Note

Whole-run cumulative totals and currently active region stacks remain.

profiler_write_summary_file()

void orb5x::profiler::profiler_write_summary_file

(

const std::string &

label

)

Write the top cumulative regions to a per-rank text file.

Parameters

[in]

label

Run or phase label recorded in the file header.

The default path is profiling/orb5x_profile_rankNNNN.txt. Existing files for the same rank are replaced. Percentages use the sum of recorded region times, so nested-region overlap is intentionally not removed.