Event generation macros are used to actually generate the trace events in your code. You can use as many event generation macros as you want in any function that has been declared traceable. The event generation macros come in two varieties, one for member functions and the other for global, static member, and friend functions.
Each macro corresponds to a trace severity level. See Section 6.1.3 for an explanation of trace severity levels.
No ENTRY/EXIT macros are provided, because these trace events are generated by the function declaration macros.
The macros take a msg parameter, which is a string containing the message to be logged. See Section 6.5.3 for information on how to include variables in the output message.
RW_USER_TRACE_FATAL("msg")
RW_USER_TRACE_ERROR("msg")
RW_USER_TRACE_WARNING("msg")
RW_USER_TRACE_INFO("msg")
RW_USER_TRACE_TEST("msg")
RW_USER_TRACE_DEBUG("msg")
These macros are normally used in global, static member, and friend functions, which don't require an object for invocation. The macros can be used in member functions, but the trace message will not include the address of the current object.
RW_USER_TRACE_OBJECT_FATAL("msg")
RW_USER_TRACE_OBJECT_ERROR("msg")
RW_USER_TRACE_OBJECT_WARNING("msg")
RW_USER_TRACE_OBJECT_INFO("msg")
RW_USER_TRACE_OBJECT_TEST("msg")
RW_USER_TRACE_OBJECT_DEBUG("msg")
These macros with the word OBJECT in their names are used in member functions. The trace message includes the address of the object that the member function is called on. Using these macros in non-member functions results in compile errors.
The Execution Tracing package provides a helper macro to allow the use of streaming syntax in trace messages. The RW_STREAM_TO_STRING(stream) macro allows the concatenation of strings and variables, much like the insertion operator for an ostream works. Here's an example:
RW_STREAM_TO_STRING( "The number of cups is " << numCups << "." ); |
Assuming numCups is in scope and has the value 5, the macro expands to the string "The number of cups is 5." This macro is normally used as the parameter to the event generation macros:
RW_USER_TRACE_INFO( RW_STREAM_TO_STRING( "The number of cups is" << numCups << "." ) ); |
Example 53 uses the set declaration macros with the event generation macros in a typical class. A more comprehensive example can be found in buildspace\examples\trace\example1.cpp.
// File: CoffeeRobot.h
#define RW_USER_TRACE_LEVEL 8 //1
#include <rw/trace/trace.h>
RW_USER_DECLARE_TRACEABLE_CLASS(CoffeeRobot) //2
Class CoffeeRobot
{
CoffeeRobot() {
RW_USER_TRACEABLE_INLINE_MEMBER("CoffeeRobot_ctor",
CoffeeRobot); //3
}
void makeCoffee(int cups);
};
// File: CoffeeRobot.cpp
#include "CoffeeRobot.h"
RW_USER_DEFINE_TRACEABLE_CLASS(CoffeeRobot) //4
void
CoffeeRobot::makeCoffee(int cups)
{
RW_USER_TRACEABLE_MEMBER("CoffeeRobot_makeCoffee",
CoffeeRobot) //5
RW_USER_TRACE_OBJECT_DEBUG(
RW_STREAM_TO_STRING("Number of cups = " << cups ) ); //6
. . .
}
void globalHelper( void )
{
RW_USER_TRACEABLE_FUNCTION( "globalHelper" ); //7
RW_USER_TRACE_INFO("I'm here to help"); //8
}
|
| //1 | This line sets the maximum trace level to compile into the code. To compile in all the trace macros, the level is set to the maximum 8 (Entry/Exit). You could also define the trace level on the command line for your compiler, using the -DRW_USER_TRACE_LEVEL=8 flag. |
| //2 | This macro declares the class CoffeeRobot as traceable. The declaration enables you to set an environment variable CoffeeRobot to ON or OFF to toggle tracing for this class at runtime. Remember to use the appropriate DEFINE macro in the implementation file (see Section 6.4.2). |
| //3 | This macro declares the constructor as traceable and a member of the CoffeeRobot class (for tracing purposes). The declaration enables you to set an environment variable CoffeeRobot_ctor to ON or OFF to toggle tracing for this function at runtime. This macro automatically generates ENTRY and EXIT events when this function is called. Note the use of the INLINE version of the macro, because this constructor is defined inline. |
| //4 | This macro matches the DECLARE macro in line //2. This DEFINE macro must appear in an implementation file exactly once for each class declared as traceable. If this macro is not used, the linker reports that some symbols are undefined. |
| //5 | This macro declares the member function makeCoffee() as traceable and as a member of the CoffeeRobot class (for tracing purposes). The macro also enables you to set an environment variable CoffeeRobot_makeCoffee to ON or OFF to toggle tracing for this function at runtime. The macro automatically generates ENTRY and EXIT events when this function is called. |
| //6 | This macro generates a DEBUG event for this member function. Because it is a member function, the OBJECT version of the macro is used. This macro uses the RW_STREAM_TO_STRING macro to include the value of the parameter in the trace message. |
| //7 | This macro declares the function as traceable and enables you to set an environment variable named globalHelper to ON or OFF to toggle tracing for this function at runtime. ENTRY and EXIT events are generated automatically when this function is called. Note the macro used for this global function. |
| //8 | This macro generates an INFO event for this function. The macro name does not contain the word OBJECT, because this is not a member function. |
Copyright © Rogue Wave Software, Inc. All Rights Reserved.
The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.