Execution Tracing

Module Description

Header File

#include <rw/trace/userdefs.h>

{}

Execution Tracing classes enable you to monitor the runtime behavior of your applications. Trace output messages can be filtered at both compile-time and runtime for maximum flexibility.

For complete information about the Execution Tracing package, see the Threads Module User's Guide.

The set declaration macros implement the runtime lookup of environment variables that determine whether a function will generate a trace event. Trace does not work correctly if the set declaration macros are not used or are used improperly. Set declaration macro names all include the word TRACEABLE, to distinguish them from event generation macros. Set declaration macros come in three varieties: package declaration macros, class declaration macros, and function declaration macros.

Package Declaration Macros

The package declaration macros are optional. You use them only when your application is split into packages, and you want to control tracing separately for each package. For information on how you can create your own packages and package tracing macros, see Section 6.9, "Using Package-level Tracing," in the Threads Module User's Guide.

Note

A predefined package set named rw_user acts as a default super set for your classes and functions. If this single package set is sufficient for your purposes, you can skip this section.

The package declaration macros are used in the implementation of the Execution Tracing package itself. To get a feel for what these macros do, you can check the userdefs.h and userdefs.cpp files in the trace source directories.

The macros take one parameter, packageName, to specify the name of the package to be traced. The packageName must be a valid C++ identifier. The DECLARE and DEFINE macros must be used in pairs, and the packageName of the DECLARE and DEFINE macros must match.

RW_TRACE_DECLARE_TRACEABLE_PACKAGE(packageName)

Declares a traceable package. This macro is normally placed at the end of the header file that defines the trace macros for that package. For an example, see the trace header file userdefs.h or the pkgdefs.h file for any other package in the Threads Module.

RW_TRACE_DEFINE_TRACEABLE_PACKAGE(packageName)

Provides a definition for a static variable defined by the matching DECLARE macro (above). This macro must be placed in some implementation file (.cpp) for your application. For an example, see the trace source file userdefs.cpp or the pkgdefs.cpp file in any of the other packages in the Threads Module.

Class Declaration Macros

The class declaration macros declare classes to be traceable, with the rw_user package as the super set. If you intend to trace any of a class' functions (member or static member), you must use these macros. Friend functions can either be traced with these macros or traced as global functions.

If you have used the package declaration macros to define other packages, you need to create your own class declaration macros. See Section 6.9, "Using Package-level Tracing," in the Threads Module User's Guide.

The macros take one parameter, className, to specify the name of the class to be traced. The className must be a valid C++ identifier. The DECLARE and DEFINE macros must be used in pairs, and the className of the DECLARE and DEFINE macros must match.

RW_USER_DECLARE_TRACEABLE_CLASS(className)

Declares a non-template class as traceable. This macro must be placed in the header file for a class before the class declaration. Otherwise, it generates an undefined symbol compile error.

RW_USER_DEFINE_TRACEABLE_CLASS(className)

Provides a definition for a static variable defined by the matching DECLARE macro (above). This macro must be placed in the implementation (.cpp) file for the class.

RW_USER_DECLARE_TRACEABLE_TEMPLATE_CLASS(className)

Declares a template class as traceable. Do not include the template parameters in the className. This macro must be placed in the header file for a class before the class declaration. Otherwise, it generates an undefined symbol compile error.

RW_USER_DEFINE_TRACEABLE_TEMPLATE_CLASS(className)

Provides a definition for a static variable defined by the matching DECLARE macro (above). Do not include the template parameters in the className. This macro must be placed in the implementation file (typically a .cc file) for the template class.

Function Declaration Macros

The function declaration macros declare functions to be traceable. In addition, the macros automatically generate ENTRY and EXIT trace events upon entry and exit of the function. Every function that requires tracing must have one of these macros, normally as the first line of the function. Attempting to use more than one function declaration macro in a function results in compile or link errors.

The macro families come in sets of four macros, including an INLINE version for inline functions, a TEMPLATE version for template functions, a INLINE_TEMPLATE version for inline template functions, and a basic version for all other functions. Using the incorrect version results in compile and link errors.

Function declaration macros can take these parameters:

• functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag is usually the name of the function (for a global function) or a string of the form "ClassName_functionName" (for a member function). See the Threads Module User's Guide, for more on assigning tag names.
• className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

Classes
class	RWTraceClientAlreadyAdded
	Trace exception thrown when an attempt is made to add a client that has already been added. More...
class	RWTraceClientAlreadyConnected
	Trace exception thrown when an attempt is made to connect to a client that is already connected. More...
class	RWTraceClientNotConnected
	Trace exception thrown when a trace operation is attempted on a client is not yet connected. More...
class	RWTraceEventClient
	A handle class for trace event client implementations. More...
class	RWTraceEventClientImp
	A body class for trace event client implementations. More...
class	RWTraceEventFilter
	A handle class for trace event filter implementations. More...
class	RWTraceEventFilterImp
	A body class for trace event filter implementations. More...
class	RWTraceInvalidClient
	Trace exception thrown when an operation is attempted on a client that is not valid. More...
class	RWTraceInvalidPointer
	Trace exception thrown when the client is not connected to a valid body. More...
class	RWTraceLevelFilter
	A handle class for a single-client filter that lets events only of the supplied severity level or higher to pass through. More...
class	RWTraceLevelFilterImp
	A body class for trace level filter implementations. More...
class	RWTraceManager
	The handle to a singleton trace event manager implementation. More...
class	RWTraceMultiClientFilter
	A handle class for a trace event filter that accepts multiple clients. More...
class	RWTraceMultiClientFilterImp
	A body class for trace event filters that accept multiple clients. More...
class	RWTraceOstreamClient
	A handle class for a trace event client that sends all events to an std::ostream. More...
class	RWTraceOstreamClientImp
	A body class for clients that send all trace events to an std::ostream. More...
class	RWTraceSingleClientFilter
	A handle class for a trace event filter that accepts only one client. More...
class	RWTraceSingleClientFilterImp
	A body class for a trace level filter that accepts only one client. More...

Macros
#define	RW_STREAM_TO_STRING(stream)
#define	RW_TRACE_DECLARE_TRACEABLE_PACKAGE(packageName)
#define	RW_TRACE_DEFINE_TRACEABLE_PACKAGE(packageName)
#define	RW_USER_DECLARE_TRACEABLE_CLASS(className)
#define	RW_USER_DECLARE_TRACEABLE_TEMPLATE_CLASS(className)
#define	RW_USER_DEFINE_TRACEABLE_CLASS(className)
#define	RW_USER_DEFINE_TRACEABLE_TEMPLATE_CLASS(className)
#define	RW_USER_TRACE_DEBUG(msg)
#define	RW_USER_TRACE_ERROR(msg)
#define	RW_USER_TRACE_FATAL(msg)
#define	RW_USER_TRACE_INFO(msg)
#define	RW_USER_TRACE_OBJECT_DEBUG(msg)
#define	RW_USER_TRACE_OBJECT_ERROR(msg)
#define	RW_USER_TRACE_OBJECT_FATAL(msg)
#define	RW_USER_TRACE_OBJECT_INFO(msg)
#define	RW_USER_TRACE_OBJECT_TEST(msg)
#define	RW_USER_TRACE_OBJECT_WARNING(msg)
#define	RW_USER_TRACE_TEST(msg)
#define	RW_USER_TRACE_WARNING(msg)
#define	RW_USER_TRACEABLE_FRIEND(functionTag, className)
#define	RW_USER_TRACEABLE_FUNCTION(functionTag)
#define	RW_USER_TRACEABLE_INLINE_FRIEND(functionTag, className)
#define	RW_USER_TRACEABLE_INLINE_FUNCTION(functionTag)
#define	RW_USER_TRACEABLE_INLINE_MEMBER(functionTag, className)
#define	RW_USER_TRACEABLE_INLINE_STATIC_MEMBER(functionTag, className)
#define	RW_USER_TRACEABLE_INLINE_TEMPLATE_FRIEND(functionTag, className)
#define	RW_USER_TRACEABLE_INLINE_TEMPLATE_FUNCTION(functionTag)
#define	RW_USER_TRACEABLE_INLINE_TEMPLATE_MEMBER(functionTag, className)
#define	RW_USER_TRACEABLE_INLINE_TEMPLATE_STATIC_MEMBER(functionTag, className)
#define	RW_USER_TRACEABLE_MEMBER(functionTag, className)
#define	RW_USER_TRACEABLE_STATIC_MEMBER(functionTag, className)
#define	RW_USER_TRACEABLE_TEMPLATE_FRIEND(functionTag, className)
#define	RW_USER_TRACEABLE_TEMPLATE_FUNCTION(functionTag)
#define	RW_USER_TRACEABLE_TEMPLATE_MEMBER(functionTag, className)
#define	RW_USER_TRACEABLE_TEMPLATE_STATIC_MEMBER(functionTag, className)

Enumerations
enum	RWStaticCtor { RW_STATIC_CTOR }
enum	RWTraceEventSeverity {   RW_TRACE_LEVEL_NONE, RW_TRACE_LEVEL_UNSPECIFIED, RW_TRACE_LEVEL_FATAL, RW_TRACE_LEVEL_ERROR,   RW_TRACE_LEVEL_WARNING, RW_TRACE_LEVEL_INFO, RW_TRACE_LEVEL_TEST, RW_TRACE_LEVEL_DEBUG,   RW_TRACE_LEVEL_ENTRY }

Functions
std::ostream &	operator<< (std::ostream &strm, const RWTraceEventSeverity &crit)
std::istream &	operator>> (std::istream &strm, RWTraceEventSeverity &crit)

Macro Definition Documentation

#define RW_STREAM_TO_STRING

(

stream

)

Header File

#include <rw/trace/userdefs.h>

Macro for streaming objects into a trace macro's message parameter.

Example

RW_TRACE_INFO( "main()", RW_STREAM_TO_STRING("One = " << 1) );

#define RW_TRACE_DECLARE_TRACEABLE_PACKAGE

(

packageName

)

Declares a traceable package. packageName, to specifies the name of the package to be traced. The packageName must be a valid C++ identifier. This macro is normally placed at the end of the header file that defines the trace macros for that package. For an example, see the trace header file userdefs.h or the pkgdefs.h file for any other package in the Threads Module.

#define RW_TRACE_DEFINE_TRACEABLE_PACKAGE

(

packageName

)

Provides a definition for a static variable defined by the matching RW_TRACE_DECLARE_TRACEABLE_PACKAGE macro. This macro must be placed in some implementation file (.cpp) for your application. For an example, see the trace source file userdefs.cpp or the pkgdefs.cpp file in any of the other packages in the Threads Module.

#define RW_USER_DECLARE_TRACEABLE_CLASS

(

className

)

Declares a non-template class as traceable. className specifies the name of the class to be traced. The className must be a valid C++ identifier. This macro must be placed in the header file for a class before the class declaration. Otherwise, it generates an undefined symbol compile error.

#define RW_USER_DECLARE_TRACEABLE_TEMPLATE_CLASS

(

className

)

Declares a template class as traceable. className specifies the name of the class to be traced. The className must be a valid C++ identifier. This macro must be placed in the header file for a class before the class declaration. Otherwise, it generates an undefined symbol compile error.

#define RW_USER_DEFINE_TRACEABLE_CLASS

(

className

)

Provides a definition for a static variable defined by the matching RW_USER_DECLARE_TRACEABLE_CLASS macro. This macro must be placed in the implementation (.cpp) file for the class.

#define RW_USER_DEFINE_TRACEABLE_TEMPLATE_CLASS

(

className

)

Provides a definition for a static variable defined by the matching RW_USER_DECLARE_TRACEABLE_TEMPLATE_CLASS macro. This macro must be placed in the implementation file (typically a .cc file) for the template class.

#define RW_USER_TRACE_DEBUG

(

msg

)

Generates a 'DEBUG' severity level trace event. For use by static member functions, friend functions, or global functions.

#define RW_USER_TRACE_ERROR

(

msg

)

Generates a 'ERROR' severity level trace event. For use by static member functions, friend functions, or global functions.

#define RW_USER_TRACE_FATAL

(

msg

)

Generates a 'FATAL' severity level trace event. For use by static member functions, friend functions, or global functions.

#define RW_USER_TRACE_INFO

(

msg

)

Generates a 'INFO' severity level trace event. For use by static member functions, friend functions, or global functions.

#define RW_USER_TRACE_OBJECT_DEBUG

(

msg

)

Generates a 'DEBUG' severity level trace event. For use in member functions.

#define RW_USER_TRACE_OBJECT_ERROR

(

msg

)

Generates a 'ERROR' severity level trace event. For use in member functions.

#define RW_USER_TRACE_OBJECT_FATAL

(

msg

)

Generates a 'FATAL' severity level trace event. For use in member functions.

#define RW_USER_TRACE_OBJECT_INFO

(

msg

)

Generates a 'INFO' severity level trace event. For use in member functions.

#define RW_USER_TRACE_OBJECT_TEST

(

msg

)

Generates a 'TEST' severity level trace event. For use in member functions.

#define RW_USER_TRACE_OBJECT_WARNING

(

msg

)

Generates a 'WARNING' severity level trace event. For use in member functions.

#define RW_USER_TRACE_TEST

(

msg

)

Generates a 'TEST' severity level trace event. For use by static member functions, friend functions, or global functions.

#define RW_USER_TRACE_WARNING

(

msg

)

Generates a 'WARNING' severity level trace event. For use by static member functions, friend functions, or global functions.

#define RW_USER_TRACEABLE_FRIEND	(		functionTag,
			className
	)

Defines a friend function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class. The functionTag parameter is usually the function name.

Note

Each function in an application may be traceable as a friend to only one class. Friend functions can also be traced as global functions.

#define RW_USER_TRACEABLE_FUNCTION

(

functionTag

)

Defines a global function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually the function name.

#define RW_USER_TRACEABLE_INLINE_FRIEND	(		functionTag,
			className
	)

Defines a friend function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class. The functionTag parameter is usually the function name.

Note

Each function in an application may be traceable as a friend to only one class. Friend functions can also be traced as global functions.

#define RW_USER_TRACEABLE_INLINE_FUNCTION

(

functionTag

)

Defines a global function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually the function name.

#define RW_USER_TRACEABLE_INLINE_MEMBER	(		functionTag,
			className
	)

Defines a member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

#define RW_USER_TRACEABLE_INLINE_STATIC_MEMBER	(		functionTag,
			className
	)

Defines a static member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

#define RW_USER_TRACEABLE_INLINE_TEMPLATE_FRIEND	(		functionTag,
			className
	)

Defines a friend function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class. The functionTag parameter is usually the function name.

Note

Each function in an application may be traceable as a friend to only one class. Friend functions can also be traced as global functions.

#define RW_USER_TRACEABLE_INLINE_TEMPLATE_FUNCTION

(

functionTag

)

Defines a global function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually the function name.

#define RW_USER_TRACEABLE_INLINE_TEMPLATE_MEMBER	(		functionTag,
			className
	)

Defines a member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

#define RW_USER_TRACEABLE_INLINE_TEMPLATE_STATIC_MEMBER	(		functionTag,
			className
	)

Defines a static member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

#define RW_USER_TRACEABLE_MEMBER	(		functionTag,
			className
	)

Defines a member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

#define RW_USER_TRACEABLE_STATIC_MEMBER	(		functionTag,
			className
	)

Defines a static member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

#define RW_USER_TRACEABLE_TEMPLATE_FRIEND	(		functionTag,
			className
	)

Defines a friend function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class. The functionTag parameter is usually the function name.

Note

Each function in an application may be traceable as a friend to only one class. Friend functions can also be traced as global functions.

#define RW_USER_TRACEABLE_TEMPLATE_FUNCTION

(

functionTag

)

Defines a global function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually the function name.

#define RW_USER_TRACEABLE_TEMPLATE_MEMBER	(		functionTag,
			className
	)

Defines a member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

#define RW_USER_TRACEABLE_TEMPLATE_STATIC_MEMBER	(		functionTag,
			className
	)

Defines a static member function to be traceable. functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag parameter is usually a string of the form "ClassName_functionName". className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.

Enumeration Type Documentation

enum RWStaticCtor

Header File

#include <rw/thr/defs.h>

An enumerated type used to identify static instance constructors.

Enumerator
RW_STATIC_CTOR

enum RWTraceEventSeverity

RWTraceEventSeverity contains tracing severity levels; provides basis for convenience macros.

Enumerator
RW_TRACE_LEVEL_NONE
RW_TRACE_LEVEL_UNSPECIFIED
RW_TRACE_LEVEL_FATAL	unrecoverable error
RW_TRACE_LEVEL_ERROR	recoverable error
RW_TRACE_LEVEL_WARNING	insignificant or potential error
RW_TRACE_LEVEL_INFO	general status or resource mngmnt
RW_TRACE_LEVEL_TEST	used for testing
RW_TRACE_LEVEL_DEBUG	used for debugging
RW_TRACE_LEVEL_ENTRY	entry/exit (automatic)

Function Documentation

std::ostream& operator<<	(	std::ostream &	strm,
		const RWTraceEventSeverity &	crit
	)

Streams an RWTraceEventSeverity into an output stream.

std::istream& operator>>	(	std::istream &	strm,
		RWTraceEventSeverity &	crit
	)

Streams an input stream into an RWTraceEventSeverity.