Intrusive Performance Monitoring

A tracepoint utility that provides intrusive (requires code change) performance monitoring. More...

Classes
struct	turi::trace_count

Macros
#define	DECLARE_TRACER(name)   turi::trace_count name;
#define	INITIALIZE_TRACER(name, description)   name.initialize(#name, description);
#define	INITIALIZE_TRACER_NO_PRINT(name, description)   name.initialize(#name, description, false);
#define	BEGIN_TRACEPOINT(name)   unsigned long long __ ## name ## _trace_ = rdtsc();
#define	END_TRACEPOINT(name)   name.incorporate(rdtsc() - __ ## name ## _trace_);
#define	END_AND_BEGIN_TRACEPOINT(endname, beginname)

Detailed Description

A tracepoint utility that provides intrusive (requires code change) performance monitoring.

The tracepoint utility provides a extremely low overhead way of profiling a section of code, counting the number of times the section is entered, the average, maximum and mimimum runtimes of the section.

The tracepoint utility can be enabled file by file, or in an entire project by setting the USE_TRACEPOINT macro before including tracepoint.hpp, or predefining USE_TRACEPOINT globally.

#define USE_TRACEPOINT
#include "perf/tracepoint.hpp"

Example Usage:

DECLARE_TRACER(event)
INITIALIZE_TRACER(event, "event counter name");
Then later on...
BEGIN_TRACEPOINT(event)
... Do stuff ...
END_TRACEPOINT(event)

See DECLARE_TRACER for details.

Macro Definition Documentation

BEGIN_TRACEPOINT

#define BEGIN_TRACEPOINT

(

name

)

unsigned long long __ ## name ## _trace_ = rdtsc();

Begins a tracepoint. The object with name "name" created by DECLARE_TRACER must be in scope. Times a block of code. Every END_TRACEPOINT must be matched with a BEGIN_TRACEPOINT within the same scope. Tracepoints are safe to use in concurrent use.

Definition at line 230 of file tracepoint.hpp.

DECLARE_TRACER

#define DECLARE_TRACER

(

name

)

turi::trace_count name;

Creates a tracing object with a given name. This creates a variable called "name" which is of type trace_count. and is equivalent to:

turi::trace_count name;

The primary reason to use this macro instead of just writing the code above directly, is that the macro is ignored and compiles to nothing when tracepoints are disabled.

Example Usage:

DECLARE_TRACER(event)
INITIALIZE_TRACER(event, "event counter name");
Then later on...
BEGIN_TRACEPOINT(event)
... Do stuff ...
END_TRACEPOINT(event)

There are some minor caveats. BEGIN_TRACEPOINT really declares a variable, so you must begin and end a tracepoint within the same scope, and you cannot call BEGIN_TRACEPOINT on the same event within the same scope.

At program termination the contents of the tracepoint will be emitted. It will print the number times the tracepoint is entered, the total program time spent in the tracepoint, as well as average, minimum and maximum time spent in the tracepoint. Note that the tracepoint is safe to use even when running in parallel. The total time spent in the tracepoint is hence the sum over all threads.

The tracepoint uses rdtsc for fast clock cycle counting, hence might be inaccurate on systems where rdtsc is not necessarily monotonic.

Definition at line 225 of file tracepoint.hpp.

END_AND_BEGIN_TRACEPOINT

#define END_AND_BEGIN_TRACEPOINT	(		endname,
			beginname
	)

Value:

unsigned long long __ ## beginname ## _trace_ = rdtsc(); \
                                                     endname.incorporate(__ ## beginname ## _trace_ - __ ## endname ## _trace_);

Ends the tracepoint with the name "endname" and begins a tracepoint with name "beginname". Conceptually equivalent to

END_TRACEPOINT(endname)
BEGIN_TRACEPOINT(beginname)

but with slightly less overhead.

Definition at line 232 of file tracepoint.hpp.

END_TRACEPOINT

#define END_TRACEPOINT

(

name

)

name.incorporate(rdtsc() - __ ## name ## _trace_);

Ends a tracepoint; see BEGIN_TRACEPOINT.

Definition at line 231 of file tracepoint.hpp.

INITIALIZE_TRACER

#define INITIALIZE_TRACER	(		name,
			description
	)		name.initialize(#name, description);

Initializes the tracer created by DECLARE_TRACER with a description. The object with name "name" created by DECLARE_TRACER must be in scope. This initializes the tracer "name" with a description, and configures the tracer to print when the tracer "name" is destroyed.

Definition at line 227 of file tracepoint.hpp.

INITIALIZE_TRACER_NO_PRINT

#define INITIALIZE_TRACER_NO_PRINT	(		name,
			description
	)		name.initialize(#name, description, false);

Initializes the tracer created by DECLARE_TRACER with a description. The object with name "name" created by DECLARE_TRACER must be in scope. This initializes the tracer "name" with a description, and configures the tracer to NOT print when the tracer "name" is destroyed.

Definition at line 228 of file tracepoint.hpp.