SourcePro® 2023.1 |
SourcePro® API Reference Guide |
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.
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.
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.
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.
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:
"ClassName_functionName"
(for a member function). See the Threads Module User's Guide, for more on assigning tag names.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... | |
Functions | |
std::ostream & | operator<< (std::ostream &strm, const RWTraceEventSeverity &crit) |
std::istream & | operator>> (std::istream &strm, RWTraceEventSeverity &crit) |
#define RW_STREAM_TO_STRING | ( | stream | ) |
#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.
#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.
#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.
#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.
#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.
enum RWStaticCtor |
enum RWTraceEventSeverity |
RWTraceEventSeverity contains tracing severity levels; provides basis for convenience macros.
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. |