cs_timer_stats.c File Reference

#include "cs_config.h"
#include "cs_defs.h"
#include <math.h>
#include <string.h>
#include <time.h>
#include "bft_error.h"
#include "bft_mem.h"
#include "cs_map.h"
#include "cs_timer.h"
#include "cs_time_plot.h"
#include "cs_timer_stats.h"

Include dependency graph for cs_timer_stats.c:

Macros
#define	_POSIX_C_SOURCE   200112L

Functions
void	cs_timer_stats_initialize (void)
	Initialize timer statistics handling. More...
void	cs_timer_stats_finalize (void)
	Finalize timer statistics handling. More...
void	cs_timer_stats_set_start_time (int time_id)
	Set a start time for time stats. More...
void	cs_timer_stats_set_plot_options (cs_time_plot_format_t format, int frequency, int n_buffer_steps, double flush_wtime)
	Set global timer statistics plot options. More...
void	cs_timer_stats_increment_time_step (void)
	Increment time step for timer statistics. More...
int	cs_timer_stats_create (const char *parent_name, const char *name, const char *label)
	Create a timer statistics structure. More...
int	cs_timer_stats_id_by_name (const char *name)
	Return the id of a defined statistic based on its name. More...
void	cs_timer_stats_set_plot (int id, int plot)
	Enable or disable plotting for a timer statistic. More...
int	cs_timer_stats_is_active (int id)
	indicate if a timer for a given statistic is currently active. More...
void	cs_timer_stats_start (int id)
	Start a timer for a given statistic. More...
void	cs_timer_stats_stop (int id)
	Stop a timer for a given statistic. More...
int	cs_timer_stats_switch (int id)
	Start a timer for a given statistic, stopping previous timers of the same type which are not a parent, and starting inactive parent timers if necessary. More...
void	cs_timer_stats_add_diff (int id, const cs_timer_t *t0, const cs_timer_t *t1)
	Add a timing range to an inactive timer. More...
void	cs_timer_stats_define_defaults (void)
	Define default timer statistics. More...

Detailed Description

Application timer statistics and graphs.

These statistics are intended to provide a synthetic view of the relative costs of various operations and stages, and are defined as sets of trees so as to allow a form of grouping.

This logic does not replace having specific timers for operators, which allow for more detail, but more difficult to provide an overview for. Timer statistics also allow for incrementing results from base timers (in addition to starting/stopping their own timers), so they may be used to assist logging and plotting of other timers.

Macro Definition Documentation

_POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200112L

Function Documentation

cs_timer_stats_add_diff()

void cs_timer_stats_add_diff	(	int	id,
		const cs_timer_t *	t0,
		const cs_timer_t *	t1
	)

Add a timing range to an inactive timer.

This does not modify parent timers, so consistency of active and inactive timers must be ensured by the caller.

Parameters

[in]	id	id of statistic
[in]	t0	oldest timer value
[in]	t1	most recent timer value

cs_timer_stats_create()

int cs_timer_stats_create	(	const char *	parent_name,
		const char *	name,
		const char *	label
	)

Create a timer statistics structure.

Parameters

[in]	parent_name	name of parent statistic, or NULL
[in]	name	associated canonical name
[in]	label	associated label, or NULL

Returns

id of new timer stats structure

cs_timer_stats_define_defaults()

void cs_timer_stats_define_defaults

(

void

)

Define default timer statistics.

This creates 2 statistic timer trees, whose roots ids are:

• 0 for computational operations
• 1 for computational stages

cs_timer_stats_finalize()

void cs_timer_stats_finalize

(

void

)

Finalize timer statistics handling.

cs_timer_stats_id_by_name()

int cs_timer_stats_id_by_name

(

const char *

name

)

Return the id of a defined statistic based on its name.

If no timer with the given name exists, -1 is returned.

Parameters

[in]

name

statitic name

Returns

id of the statistic, or -1 if not found

cs_timer_stats_increment_time_step()

void cs_timer_stats_increment_time_step

(

void

)

Increment time step for timer statistics.

cs_timer_stats_initialize()

void cs_timer_stats_initialize

(

void

)

Initialize timer statistics handling.

This creates 2 statistic timer trees, whose roots ids are:

• 0 for computational operations
• 1 for computational stages

cs_timer_stats_is_active()

int cs_timer_stats_is_active

(

int

id

)

indicate if a timer for a given statistic is currently active.

Parameters

[in]

id

id of statistic

Returns

1 if active, 0 otherwise

cs_timer_stats_set_plot()

void cs_timer_stats_set_plot	(	int	id,
		int	plot
	)

Enable or disable plotting for a timer statistic.

By default plotting is enabled for all statistics, except root statistic 1 (as it measures the same total time as root 0, with a different subtree).

This function is only effective before the first call to cs_timer_stats_increment_time_step.

Parameters

[in]	id	id of statistic
[in]	plot	0 to disable, 1 to enable

cs_timer_stats_set_plot_options()

void cs_timer_stats_set_plot_options	(	cs_time_plot_format_t	format,
		int	frequency,
		int	n_buffer_steps,
		double	flush_wtime
	)

Set global timer statistics plot options.

This function is only effective before the first call to cs_timer_stats_increment_time_step.

Parameters

[in]	format	associated file format
[in]	frequency	plot every n time steps
[in]	n_buffer_steps	number of time steps in output buffer if file is not to be kept open
[in]	flush_wtime	elapsed time interval between file flushes (if < 0, no forced flush)

cs_timer_stats_set_start_time()

void cs_timer_stats_set_start_time

(

int

time_id

)

Set a start time for time stats.

This is useful to shift the time id for restarts. This function must not be called after cs_timer_stats_increment_time_step.

Parameters

[in]

time_id

associated starting time id

cs_timer_stats_start()

void cs_timer_stats_start

(

int

id

)

Start a timer for a given statistic.

Parents of the current statistic are also started, if not active.

If a timer with the same root but different parents is active, we assume the current operation is a subset of the active timer, so the timer is not started, so as to avoid having a sum of parts larger than the total.

Parameters

[in]

id

id of statistic

cs_timer_stats_stop()

void cs_timer_stats_stop

(

int

id

)

Stop a timer for a given statistic.

Children of the current statistic are also stopped, if active.

Parameters

[in]

id

id of statistic

cs_timer_stats_switch()

int cs_timer_stats_switch

(

int

id

)

Start a timer for a given statistic, stopping previous timers of the same type which are not a parent, and starting inactive parent timers if necessary.

Parameters

[in]

id

id of statistic with same root

Returns

id of previously active statistic, or -1 in case of error