Statistics framework. More...

Files
file	statistics.hpp
	This file contains the statistics framework.

Macros
#define	STAT_REGISTER_VAR(type, var, init, name, description)
	Register an external statistics variable. More...

#define	STAT_DECLARE_VAR(type, var, init)
	Declare an external statistics variable. More...

#define	STAT_REGISTER_VAR_EXTERN(type, var, init, name, description)
	Register an external statistics variable. More...

#define	STAT_REGISTER_GROUP_VAR(type, var, init, name, description, group)
	Register an statistics variable and add it to a group. More...

#define	STAT_REGISTER_GROUP_VAR_EXTERN(type, var, init, name, description, group)
	Register an external statistics variable and add it to a group. More...

#define	STAT_REGISTER_DIST(counttype, indextype, var, start, end, step, init, name, description)
	Define a distribution table (steps). More...

#define	STAT_REGISTER_DIST_RANGE(counttype, indextype, var, range, range_size, init, name, description)
	Define a distribution table (range). More...

#define	STAT_REGISTER_GROUP(var, name, description)
	Register a statistics group. More...

#define	STAT_REGISTER_SUBGROUP(var, name, description, group)
	Register a statistics group and add it to a group. More...

#define	STAT_DECLARE_GROUP(var)
	Declare an external group (or subgroup). More...

#define	STAT_REGISTER_SUM_GROUP(var, name, description)
	Register a statistics summary group. More...

#define	STAT_REGISTER_SUM_SUBGROUP(var, name, description, group)
	Register a statistics summary group. More...

#define	STATISTICS(x) /* nothing */
	Wrapper for statistics only code. More...

Detailed Description

Statistics framework.

The framework provides several facilities to collect information about a virtual machine invocation. The idea is to create objects of specific classes which represent a statistic entity. For different task different classes are provided.

Variables

The most general class is cacao::StatVar. It can be used as a wrapper for almost any type. Statistic variables of this type can be altered in various ways although the most common usage is to increment the value. At the end of the virtual machine run the value is emitted.

Macros

The following macros should be used to define and declare variables of type cacao::StatVar.

Example

* // somewhere on a file global scope
* STAT_REGISTER_VAR(int,count_all_methods,0,"all methods","Number of loaded Methods")
* ..
*
* void handle_method() {
*   // somewhere inside normal code
*   STATISTICS(count_all_methods++);
*   ...
* }
* 

Note: The STATISTICS() macro is used to wrap statistics only code.

Distribution Tables

Distribution tables can be used to collect the distribution of a value. There are two different kinds. The cacao::StatDist has a fixed start, step and end value whereas cacao::StatDistRange can be used to construct arbitrary tables. The usage of both classes is the same.

Macros

Example

* // somewhere on a file global scope
* STAT_REGISTER_DIST(unsigned int,unsigned int,count_block_stack,0,9,1,0,"stack size dist",
*     "Distribution of stack sizes at block boundary")
*
* static const unsigned int count_method_bb_distribution_range[] = {5,10,15,20,30,40,50,75};
* STAT_REGISTER_DIST_RANGE(unsigned int,unsigned int,count_method_bb_distribution,
*     count_method_bb_distribution_range,8,0,"method bb dist.","Distribution of basic blocks per method")
* ...
*
* void handle_method() {
*   // somewhere inside normal code
*   STATISTICS(count_block_stack[indepth]++);
*   ...
*   STATISTICS(count_method_bb_distribution[basicblockcount]++);
*   ...
* }
* 

Groups

Groups are used to structure statistics entities.

Macros

Example

* // somewhere on a file global scope
* STAT_REGISTER_GROUP(const_pcmd_stat,"const pcmd","Number of Const Pseudocommands")
* STAT_REGISTER_GROUP_VAR(int,count_pcmd_load,0,"pcmd load","Number of Const Pseudocommands (load)",const_pcmd_stat)
* ...
* 

Summary Groups

Summary groups are a special form of groups. The only difference is that a summary group sums up the values of all children and prints it.

Macros

Example

* // somewhere on a file global scope
* STAT_REGISTER_SUM_GROUP(const_pcmd_stat,"const pcmd","Number of Const Pseudocommands")
* STAT_REGISTER_GROUP_VAR(int,count_pcmd_load,0,"pcmd load","Number of Const Pseudocommands (load)",const_pcmd_stat)
* STAT_REGISTER_GROUP_VAR(int,count_pcmd_zero,0,"pcmd zero","Number of Const Pseudocommands (zero)",const_pcmd_stat)
* ...
* 

Macro Definition Documentation

#define STAT_DECLARE_GROUP ( var )

Declare an external group (or subgroup).

In contrast to variables are groups always defined at a global scope. This can be prevented by e.g. an anonymous namespace.

Parameters

var	Variable name of the statistic group.

See Also: STAT_REGISTER_GROUP; STAT_REGISTER_SUBGROUP

Definition at line 970 of file statistics.hpp.

#define STAT_DECLARE_VAR	(	type,
		var,
		init
	)

Declare an external statistics variable.

The definition should be done via the STAT_REGISTER_VAR_EXTERN() macro.

Parameters

type	Type of the variable. It should support the basic operators (arithmetic, assigment, etc.) as well as operator<<(OStream&, type) for printing support.
var	Name of the statistic variable.
init	Initial value for the variable.

See Also: STAT_REGISTER_VAR_EXTERN

Definition at line 963 of file statistics.hpp.

#define STAT_REGISTER_DIST	(	counttype,
		indextype,
		var,
		start,
		end,
		step,
		init,
		name,
		description
	)

Define a distribution table (steps).

This macro creates a distribution table for some statistic values (e.g. number of basic blocks per method). In principle a static cacao::StatDist object is created which can be used to collect value distributions.

The "width of the table columns" are fixed by the step parameter. All columns have the same width (besides the first and last one).

Example:

* STAT_REGISTER_DIST(unsigned int,unsigned int,count_block_stack,0,9,1,0,"stack size dist",
*          "Distribution of stack sizes at block boundary")
* 

Result:

Distribution of stack sizes at block boundary(stack size dist):
     0]    1]    2]    3]    4]    5]    6]    7]    8]    9](   9
  4017   325    20     8     7     4     1     0     0     0     0
  0.92  0.07  0.00  0.00  0.00  0.00  0.00  0.00  0.00  0.00  0.00  ratio
  0.92  0.99  1.00  1.00  1.00  1.00  1.00  1.00  1.00  1.00  1.00  cumulated ratio

Parameters

counttype	Type of the "table entries". In most cases unsigned is the right choice.
indextype	Type of the "table index". This is the type of the things you want to count. It should support the basic arithmetic operations as well as operator<<(OStream&).
var	Name of the statistic distribution variable.
start	Start of the table.
end	End of the table.
step	Step size.
init	Initial value for the variable.
name	Printable name of the variable.
description	Printable description of the variable.

See Also: cacao::StatDist; STAT_REGISTER_DIST_RANGE

Definition at line 968 of file statistics.hpp.

#define STAT_REGISTER_DIST_RANGE	(	counttype,
		indextype,
		var,
		range,
		range_size,
		init,
		name,
		description
	)

Define a distribution table (range).

In contrast to STAT_REGISTER_DIST() the "width of the columns" can be set arbitrary.

Example:

* static const unsigned int count_method_bb_distribution_range[] = {5,10,15,20,30,40,50,75};
* STAT_REGISTER_DIST_RANGE(unsigned int,unsigned int,count_method_bb_distribution,
*    count_method_bb_distribution_range,8,0,"method bb dist.","Distribution of basic blocks per method")
* 

Result:

Distribution of basic blocks per method(method bb dist.):
     5]   10]   15]   20]   30]   40]   50]   75](  75
   774    96    45    17    15     3     5     3     2
  0.81  0.10  0.05  0.02  0.02  0.00  0.01  0.00  0.00  ratio
  0.81  0.91  0.95  0.97  0.99  0.99  0.99  1.00  1.00  cumulated ratio

Parameters

counttype	Type of the "table entries". In most cases unsigned is the right choice.
indextype	Type of the "table index". This is the type of the things you want to count. It should support the basic arithmetic operations as well as operator<<(OStream&).
var	Name of the statistic distribution variable.
range	Array of table values.
range_size	Size of the range array.
init	Initial value for the variable.
name	Printable name of the variable.
description	Printable description of the variable.

See Also: cacao::StatDistRange; STAT_REGISTER_DIST

Definition at line 969 of file statistics.hpp.

#define STAT_REGISTER_GROUP	(	var,
		name,
		description
	)

Register a statistics group.

Create a new statistics group and add it to the root group. Groups are used to organize statistics entries (variables or groups).

Parameters

var	Name of the statistic group.
name	Printable name of the group.
description	Printable description of the group.

See Also: STAT_DECLARE_GROUP; STAT_REGISTER_SUBGROUP

Definition at line 971 of file statistics.hpp.

#define STAT_REGISTER_GROUP_VAR	(	type,
		var,
		init,
		name,
		description,
		group
	)

Register an statistics variable and add it to a group.

This is the same as STAT_REGISTER_VAR() but the variable is added to group.

Parameters

type	Type of the variable. It should support the basic operators (arithmetic, assigment, etc.) as well as operator<<(OStream&, type) for printing support.
var	Name of the statistic variable.
init	Initial value for the variable.
name	Printable name of the variable.
description	Printable description of the variable.
group	Parent group of this variable.

See Also: STAT_REGISTER_VAR; STAT_REGISTER_GROUP_VAR_EXTERN

Definition at line 967 of file statistics.hpp.

#define STAT_REGISTER_GROUP_VAR_EXTERN	(	type,
		var,
		init,
		name,
		description,
		group
	)

Register an external statistics variable and add it to a group.

The difference to STAT_REGISTER_GROUP_VAR() is the same as between STAT_REGISTER_VAR_EXTERN and STAT_REGISTER_VAR().

Parameters

type	Type of the variable. It should support the basic operators (arithmetic, assigment, etc.) as well as operator<<(OStream&, type) for printing support.
var	Name of the statistic variable.
init	Initial value for the variable.
name	Printable name of the variable.
description	Printable description of the variable.
group	Parent group of this variable.

See Also: STAT_DECLARE_VAR; STAT_REGISTER_VAR

Definition at line 965 of file statistics.hpp.

#define STAT_REGISTER_SUBGROUP	(	var,
		name,
		description,
		group
	)

Register a statistics group and add it to a group.

Create a new statistics group and add it to a specified group.

Parameters

var	Name of the statistic group.
name	Printable name of the group.
description	Printable description of the group.
group	Parent group of this variable.

See Also: STAT_DECLARE_GROUP; STAT_REGISTER_GROUP

Definition at line 974 of file statistics.hpp.

#define STAT_REGISTER_SUM_GROUP	(	var,
		name,
		description
	)

Register a statistics summary group.

Create a new statistics group and add it to the root group. Summary groups are used to calculate the sum of several dependant statistic entries e.g. memory usage of the compiler

Example:

* STAT_REGISTER_SUM_GROUP(info_struct_stat,"info structs","info struct usage")
* STAT_REGISTER_GROUP_VAR(int,size_classinfo,0,"size classinfo","classinfo",info_struct_stat)
* STAT_REGISTER_GROUP_VAR(int,size_fieldinfo,0,"size fieldinfo","fieldinfo",info_struct_stat)
* STAT_REGISTER_GROUP_VAR(int,size_methodinfo,0,"size methodinfo","methodinfo",info_struct_stat)
* STAT_REGISTER_GROUP_VAR(int,size_codeinfo,0,"size codeinfo","codeinfo",info_struct_stat)
* STAT_REGISTER_GROUP_VAR(int,size_lineinfo,0,"size lineinfo","lineinfo",info_struct_stat)
* 

Result:

                size classinfo    147656 : classinfo
                size fieldinfo     78272 : fieldinfo
               size methodinfo    830024 : methodinfo
                 size lineinfo     91192 : lineinfo
                 size codeinfo    158400 : codeinfo
                                 -------
                           sum   1305544 : info struct usage

Parameters

var	Name of the statistic group.
name	Printable name of the group.
description	Printable description of the group.

See Also: STAT_REGISTER_SUM_SUBGROUP

Definition at line 972 of file statistics.hpp.

#define STAT_REGISTER_SUM_SUBGROUP	(	var,
		name,
		description,
		group
	)

Register a statistics summary group.

Create a new statistics group and add it to a specified group.

Parameters

var	Name of the statistic group.
name	Printable name of the group.
description	Printable description of the group.
group	Parent group of this group.

See Also: STAT_REGISTER_SUM_GROUP

Definition at line 973 of file statistics.hpp.

#define STAT_REGISTER_VAR	(	type,
		var,
		init,
		name,
		description
	)

Register an external statistics variable.

This macros defines a static variable of type cacao::StatVar<type,init> and adds it to the root statistics group. All STAT_REGISTER_* macros should only occur in implementation files. If a variable is used in several compilation units STAT_REGISTER_VAR_EXTERN() and STAT_DECLARE_VAR() should be used.

Parameters

type	Type of the variable. It should support the basic operators (arithmetic, assigment, etc.) as well as operator<<(OStream&, type) for printing support.
var	Name of the statistic variable.
init	Initial value for the variable.
name	Printable name of the variable.
description	Printable description of the variable.

See Also: STAT_DECLARE_VAR; STAT_REGISTER_VAR_EXTERN; STAT_REGISTER_GROUP_VAR

Definition at line 966 of file statistics.hpp.

#define STAT_REGISTER_VAR_EXTERN	(	type,
		var,
		init,
		name,
		description
	)

Register an external statistics variable.

In contrast to STAT_REGISTER_VAR() variables defined via STAT_REGISTER_VAR_EXTERN() are not declared static static and therefore allows external binding. If a statistics variable is only used in one compilation unit, STAT_REGISTER_VAR() is preferable.

Parameters

type	Type of the variable. It should support the basic operators (arithmetic, assigment, etc.) as well as operator<<(OStream&, type) for printing support.
var	Name of the statistic variable.
init	Initial value for the variable.
name	Printable name of the variable.
description	Printable description of the variable.

See Also: STAT_DECLARE_VAR; STAT_REGISTER_VAR

Definition at line 964 of file statistics.hpp.

#define STATISTICS ( x ) /* nothing */

Wrapper for statistics only code.

Definition at line 975 of file statistics.hpp.

Files

Macros

Detailed Description

Variables

Macros

Example

Distribution Tables

Macros

Example

Groups

Macros

Example

Summary Groups

Macros

Example

Macro Definition Documentation