Using Event Generation Macros
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
“Trace Severity Levels” for an explanation of trace severity levels.
NOTE >> 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
“Including Variables in Trace Messages” for information on how to include variables in the output message.
Macros for Global Functions
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.
Macros for Member Functions
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.
Including Variables in Trace Messages
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 << ".” ) );
Trace Macros Example
Example 50 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.
Example 50 – Declaring trace event sets
// 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
}