SourcePro® API Reference Guide

 
Classes | Macros | Enumerations | Functions
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.

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.

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.

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.

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.

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.

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:

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
1 #include <rw/trace/userdefs.h>

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

Example
1 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

Header File
1 #include <rw/thr/defs.h>

An enumerated type used to identify static instance constructors.

Enumerator
RW_STATIC_CTOR 

 

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.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.