Rogue Wave banner
Previous fileTop of DocumentContentsIndexNext file

Trace Set Declaration Macros


Global Macros

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

None

Package

Execution Tracing

Header File

#include <rw/trace/userdefs.h>

Description

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.h++ User 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)
RW_TRACE_DEFINE_TRACEABLE_PACKAGE(packageName)

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.h++ User 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)
RW_USER_DEFINE_TRACEABLE_CLASS(className)

RW_USER_DECLARE_TRACEABLE_TEMPLATE_CLASS(className)

RW_USER_DEFINE_TRACEABLE_TEMPLATE_CLASS(className)

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:

Macros for global functions.

Macros for member functions.

Macros for static member functions.

Macros for friend functions.


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.

See Also

Section 6.4, "Using Set Declaration Macros," Threads.h++ User Guide



Previous fileTop of DocumentContentsIndexNext file

©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.