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 only this point.

Go to the source code of this file.


Classes
struct	iInstrumentationData
struct	iPoint
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	ACCUM_INSTR(point, expr)
	Macro used to record the value of an numeral expression.
#define	NOINSTR(point, block) block
	Macro used to avoid instrumenting a block of code.
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_DROP_HISTORY_START }
enum	{ IPF_DROP_HISTORY_START }
Functions
lrtime_t	lrtime (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.
void	iPrintPointsAtExit (void)
	An atexit(3) function that calls iPrintPoints with a file whose name is taken from instrumentation_data.iid_OutputFileName or derived from the package name and process ID.
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 record the value of an 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 242 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 208 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 195 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 225 of file instrumentation.h.

#define NOINSTR	(	point,
		block		)	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.

See also:: NOINSTR

Definition at line 255 of file instrumentation.h.

Function Documentation

hrtime_t hrtime ( void ) [inline, static]

Returns:: A high-resolution time stamp.

Definition at line 122 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 71 of file instrumentation.c.

References IP_HISTORY_START_ADD, and require.

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

Print the collected values for an instrumentation point.

Parameters:

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

Definition at line 108 of file instrumentation.c.

References IP_HISTORY_START_ADD, and require.

Referenced by iPrintPoints().

lrtime_t lrtime ( void ) [inline, static]

Returns:: A low-resolution time stamp. The current resolution is on the order of milliseconds.

Definition at line 91 of file instrumentation.h.

References lrtime_t.

instrumentation.h File Reference

Detailed Description

Classes

Defines

Typedefs

Enumerations

Functions

Variables

Define Documentation

Function Documentation