home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tlx501.zip / DEBUG / TRACE.H < prev   
Text File  |  1996-07-08  |  10KB  |  275 lines
  1. /****************************************************************************
  2.     $Id: trace.h 501.0 1995/03/07 12:26:50 RON Exp $
  3.  
  4.     Copyright (c) 1991-95 Tarma Software Research. All rights reserved.
  5.  
  6.     Project:    Tarma Library for C++ V5.0
  7.     Author:     Ron van der Wal
  8.  
  9.     Tracing macros. As with the other debug macros, #defining NDEBUG
  10.     before #including this file turns them into null code (with a few
  11.     exceptions, noted below).
  12.  
  13.     Trace output may go through one of several trace groups, which allows you
  14.     to separate traces that pertain to different topics. In addition, each
  15.     trace message has a trace level, and trace output may be restricted to
  16.     the messages below a maximum.
  17.  
  18.     The name of a tracing group must conform to C++ identifier syntax, and
  19.     may include any mixture of: '_', letters, and digits. Each trace message
  20.     is prefixed by its group name, so it's probably best to keep the name
  21.     short and descriptive. Usage is as follows:
  22.  
  23.     TLX_TRACE_DECLARE(group);
  24.  
  25.         - Declares the existence of the tracing group; place it in every file
  26.           that produces trace output to the given group. For convenience, the
  27.           declaration may be put in a shared header file.
  28.  
  29.     TLX_TRACE_DEFINE(group);
  30.  
  31.         - Defines the tracing group; use it once for each tracing group.
  32.  
  33.     TLX_TRACE_ON(group);
  34.  
  35.         - Restores tracing for the group at its current maximum level.
  36.           Tracing is on by default.
  37.  
  38.     TLX_TRACE_OFF(group);
  39.  
  40.         - Disables all tracing for the group (it is on by default).
  41.  
  42.     TLX_TRACE_MAX(group,level);
  43.  
  44.         - Sets the maximum tracing level for the group. It will not change
  45.           the ON/OFF setting for the group.
  46.  
  47.     TLX_TRACE_TO(group,os);
  48.  
  49.         - Sets the tracing output stream for the group. By default this is
  50.           the predefined 'cerr' stream.
  51.  
  52.     TLX_TRACE(group, (level, message, parameters...));
  53.  
  54.         - Produces a printf-style formatted trace message through the
  55.           given trace group, presuming 'level' is less than or equal to
  56.           the current maximum tracing level for the group.
  57.  
  58.     TLX_TRACE_INFO(group, (message, parameters...));
  59.  
  60.         - Produces a printf-style formatted trace message with an 'Info'
  61.           prefix through the given trace group.
  62.  
  63.     TLX_TRACE_WARN(group, (message, parameters...));
  64.  
  65.         - Produces a printf-style formatted trace message with a 'Warning'
  66.           prefix through the given trace group.
  67.  
  68.     TLX_TRACE_ERROR(group, (message, parameters...));
  69.  
  70.         - Produces a printf-style formatted trace message with an 'Error'
  71.           prefix through the given trace group.
  72.  
  73.     TLX_TRACE_FATAL(group, (message, parameters...));
  74.  
  75.         - Produces a printf-style formatted trace message with a 'Fatal'
  76.           prefix through the given trace group.
  77.  
  78.     For convenience, the 'TLX' tracing group is predefined and always
  79.     available. Also, the following macros provide for manipulation of all
  80.     tracing groups at once:
  81.  
  82.     TLX_TRACE_ALL();
  83.  
  84.         - Restores tracing for all tracing groups, subject to their
  85.           individual tracing ON/OFF status.
  86.  
  87.     TLX_TRACE_NONE();
  88.  
  89.         - Disables tracing for all groups.
  90.  
  91.     $Log: trace.h $
  92.     Revision 501.0  1995/03/07 12:26:50  RON
  93.     Updated for TLX 5.01
  94.     Revision 1.2  1995/01/31 16:29:02  RON
  95.     Update for release 012
  96.     Added partial support for SunPro C++ compiler
  97.     Revision 1.1  1995/01/05  15:36:04  ron
  98.     Initial revision
  99.  
  100.     Revision 1.1  1994/11/16  15:26:09  ron
  101.     Initial revision
  102.  
  103. ****************************************************************************/
  104.  
  105. #ifndef _TLX_TRACE_H
  106. #define _TLX_TRACE_H
  107.  
  108. #ifndef _TLX_TLX_H
  109. #include <tlx\501\tlx.h>
  110. #endif
  111. #include <stdarg.h>
  112.  
  113. #ifdef NDEBUG
  114. /*---------------------------------------------------------------------------
  115.     Tracing macros when not debugging - resolve to null code
  116. ---------------------------------------------------------------------------*/
  117.  
  118. #define TLX_TRACE_ALL()         ((void)0)
  119. #define TLX_TRACE_NONE()        ((void)0)
  120.  
  121. #define TLX_TRACE_DECLARE(grp)
  122. #define TLX_TRACE_DEFINE(grp)
  123.  
  124. #define TLX_TRACE_ON(grp)       ((void)0)
  125. #define TLX_TRACE_OFF(grp)      ((void)0)
  126. #define TLX_TRACE_MAX(grp,lvl)  ((void)0)
  127. #define TLX_TRACE_TO(grp,os)    ((void)0)
  128.  
  129. #define TLX_TRACE(grp,msg)      ((void)0)
  130. #define TLX_TRACE_INFO(grp,msg) ((void)0)
  131. #define TLX_TRACE_WARN(g,m)     ((void)0)
  132. #define TLX_TRACE_ERROR(g,m)    ((void)0)
  133.  
  134. #define TLX_TRACE_SCOPE(g,n)    ((void)0)
  135.  
  136. #else
  137. /*---------------------------------------------------------------------------
  138.     Tracing macros when debugging - resolve to actual code
  139. ---------------------------------------------------------------------------*/
  140.  
  141. #define TLX_TRACE_ALL()         TLTracer::EnableAll()
  142. #define TLX_TRACE_NONE()        TLTracer::DisableAll()
  143.  
  144. #define TLX_TRACE_DECLARE(grp)  extern TLTracer gTraceGrp ## grp
  145. #define TLX_TRACE_DEFINE(grp)   TLTracer gTraceGrp ## grp(#grp)
  146.  
  147. #define TLX_TRACE_ON(grp)       gTraceGrp ## grp.Enable()
  148. #define TLX_TRACE_OFF(grp)      gTraceGrp ## grp.Disable()
  149. #define TLX_TRACE_MAX(grp,lvl)  gTraceGrp ## grp.SetMaxLevel(lvl)
  150. #define TLX_TRACE_TO(grp,os)    gTraceGrp ## grp.SetStream(os)
  151.  
  152. #define TLX_TRACE(grp,arg)      gTraceGrp ## grp. \
  153.                                 SetLocus(__FILE__,__LINE__).TraceFmt arg
  154. #define TLX_TRACE_INFO(grp,arg) gTraceGrp ## grp. \
  155.                                 SetLocus(__FILE__,__LINE__).InfoFmt arg
  156. #define TLX_TRACE_WARN(grp,arg) gTraceGrp ## grp. \
  157.                                 SetLocus(__FILE__,__LINE__).WarningFmt arg
  158. #define TLX_TRACE_ERROR(grp,arg) gTraceGrp ## grp. \
  159.                                 SetLocus(__FILE__,__LINE__).ErrorFmt arg
  160. #define TLX_TRACE_FATAL(grp,arg) gTraceGrp ## grp. \
  161.                                 SetLocus(__FILE__,__LINE__).FatalFmt arg
  162.  
  163. #define TLX_TRACE_SCOPE(grp,n)  TLScopeTracer _ ## __LINE__(gTraceGrp ## grp, \
  164.                                 n, __FILE__, __LINE__)
  165.  
  166. #endif  // NDEBUG
  167.  
  168. /*---------------------------------------------------------------------------
  169.     Auxiliary declarations
  170. ---------------------------------------------------------------------------*/
  171.  
  172. class _TLXCLASS TLTracer
  173. {
  174.     // To allow global disabling/enabling of trace output, we have a
  175.     // static flag.
  176.  
  177.     static bool         sEnabled;       // Tracing globally enabled?
  178.  
  179.     // For identification, we store the group name. We also keep track of
  180.     // the current maximum tracing level for the group and its output
  181.     // stream. Next to the maximum tracing level, we remember the on/off
  182.     // status of the group as well.
  183.  
  184.     const char *        mGroupName;     // Name of the tracing group
  185.     int                 mMaxLevel;      // Maximum tracing level
  186.     bool                mEnabled;       // Group enabled?
  187.     ostream *           mOStream;       // Output stream
  188.  
  189.     // To allow display of the filename and line number of the origin of the
  190.     // trace message and still use variable-length argument lists (and ditto
  191.     // macros), we store the message locus just prior to the call to the
  192.     // actual trace function.
  193.     //
  194.     // The locus is local to the group to reduce (but not eliminate) the
  195.     // chances of a conflict in multi-threaded environments.
  196.  
  197.     const char *        mFileName;      // Filename of the trace message
  198.     int                 mLineNo;        // Line number in the file
  199.  
  200. public:
  201.     TLTracer(const char *);
  202.     ~TLTracer();
  203.  
  204.     // Global and local trace enabling and level setting.
  205.  
  206.     static void         EnableAll();
  207.     static void         DisableAll();
  208.     void                Enable();
  209.     void                Disable();
  210.     void                SetMaxLevel(int);
  211.     void                SetStream(ostream &);
  212.  
  213.     // Formatted trace output functions
  214.  
  215.     void __cdecl    TraceFmt(int, const char *, ...);
  216.     void __cdecl    InfoFmt(const char *, ...);
  217.     void __cdecl    WarningFmt(const char *, ...);
  218.     void __cdecl    ErrorFmt(const char *, ...);
  219.     void __cdecl    FatalFmt(const char *, ...);
  220.  
  221.     // Helper function to store the locus of the message that follows
  222.  
  223.     TLTracer &          SetLocus(const char *, int);
  224.  
  225. private:
  226.     // Implementation helper functions
  227.  
  228.     bool                CanTrace(int) const;
  229.     void                VPrintf(const char *, const char *, va_list);
  230. };
  231.  
  232. class _TLXCLASS TLScopeTracer
  233. {
  234.     TLTracer &          mTracer;
  235.     const char *        mName;
  236.     const char *        mFile;
  237.     int                 mLine;
  238.  
  239. public:
  240.     TLScopeTracer(TLTracer &, const char *, const char *, int);
  241.     ~TLScopeTracer();
  242. };
  243.  
  244. inline TLScopeTracer::TLScopeTracer(
  245.     TLTracer &  aTracer,
  246.     const char *aName,
  247.     const char *aFile,
  248.     int         aLine)
  249. : mTracer(aTracer), mName(aName), mFile(aFile), mLine(aLine)
  250. {
  251.     mTracer.SetLocus(mFile, mLine);
  252.     mTracer.InfoFmt("Entering scope %s...", mName);
  253. }
  254.  
  255. inline TLScopeTracer::~TLScopeTracer()
  256. {
  257.     mTracer.SetLocus(mFile, mLine);
  258.     mTracer.InfoFmt("Leaving scope %s...", mName);
  259. }
  260.  
  261. /*---------------------------------------------------------------------------
  262.     Inline and other definitions
  263. ---------------------------------------------------------------------------*/
  264.  
  265. //----- Predefined tracing group 'TLX'
  266.  
  267. extern _TLXDATA TLTracer        gTraceGrpTLX;
  268.  
  269. //----- TLTracer
  270.  
  271. inline bool TLTracer::CanTrace(int aLevel) const
  272.     { return sEnabled && mEnabled && aLevel <= mMaxLevel; }
  273.  
  274. #endif  // _TLX_TRACE_H
  275.