Using Package-level Tracing
This section describes how to create trace macros for your own packages. A package is simply a group of classes and functions that represent some logical aspect of an application. The Execution Tracing package provides one default package definition, called rw_user, for tracing purposes. Each package needs a set of trace macros that refer to it, and those macro names should include a prefix that identifies the package. Thus, all the predefined set declaration and event generation macros, as well as the RW_USER_TRACE_LEVEL macro, begin with the prefix RW_USER.
Each new package that you define needs its own version of the RW_USER macros, whose names begin with their associated package. To simplify the process of defining these macros, the Execution Tracing package provides a file that you can use as a template. The rw/trace/package_template.h file contains all the macro definitions, as well as the RW_DECLARE_TRACEABLE_PACKAGE macro.
To create your own package, complete these steps:
1. Create a macro header file to declare your package and define a set of macros for it.
a. Make a copy of the template file rw/trace/package_template.h with a different name (for example, mypackage_trace.h).
b. Edit the file to change PACKAGE_NAME to your package name in uppercase and package_name to your package name in lowercase. You could use a sed script similar to this:
s/PACKAGE_NAME/MYPACKAGE/g
s/package_name/mypackage/g
See any Threads Module pkgdefs.h file in the rw_root subdirectories for examples of these macro header files.
2. Define your package by putting the macro RW_TRACE_DEFINE_TRACEABLE_PACKAGE(mypackage) (package name in lowercase) in one of your implementation files that includes mypackage_trace.h.
For examples, see any Threads Module pkgdefs.cpp file in the rw_root subdirectories.
3. Use your package macros in your code exactly as you would have used the RW_USER macros. Use the macros MYPACKAGE_DECLARE_TRACEABLE_CLASS, MYPACKAGE_TRACEABLE_MEMBER, and so on, in your classes and functions in MyPackage.
4. Control the level of tracing compiled into your package with the MYPACKAGE_TRACE_LEVEL macro, just as you would with the RW_USER_TRACE_LEVEL macro. MYPACKAGE_TRACE_LEVEL must be defined before including your macro header file, mypackage_trace.h.
5. Set the environment variable mypackage to ON or OFF to control tracing of MyPackage at runtime.
You can control all trace output from your package by setting the environment variable mypackage (your package name in lowercase) to ON or OFF.
