Sierra Toolkit
Version of the Day
|
The diagnostic writer provides features for the runtime selection of diagnostic output of data and objects. More...
![]() |
The diagnostic writer provides features for the runtime selection of diagnostic output of data and objects.
The runtime diagnostic output selection is achieved utilizing message marking within the source code and selection from the command line or input deck.
The First,
by implementing a dump member function and an operator<< free function, the class may be easily dumped using the << operator. And, second, by assigning appropriate bit masks, the diagnostic writer allows the diagnostic output to be selectively output by the developer or user at runtime.
For Example:
Adding a diagnostic writer to your application allows you to leave diagnostic code in your application which is only seen when desired.
Create a App_DiagWriter_fwd.h
The forward definition file defines the LOG_name bit masks which will be used to select the messages to be written to the diagnostic stream.
Create a App_DiagWriter.h
The diagnostic writer header file defines the parser for parsing the command line and line commands to produce the mask of bits which the user has selected. It also implements the sentry which the application uses to bootstrap the diagnostic writer.
Create a App_DiagWriter.C
The implementation of the parser constructor adds the command line and line command value used to generate the bit mask. Any combinations of bit masks can be given a name. This will simplify specification of commonly grouped options for the user.
Adding a new mask and option name requires only adding the new bit to the enumeration in App_DiagWriter_fwd.h, where 0xmmmmmm00 is a previously unusd bit:
And, adding a mask function call in the parser constructor in the App_DiagWriter.C file.
To incorporate the diagnostic writer into a class or application, there are only a few steps to follow. And, by following these guidelines, the newly created class can fully participate is class data diagnostic output.
In your class header:
Include your application's diagnostic writer forward header.
Declare the dump member function. If this is a base class, be sure the define this member function as virtual if inheritance may be in play.
Define the output insertion operator, operator<< to call your member function.
In your class implementation:
Include your application's diagnostic writer header.
Define your MyClass::dump(Writer &dout) const member function. I suggest using the following as a start:
There are several functions and manipulators which control the selection and formatting of the diagnostic output.
The print mask and the line mask
It is the interaction of the print mask and line mask which determines is the data is to be written to the diagnostic stream. The print mask is set by the user on the command line or in the input deck. The line mask is set by the developer using the m member function and Diag::setlinemask and Diag::resetlinemask manipulators.
As each << operator is executed, the print mask and current line mask are bitwise anded together. If the result of this is non zero, then the line is output.
std::endl and Diag::dendl
Be sure to include std::endl or Diag::dendl at the end of each output line. The end line functions serve as a mask application terminator. In other word, the mask specified using the m member function are in effect until the std::endl of Diag::dendl functions are called on the diagnostic stream. Leaving one out can effect the what is selected to be output.
Diag::push and Diag::pop
The push manipulator pushes the current LineMask onto a stack and the pop manipulator restores the LineMask from the top element of the push stack.
When exception occur, the pops put-to the output stream are skipped by the exception catch block. As a result, the indentation can start to march across the screen. To correct this behavior, add a ThrowSafe sentry within your try block prior to any push operations.