CPU Broker: instrumentation.h File Reference

Instrumenting blocks of code or expressions is done by adding a call to CB_INSTR_POINT in the configure.in file and surrounding the code with a macro call. For example, to do high resolution timings of the following code:

   for( lpc = 0; lpc < 100; lpc++ )
   {
       ...
   }

   CB_INSTR_POINT([my_point],
                  [HRTIME_INSTR],
                  [My instrumentation point])

Where 'my_point' is the name of the instrumentation point, HRTIME_INSTR is the C macro that will record the timings, and 'My instrumentation point' is the description of the point. The result of this call will be two new definitions in the config.h: 'INSTR_my_point' and 'INSTR_my_point_data'. The first C macro is used to surround the code block and the second contains the data used to initialize the instrumentation point structure (iPoint). With these new definitions, we can modify our original code to add instrumentation:

   #if defined(INSTR_my_point_data)
   static struct iPoint IP_my_point = {
       INSTR_my_point_data
   };
   #endif
 ...
   INSTR_my_point(&IP_my_point, ({
       for( lpc = 0; lpc < 100; lpc++ )
       {
           ...
       }
   }));

(Notice the parentheses around the code block, these are required for things to parse correctly.)

Finally, to enable this instrumentation point, you either need to use --enable-instrumentation to enable all of the points, or --enable-instrumentation="my_point ..." to enable this point and any others named.

Any instrumentation data collected during a run is usually appended to a file iPrintPointsAtExit function.

Go to the source code of this file.


Classes
struct	iPoint
struct	iInstrumentationData
Defines
#define	IPOINT_INIT_HISTORY(history)
	Macro used to statically initialize the ip_History field of the iPoint structure.
#define	HRTIME_INSTR(point, block)
	Macro used to perform high-resolution timings of a block of code.
#define	LRTIME_INSTR(point, block)
	Macro used to perform low-resolution timings of a block of code.
#define	LRCPUTIME_INSTR(point, block)
	Macro used to perform low-resolution CPU timings of a block of code.
#define	ACCUM_INSTR(point, expr)
	Macro used to accumulate the value of a numeral expression.
#define	NOINSTR(point, block) (void)(block)
	Macro used to avoid instrumenting a block of code.
#define	INSTR_FILE_NAME_ENV "CB_INSTR_FILE_NAME"
	The environment variable name to check for the instrumentation output file name.
Typedefs
typedef unsigned long long	lrtime_t
	Container for low-resolution timer values.
typedef unsigned long long	hrtime_t
	Container for high-resolution timer values.
Enumerations
enum	{ IPB_PRINT_HISTORY, IPB_DROP_HISTORY_START }
enum	{ IPF_PRINT_HISTORY = (1L << IPB_PRINT_HISTORY), IPF_DROP_HISTORY_START = (1L << IPB_DROP_HISTORY_START), IPF_MASK }
	Flags for the iPoint structure. More...
Functions
lrtime_t	lrtime (void)
lrtime_t	lrcputime (void)
hrtime_t	hrtime (void)
void	iPostFloatData (struct iPoint *ip, double value)
	Post a floating point data value to an instrumentation point.
void	iPrintPoint (FILE file, struct iPoint ip)
	Print the collected values for an instrumentation point.
void	iPrintPoints (FILE *file)
	Print all of the instrumentation points that have had data posted to them using iPrintPoint.
void	iPrintPointsAtExit (void)
	An atexit(3) function that calls iPrintPoints with a file from one of the following sources (listed in order of precedence):.
Variables
iInstrumentationData	instrumentation_data
	The global data needed by the instrumentation infrastructure.

Define Documentation

#define ACCUM_INSTR	(	point,
		expr		)

Value:

{ \
    iPostFloatData(point, (double)(expr)); \
}

Macro used to accumulate the value of a numeral expression.

Parameters:

	point	The iPoint to use when recording data.
	expr	An expression that results in a number value.

See also:: NOINSTR

Definition at line 299 of file instrumentation.h.

#define HRTIME_INSTR	(	point,
		block		)

Value:

{ \
    hrtime_t _start, _end; \
\
    _start = hrtime(); \
    block; \
    _end = hrtime(); \
    iPostFloatData(point, (_end - _start)); \
}

Macro used to perform high-resolution timings of a block of code.

Parameters:

	point	The iPoint to use when recording data.
	block	The code block to instrument.

See also:: NOINSTR

Definition at line 248 of file instrumentation.h.

#define IPOINT_INIT_HISTORY

(

history

)

Value:

{ \
    history, \
    sizeof(history) / sizeof(double) \
}

Macro used to statically initialize the ip_History field of the iPoint structure.

Parameters:

history

A statically allocated array of doubles.

Definition at line 235 of file instrumentation.h.

#define LRCPUTIME_INSTR	(	point,
		block		)

Value:

{ \
    lrtime_t _start, _end; \
\
    _start = lrcputime(); \
    block; \
    _end = lrcputime(); \
    iPostFloatData(point, (_end - _start)); \
}

Macro used to perform low-resolution CPU timings of a block of code.

Parameters:

	point	The iPoint to use when recording data.
	block	The code block to instrument.

See also:: NOINSTR

Definition at line 282 of file instrumentation.h.

#define LRTIME_INSTR	(	point,
		block		)

Value:

{ \
    lrtime_t _start, _end; \
\
    _start = lrtime(); \
    block; \
    _end = lrtime(); \
    iPostFloatData(point, (_end - _start)); \
}

Macro used to perform low-resolution timings of a block of code.

Parameters:

	point	The iPoint to use when recording data.
	block	The code block to instrument.

See also:: NOINSTR

Definition at line 265 of file instrumentation.h.

#define NOINSTR	(	point,
		block		)	(void)(block)

Macro used to avoid instrumenting a block of code.

Parameters:

	point	Not used. This is only here so it can mimic the other INSTR macros.
	block	A block of code to execute.

Definition at line 310 of file instrumentation.h.

Enumeration Type Documentation

anonymous enum

Flags for the iPoint structure.

Enumeration values:

IPF_PRINT_HISTORY	Print the entire history in addition to the summary data.
IPF_DROP_HISTORY_START	Drop data values at the start of the history instead of the tail.
IPF_MASK	Bitmask covering all of the meaningful flag bits.

Definition at line 175 of file instrumentation.h.

Function Documentation

hrtime_t hrtime ( void ) [inline, static]

Returns:: A high-resolution time stamp.

Definition at line 155 of file instrumentation.h.

References hrtime_t.

void iPostFloatData	(	struct iPoint *	ip,
		double	value
	)

Post a floating point data value to an instrumentation point.

Parameters:

	ip	The instrumentation point to add the given value to.
	value	The value to add.

Definition at line 86 of file instrumentation.c.

References iInitPoint(), IP_HISTORY_START_ADD, and require.

void iPrintPoint	(	FILE *	file,
		struct iPoint *	ip
	)

Print the collected values for an instrumentation point.

The summary data printed depends on whether or not a history array has been provided: no history means the summary covers all of the posted data; otherwise the summary covers only the data held in the history.

Parameters:

	file	The file to print the data to.
	ip	The instrumentation point to print out.

Definition at line 126 of file instrumentation.c.

References IP_HISTORY_START_ADD, IPF_MASK, and require.

Referenced by iPrintPoints().

void iPrintPoints

(

FILE *

file

)

Print all of the instrumentation points that have had data posted to them using iPrintPoint.

Parameters:

file

The file to print the data to.

Definition at line 231 of file instrumentation.c.

References instrumentation_data, iPrintPoint(), and require.

Referenced by iPrintPointsAtExit().

void iPrintPointsAtExit

(

void

)

An atexit(3) function that calls iPrintPoints with a file from one of the following sources (listed in order of precedence):.

The value of the CB_INSTR_FILE_NAME environment variable, if it is defined. Note: A value of "-" represents stdout.
The instrumentation_data.iid_OutputFileName variable, if it is non-NULL. Note: A value of "-" represents stdout.
A formatted file name derived from PACKAGE and the current process ID.

All of the files are opened in append mode and the current time is printed out before calling iPrintPoints. When the function finishes it will clear instrumentation_data.iid_FirstPoint so that any future calls to this function will not result in data being printed more than once.

Definition at line 246 of file instrumentation.c.

References DEFAULT_INSTRUMENTATION_FILE_NAME, INSTR_FILE_NAME_ENV, instrumentation_data, and iPrintPoints().

Referenced by main(), and ManagerImpl::ManagerImpl().