#include <OTC/debug/tracer.hh> class OTC_Tracer {
public:
OTC_Tracer( char const* thePrototype, char const* theFile, u_int theLine, int theEnable=0 );
OTC_Tracer(char const* thePrototype);
~OTC_Tracer();
inline ostream& operator()() const;
inline char const* prototype() const;
inline static OTC_Boolean globalTrace();
inline static void enableGlobalTrace();
inline static void disableGlobalTrace();
inline static int level();
inline static void setLevel(int theLevel);
inline static OTC_Boolean traceIndent();
inline static void enableTraceIndent();
inline static void disableTraceIndent();
inline static OTC_Tracer const* last();
inline OTC_Tracer const* prev() const;
friend ostream& otclib_tracer();
inline static ostream* stream();
inline static void setStream(ostream* theStream);
};
main()
{
OTC_Tracer tracer("main()");
tracer() << "Some info." << endl;
}
This would produce the following output.
@enter - main() Some info. @exit - main()To encourage you to leave debugging statements in your code, a number of macros have been provided, that achieve the above result, but that can be conditionally compiled into your code, only when required. These are the
OTCLIB_DOTRACE
and
OTCLIB_TRACER
macros and are used in the following manner.
main()
{
OTCLIB_DOTRACE("main()");
OTCLIB_TRACER(1) << "Hello World" << endl;
}
It is not necessary to use the OTCLIB_DOTRACE
macro in
a block to be able to use the OTCLIB_TRACER
macro. The
OTCLIB_TRACER
can be used in a block by itself.
To compile the debugging statements into your code, the
preprocessor symbol OTCLIB_TRACE
must be defined, ie.,
-DOTCLIB_TRACE
must be supplied as an argument to the compiler.
The argument to the OTCLIB_TRACER
macro represents a debug
level. If the debug level set in the OTC_Tracer
class is greater
than the value of the argument, and the argument is positive,
the line will be run. When the OTCLIB_DOTRACE
macro is used, the
information generated when the OTC_Tracer
class is created and
destroyed is at level 1
. Instead of the OTCLIB_DOTRACE
macro,
the OTCLIB_MARKBLOCK
macro can be used. This macro takes
two arguments. The first argument is a trace level. The second
argument is the string which will be passed to the construtor
of the OTC_Tracer
class. The OTCLIB_DOTRACE
macro has the
same affect as the OTCLIB_MARKBLOCK
macro, using 1
as the
first argument. A level of 0
indicates that the information
should always be displayed. Higher values should be used for
successive levels of verbosity.
The initial debug level use to to determine what is displayed will
be taken from the environment variable OTCLIB_TRACELEVEL
or will
be set to 0
if this isn't defined or the value in the variable
was negative, ie., by default, no trace output is displayed. If
you use this feature a lot, ie., you are a code developer, you may
wish to permanently set this environment variable to 1
or
higher.
By default, the output from the OTC_Tracer
class is sent to
stderr
via the clog
stream. You can divert the trace output to
a file by setting the environment variable OTCLIB_TRACEFILE
to
be the name of the file. If the file cannot be opened, the output
will still be sent to stderr
.
You can also divert the trace output to a particular file
descriptor. If you wish to do this, the environment variable
OTCLIB_TRACEFD
should be set to the number of the file
descriptor. This can be used to divert the trace output through a
process that filters or highlights information.
Note that if both OTCLIB_TRACEFD
and OTCLIB_TRACEFILE
are
defined, use of the file descriptor will take precedence;
output will not be sent to both places.
If you are using the OTCLIB_TRACER
and OTCLIB_DOTRACE
macros,
you can enable the generation of additional trace information
containing file and line information. This is enabled by setting
the environment variable OTCLIB_TRACEINFO
. The additional
information is output, just before the @enter
line for a
function. The format of the additional information will be:
@location - "file.cc", line 42
OTC_Tracer(
char const* thePrototype,
char const* theFile,
u_int theLine,
int theEnable=0
);
thePrototype
should be a string
describing the function and its arguments.
This string will be printed out with a
message indicating that the function has
been entered. theFile
and theLine
should identify the file and line at which
the OTC_Tracer
class was created. These
would normally be passed automatically,
by the OTCLIB_DOTRACE
macro, the symbols
__FILE__
and __LINE__
. When this
constructor is used, the message indicating
entry and exit of the function is only
displayed if enabled. To enable output,
theEnable
should be 0
or a positive
value. To disable output, theEnable
should be negative.
OTC_Tracer(char const* thePrototype);
thePrototype
should be a string
describing the function and its arguments.
This string will be printed out with a
message indicating that the function has
been entered.
~OTC_Tracer();
inline ostream& operator()() const;
inline char const* prototype() const;
OTCLIB_GLOBALTRACE
as well as through the following
functions.
inline static OTC_Boolean globalTrace();
OTCLIB_TRUE
if a global
tracing is enabled, regardless
of other settings.
inline static void enableGlobalTrace();
inline static void disableGlobalTrace();
inline static int level();
inline static void setLevel(int theLevel);
OTCLIB_NOTRACEINDENT
.
inline static OTC_Boolean traceIndent();
OTCLIB_TRUE
if trace indenting
is enabled.
inline static void enableTraceIndent();
inline static void disableTraceIndent();
inline static OTC_Tracer const* last();
0
if
none are currently in existence.
inline OTC_Tracer const* prev() const;
0
if there wasn't one.
friend ostream& otclib_tracer();
OTCLIB_DOTRACE
or OTCLIB_MARKBLOCK
macro in a function.
inline static ostream* stream();
0
.
inline static void setStream(ostream* theStream);
theStream
for output.
ostream