NAME
OTC_Tracer -
Class for tracing execution path through a function.
SYNOPSIS
#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);
};
CLASS TYPE
Concrete
DESCRIPTION
Used to trace execution path through a function, by printing out
messages when an instance of the class is created, and
automatically, when the class is destroyed on function exit.
An example of how the class is used.
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
CONSTRUCTION
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.
DESTRUCTION
~OTC_Tracer();
Prints out a message to say that the
function is being exited.
STREAM ACCESS
inline ostream& operator()() const;
Returns the stream to which the trace
output will be sent.
FUNCTION NAME
inline char const* prototype() const;
GLOBAL TRACE
Enabling of a global trace can be done by setting the environment
variable OTCLIB_GLOBALTRACE as well as through the following
functions.
inline static OTC_Boolean globalTrace();
Returns OTCLIB_TRUE if a global
tracing is enabled, regardless
of other settings.
inline static void enableGlobalTrace();
inline static void disableGlobalTrace();
TRACE LEVEL
A global trace will override the effect of these settings and will
result in everything being displayed.
inline static int level();
inline static void setLevel(int theLevel);
TRACE INDENT
Trace indenting is by default turned on. You can turn identing
off by setting the environment variable OTCLIB_NOTRACEINDENT.
inline static OTC_Boolean traceIndent();
Returns OTCLIB_TRUE if trace indenting
is enabled.
inline static void enableTraceIndent();
inline static void disableTraceIndent();
Disables trace indenting.
STACK TRACE
inline static OTC_Tracer const* last();
Returns a pointer to the most recently
created instance of this class, or 0 if
none are currently in existence.
inline OTC_Tracer const* prev() const;
Returns a pointer to the instance
of this class created prior to this
instance or 0 if there wasn't one.
STAND ALONE TRACE
friend ostream& otclib_tracer();
Allows you to do away with having either a
OTCLIB_DOTRACE or OTCLIB_MARKBLOCK
macro in a function.
STREAMS
inline static ostream* stream();
Returns the stream to which trace output
is currently being directed. If the
trace facility hasn't yet been initialised
this will return 0.
inline static void setStream(ostream* theStream);
Set the trace facility to use theStream
for output.
SEE ALSO
ostream
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1991 1992 1993 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED