doc.h

//----------------------------------------------
// traceString documentation static const char* myName = "Foo::Bar(int a)"; TRACER(t,myName,"Foo"); /* %TRACE% */
         // rest of routine
       }\endverbatim

    Here the idea is that TRACER is a developer supplied macro that,
    when turned on, will print the name of routine to aid debugging.

    A code instrumented by traceString can be re-instrumented repeatly.  In
    this way it can be used as development continues so that when 
    "int Foo::Bar(int a)" becomes  "int Foo::Bar(int* a)" the tool can
    make the changes to the variable "myName" rather than the developer.

    A developer has control over what traceString places in the source
    code via a pattern file.  This file describes how the function name
    should be expanded.  The above pattern was:

       \verbatim
       static const char* myName = "$(FQNAME)"; TRACER(t,myName,"$(CLASS)");
       \endverbatim

    Where "\$(FQNAME)" is the "fully qualified" name of the routine, that is
    the name of the routine and its arguments.  The name of the routine
    with out is arguements is available (\$(NAME): "Foo::bar") as well the
    class name ($(CLASS): "Foo").  If the pattern line was 

       \verbatim
       FUNC_TRACE("$(NAME)");
       \endverbatim

    then the expansion would be:
            
       \verbatim
       int Foo::bar(int a)
       { /* %TRACE% */ FUNC_TRACE("Foo::bar"); /* %TRACE% */
         // rest of routine
       }\endverbatim

    There can be more than one pattern line in the pattern file.  There is
    a default pattern and other named patterns.  So the pattern file might
    look like:

       \verbatim
       default: static const char* myName = "$(FQNAME)";TRACER(t,myName,"$(CLASS)");
       ifdef  : \n#ifdef DEBUG\nstatic const char* myName = "$(FQNAME)";\n#endif\n
       FT     : FUNC_TRACE("$(NAME)");
       FC     : FT_wClass("$(FQNAME)","$(CLASS)");
       None   :
       \endverbatim

    If the source code originally looked like this:

       \verbatim
       int Foo::bar(int a)
       {
         // rest of routine
       }
       int Foo::baz(double b)
       { /* %TRACE[FT]% */ /* %TRACE% */
         // rest of routine
       }
       int Foo::biz(string b)
       { /* %TRACE[FC]% */ /* %TRACE% */
         // rest of routine
       }
       int Foo::getSomething()
       { /* %TRACE[None]% */ /* %TRACE% */
         // rest of routine
       }
       int Foo::foo()
       { 
         /* %TRACE[ifdef]% */ /* %TRACE% */
         // rest of routine
       }

       \endverbatim

    It would be converted to this:

       \verbatim
       int Foo::bar(int a)
       { /* %TRACE% */ static const char* myName = "Foo::Bar(int a)"; TRACER(t,myName,"$(CLASS)"); /* %TRACE% */
         // rest of routine
       }
       int Foo::baz(double b)
       { /* %TRACE[FT]% */ FUNC_TRACE("Foo::baz"); /* %TRACE% */ 
         // rest of routine
       }
       int Foo::biz(string b)
       { /* %TRACE[FC]% */ FT_wCLASS("Foo::biz(string b)","Foo"); /* %TRACE% */
         // rest of routine
       }
       int Foo::getSomething()
       { /* %TRACE[None]% */ /* %TRACE% */
         // rest of routine
       }
       int Foo::foo()
       { 
         /* %TRACE[ifdef]% */ 
         #ifdef DEBUG
         static const char* myName = "Foo::foo()";
         #endif
         /* %TRACE% */
         // rest of routine
       }
       \endverbatim

    Thus, if there is no trace string already in the function, the default pattern is
    used.  A named pattern is specified with:

      \verbatim
      /* %TRACE[FT]% */ /* %TRACE% */
      \endverbatim

    where the string in the square brackets controls which pattern is
    used.  The "Foo::getSomething()" shows the use of the "None" pattern
    where no extra code was placed that function.

    traceString will also expand `\n' in the pattern file.  In this
    way a single line pattern can expand to multi-line code. In this
    way C-preprocessor directives like #ifdef can be used.

    The tool "traceString" is fast.  It is written in C++ and flex.  On a Pentium 4
    it converted  23000 lines of code in 61 files in 0.1 seconds.
    

    \subsection example Tracer Example

    This package also contains a tracer package to control tracing.
    Applications can freely include this if they choose to help will
    tracing the applications tracing program execution.

    "tracer" depends on C++ ability to have user code construct objects
    that are automatically deleted at their end of scope.  So we
    construct a tracer object at the beginning of a routine and at the
    end of the tracer object's lifetime the destructor is called and
    we print a message that we are leaving the routine.

    We may wish to have a finer control on which routines that print
    out.  There are four tests that must be true in order that a
    routine prints an entering/leaving message.  (ignoring watch
    lists, see watch list discussion that follows)

    a) The static member variable must be turned on.  Printing will only
       occur if it is true.

    b) The routine name must not be in the always_excluded list

    c) There is a routine list which is either an include or an
       exclude list.  To be printed the routine name must be on
       include list or not on the exclude list.  This list of routines
       can only be either an include list or an exclude list not both.
       If there is no list then this is ignored.

    d) There is a class list which is either an include or an
       exclude list.  To be printed the class name must be on
       include list or not on the exclude list.  This list of classes
       can only be either an include list or an exclude list not both.
       If there is no list then this is ignored.


    Watch list rules:  

    The purpose of the watch list to print out the call tree execution
    starting at watched routine.  That is a routine or class listed in
    a watch list will print out the routine and all routines called
    until the execution returns back to that routine.    To print
    following has to be true.

    a) Tracing must be turned on

    b) A routine or class must be on the appropriate watch list
       (FUNCTION_WATCH for functions and KLASS_WATCH for classes)

       OR

       called by a watched routine

    c) the regular class and function include/exclude lists are
       ignored.

    d) The always exclude list is obeyed.

      \verbatim
      \#include <iostream>
      \#include "tracer.h"

      void c(int i)
      {
        /* %TRACE% */ static const char* myName = "c(int i)";  TRACER(tr, myName,""); /* %TRACE% */
        std::cout << "In middle of c " << i << "\n";
      }

      void b(int i)
      {
        /* %TRACE% */ static const char* myName = "b(int i)";  TRACER(tr, myName,""); /* %TRACE% */ 
        std::cout << "In middle of b " << i << "\n";
        c(i+1);
      }

      void a(int i)
      {
        /* %TRACE% */ static const char* myName = "a(int i)";  TRACER(tr, myName,""); /* %TRACE% */ 
        std::cout << "In middle of a " << i << "\n";
        b(i+1);
      }


      int main()
      {
        /* %TRACE% */ static const char* myName = "main()";  TRACER(tr, myName,""); /* %TRACE% */ 
        NamesList nl;

        nl.push_back("e(int i)");
        nl.push_back("d(int i)");
        nl.push_back("c(int i)");
        nl.push_back("f(int i)");

        Tracer::turnOnEnv(&std::cout);

        std::cout << "\nTesting Function exclude list\n";
        Tracer::applyList(nl,Tracer::FUNCTION, Tracer::EXCLUDE);
        a(1);

        std::cout << "\nTesting Function watch list\n";
        watchList.push_back("b(int i)");
        Tracer::applyList(watchList,Tracer::FUNCTION_WATCH, Tracer::INCLUDE);
        a(1);
      }
      \endverbatim

      The above code shows the general behavior.  The main routine
      builts a list of routines to ignore then it calls
      "Tracer::turnOnEnv(&std::cout);" to check to see if the
      environment variable TRACER_ON is defined with some value.  If
      so then program execution is printed.  In the above execution
      when traceing is on is:
        
      \verbatim
      Testing Function exclude list

      > a(int i)
      In middle of a 1

        > b(int i)
      In middle of b 2
      In middle of c 3

        < b(int i)

      < a(int i)

      Testing Function watch list
      In middle of a 1

      > b(int i)
      In middle of b 2

        > c(int i)
      In middle of c 3

        < c(int i)

      < b(int i)
      \endverbatim

      Note that the entering and leaving messages are indented and
      that the "c(int i)" routine did not print because it was on the
      exclude list for the first call to a(1).

      In the watch list execution, a is ignored because it is not on
      the watch list  but "b(int i)" is.   Note that "c(int i)" is
      printed because it is called by "b(int i)" and a watch list
      ignores the "FUNCTION" and "KLASS" include/exclude lists.

 */

// Local Variables:
// mode: html
// End:

---

Project Hosted By: