Using RWTraceLevelFilter

SourcePro Core : Threads Module User's Guide : PART III Foundation Packages : The Execution Tracing Package : Using Trace Filters : Using the Predefined Filters : Using RWTraceLevelFilter

The RWTraceLevelFilter filter is used to dynamically filter trace events at runtime. The setLevel() function can be used by your program to reset the filter’s cut-off level at any time during your program’s execution. This filter and two other ways of filtering trace events are compared in Controlling Trace Output.

Example 54 shows how to use the RWTraceLevelFilter class.

Example 54 – Implementing dynamic filtering of trace events

#define RW_USER_TRACE_LEVEL 8 //1

#include <rw/trace/trace.h>

int main()

{

// create trace client that logs messages to cerr

RWTraceOstreamClient myTraceClient(cerr); //2

// create filter that only lets info and more important events

// pass through

RWTraceLevelFilter myTraceLevelFilter(RW_TRACE_LEVEL_INFO); //3

// connect client to level filter

myTraceClient.connect(myTraceLevelFilter); //4

// connect level filter to manager

myTraceLevelFilter.connectToManager(); //5

RW_USER_TRACEABLE_FUNCTION("main”); //6

// generate some trace information

RW_USER_TRACE_INFO("This info level message should be seen.");

RW_USER_TRACE_WARNING("This warning level message should be seen.");

RW_USER_TRACE_ERROR("This error level message should be seen.");

// change the level

myTraceLevelFilter.setLevel(RW_TRACE_LEVEL_ERROR); //7

// generate some more trace information

RW_USER_TRACE_INFO("This info level message should not be seen.");

RW_USER_TRACE_WARNING("This warning level message should”

"not be seen.");

RW_USER_TRACE_ERROR("This error level message should be seen.");

return 0;

}

//1 Compiles in all trace macros by setting the user trace level macro to 8. 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 Creates a normal ostream client to display the trace information.

//3 Instantiates an RWTraceLevelFilter. The constructor takes the maximum level of trace messages to pass through. You can pass an integer level number (see Trace Severity Levels) or use one of the symbolic constants, as in this line. Pass 0 to filter out all trace messages.

//4 Connects the client to the level filter.

//5 Then connects the filter to the trace manager.

//6 Declares the function as traceable, so you can use trace event generation macros in this function.

//7 Changes the cutoff level on the level filter, using the setLevel() function.

The symbolic constants referred to in line //3 are defined in the file rw/trace/RWTraceEventSeverity.h. They cannot be used when setting the RW_USER_TRACE_LEVEL macro, because this macro needs to be set before including any trace header files.

The constants are: RW_TRACE_LEVEL_FATAL, RW_TRACE_LEVEL_ERROR, RW_TRACE_LEVEL_WARNING, RW_TRACE_LEVEL_INFO, RW_TRACE_LEVEL_TEST, RW_TRACE_LEVEL_DEBUG, RW_TRACE_LEVEL_ENTRY and RW_TRACE_LEVEL_NONE. They all map directly to the appropriate severity level. RW_TRACE_LEVEL_NONE filters out all trace messages. It is equivalent to zero.