4.18. trace()/ trace_with_macro() Macros

4.18.1. DEFINITION

#define trace(message)
#define trace_with_mask(message, mask)
	  

4.18.2. USAGE

Both macros are used to trace function calls chain in C++ programs. Two records are written to the log file: an entrance marker before any other statement is executed, and an exit marker after the last statement is executed:

trace_with_mask() has a second argument to supply the debug mask. Every class (or group of related classes) in libassa library is assigned two masks: one for tracing debug messages that might be of interest to the library's maintainer, and another is for tracing every member function call of the class. For complete list of masks, see Section 1.5.4.

For example, Reactor class has two debug masks assigned to it: REACT and REACTTRACE (see assa/LogMask.h file for details). First is used for logging debug messages through the code to help debug its execution:

TimerId 
Reactor::
registerTimerHandler (EventHandler* eh_, TimeVal& timeout_)
{
    trace("Reactor::registerTimerHandler");

    // some code ...

    DL((REACT,"TIMEOUT_EVENT: (%d,%d)", timeout_.sec(), timeout_.msec()));
 
    // some more code ...
}
	  

REACCTRACE mask is used in every member function as a second argument of trace_with_mask() to trace function execution sequence:

void foo ()
{
    trace_with_mask("foo",RACTTRACE);
    DL((REACT,"I am foo \n"));
}

bool 
Reactor::
registerIOHandler (EventHandler* eh_, int fd_, EventType et_)
{
   trace_with_mask("Reactor::registerHandler(I/O)",REACTTRACE);

   foo (); 
}
	  

When REACTTRACE mask is turned on, then following messages is logged to the log file upon entering and exiting function registerIOHandler():

--v-- Reactor::registerHandler(I/O) --v--
    --v-- foo --v--
    [foo] I am foo
    --^-- foo --^--
--^--Reactor::registerHandler(I/O)--^--
	  

This allows to optionally trace function calls sequence in the program and debug complicated scenarios that might occur in day-to-day operations.

Macro trace() is a shortcut that uses TRACE as a trace mask.