Trace Set Declaration Macros

Module:  Threads   Package:  Execution Tracing

Global Macros

• Local Index
• Header File
• Description
• Package Declaration Macros
• Class Declaration Macros
• Function Declaration Macros
• See Also

#include <rw/trace/userdefs.h>

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.

---

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.

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.

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 Section 6.4.3, "Function Declaration Macros," in 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.

Macros for global functions.

• RW_USER_TRACEABLE_FUNCTION("functionTag")

• RW_USER_TRACEABLE_INLINE_FUNCTION("functionTag")

• RW_USER_TRACEABLE_TEMPLATE_FUNCTION("functionTag")

• RW_USER_TRACEABLE_INLINE_TEMPLATE_FUNCTION("functionTag")

This macro family is used in global (non-member) functions. The functionTag is usually the name of the function.

Macros for member functions.

• RW_USER_TRACEABLE_MEMBER("functionTag", className)

• RW_USER_TRACEABLE_INLINE_MEMBER("functionTag", className)

• RW_USER_TRACEABLE_TEMPLATE_MEMBER("functionTag", className)

• RW_USER_TRACEABLE_INLINE_TEMPLATE_MEMBER("functionTag", className)

This macro family is used in member functions. The functionTag is usually the string "ClassName_functionName".

Macros for static member functions.

• RW_USER_TRACEABLE_STATIC_MEMBER("functionTag", className)

• RW_USER_TRACEABLE_INLINE_STATIC_MEMBER("functionTag", className)

• RW_USER_TRACEABLE_TEMPLATE_STATIC_MEMBER("functionTag", className)

• RW_USER_TRACEABLE_INLINE_TEMPLATE_STATIC_MEMBER ("functionTag", className)

This macro family is used in static member functions. The functionTag is usually the string "ClassName_functionName".

Macros for friend functions.

• RW_USER_TRACEABLE_FRIEND("functionTag", className)

• RW_USER_TRACEABLE_INLINE_FRIEND("functionTag", className)

• RW_USER_TRACEABLE_TEMPLATE_FRIEND("functionTag", className)

• RW_USER_TRACEABLE_INLINE_TEMPLATE_FRIEND("functionTag", className)

This macro family is used in friend functions. The functionTag 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.

---

Section 6.4, "Using Set Declaration Macros," in the Threads Module User's Guide

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.