Tracer Class Reference

A class to help trace program execution. More...

#include <tracer.h>

Collaboration diagram for Tracer:

[legend]List of all members.

Public Types
enum	Kind_t { EMPTY = 0, INCLUDE, EXCLUDE }
	A list can either be empty or a list to include or exclude.
enum	List_t {   KLASS = 0, FUNCTION, ALWAYS_EXCLUDE, KLASS_WATCH,   FUNCTION_WATCH, LISTSIZE }
Public Member Functions
	Tracer (const char *name, const char *klass)
	A inlined ctor for the tracer class.
	~Tracer ()
	An inlined dtor to print the leaving message.
Static Public Member Functions
static void	turnOn (std::ostream *s)
	Turns on the global trace flag and saves away the print stream object.
static void	turnOn (std::ostream &s)
	Turns on the global trace flag and saves away the print stream object.
static void	turnOnEnv (std::ostream *s)
	Check for the environment variable #TRACER_ON to turn on tracing.
static void	turnOnEnv (std::ostream &s)
	Check for the environment variable #TRACER_ON to turn on tracing.
static int	traceOn ()
	Report the status of the trace flag.
static void	turnOff ()
	Turn off the global trace flag.
static void	applyList (NamesList &nl, List_t listType, Kind_t kind)
	Application interface to specify the INCLUDE/EXCLUDE list.
static void	applyList (const char *file, List_t listType, Kind_t kind)
Private Member Functions
void	entering (const char *name, const char *klass)
	Prints entering routine message.
void	leaving ()
	Print the leaving routine message.
Static Private Member Functions
static bool	printMe (Kind_t t, NamesList &s, const char *name)
	Checks name against appropriate list.
static void	buildList (const char *fn, NamesList *nl)
	Build the list from a file name.
static void	cleanup ()
	Clean up after tracing.
static void	cleanup (NamesList *nl)
Private Attributes
char *	mp_name
	Usually the fully qualified routine name.
Static Private Attributes
static char *	msp_watch = 0
	The name of the function we are currently watching.
static int	ms_traceOn = 0
	Global trace flag.
static int	ms_watchOn = 0
	Global watch flag.
static int	ms_watchList = 0
	Global flag which is true iff there is one or more watch lists.
static int	ms_indentLvl = 0
	Static indentation counter.
static std::ostream *	msp_stream = 0
	The stream to send the messages to. It can safely be null.
static NamesList *	msp_list [LISTSIZE]
	An array to hold the vectors of names. LISTSIZE is 3.
static Kind_t	ms_listK [LISTSIZE]
	The type of each of the lists.
static TracerHelper	ms_tracerHelper
	This is here just to force the cleanup of the static member data in the Tracer Class.
Friends
class	TracerHelper
Classes
class	TracerHelper
	Tracer Clean up class. More...

---

Detailed Description

A class to help trace program execution.

Description

This class uses the constructor to print out a message that we are entering a function. The destructor prints out the leaving message. This can happen for all functions that call the ctor or just some of them. Application codes call the ctor with the name of the class and function name. When the ``entering'' function checks to see if the function/class are in the proper list. If so it prints. There are 4 tests that must be true in order to print.

• The global ms_traceOn must be on.
• The function must not be in the always exclude list
• The class must pass through the class list OR
• The function must pass through the function list.

If there is no class list nor a function list then the last two conditions are considered to be true. The last two tests are an OR test. That is if either are true the routine name will be printed.

A list can either be an INCLUDE or EXCLUDE list. That is either the list is an include list and only those members in the list are consider true. Or it is an exclude list and the member of the list are not printed and all other are.

In this way one can say that the member functions of some class will printed in an include list and some member functions of other classes will be in an include list of functions.

---

Member Enumeration Documentation

enum Tracer::List_t

There are 5 list types: class, function and always exclude, klass_watch, function_watch

---

Constructor & Destructor Documentation

Tracer::Tracer (  const char *  name, const char *  klass )  [inline]

A inlined ctor for the tracer class. Description The constructor is inlined for speed. This way we can quickly test to see if the global trace flag is on. If on then the non-inlined member function entering to do the actual printing.

Tracer::~Tracer (   )  [inline]

An inlined dtor to print the leaving message. Description The destructor is inlined for speed. This way we can quickly test to see if the global trace flag is on. If on then the non-inlined member function leaving to do the actual printing. Note that we must test for both the global trace flag and that the routine name exists. In this way we correctly handle the case where the tracing is turned on in the middle of a function that has a Tracer object.

---

Member Function Documentation

void Tracer::applyList (  NamesList &  nl, List_t  listType, Kind_t  kind )  [static]

Application interface to specify the INCLUDE/EXCLUDE list. Description Either an application code specifies a vector of #char* as a list to INCLUDE/EXCLUDE or specifies a file name as the list.

void Tracer::buildList (  const char *  fn, NamesList *  nl )  [static, private]

Build the list from a file name. Description This routine opens the file, then reads the file a line at a time. Each line is assumed to be the name of a routine or class. If it is blank or has the comment marker (the sharp sign). then the line is ignored. After all the line are read in the list is sorted. See Meyer's Effective STL item 23 to see why we use a sorted vector rather than a set.

void Tracer::cleanup (   )  [static, private]

Clean up after tracing. Description All of the non-empty lists must be cleaned up

void Tracer::entering (  const char *  name, const char *  klass )  [private]

Prints entering routine message. Description Here is where we enforce the gauntlet that the printing has to go through. If we are here then global tracing is on. If there are no watch lists then if it passes the three tests in this routine then the routine name is saved away the entering message is printed. If there is a watch list (and it is not already on) then check to see if the current routine or class is what we are watching for. Note that the alwaysExc list is obeyed. So if you ask to watch something which is on the exclude list then nothing will happen. Note that we ignore the regular class and function lists if there is a watch list. If the watch is already on, we pass it through the always exclude list and if it passes we print. So the point of the watch is to print the call tree from the watched routine down. Strange behavior will ensue if an always ignored routine is in the middle of the call tree but not routines that the ignored routine calls. That is there will be a gap in the call tree as the ignored routine will not be printed.

void Tracer::leaving (   )  [private]

Print the leaving routine message. Description Here we don't have to run the gauntlet tests. To print we only need the global trace flag and the name of the routine mp_name to be non-zero. Iff mp_name can the gauntlet be true.

bool Tracer::printMe (  Kind_t  t, NamesList &  s, const char *  name )  [static, private]

Checks name against appropriate list. Description If the list is empty then it return true. It is also true when the list is an include list and the name is found or not found and an exclude list.

static void Tracer::turnOn (  std::ostream &  s  )  [inline, static]

Turns on the global trace flag and saves away the print stream object. Description This must be turned on to start the tracing.

static void Tracer::turnOn (  std::ostream *  s  )  [inline, static]

Turns on the global trace flag and saves away the print stream object. Description This must be turned on to start the tracing.

---

The documentation for this class was generated from the following files:

• tracer.h
• tracer.C

---

Project Hosted By: