//#error REDO, REDO REDO, for C only! /*============================================================================= * drt/sys/kdebug.h * DRT basic runtime debugging (tracing) functions. * * Usage * DEBUGGING OUTPUT * ------------------------------------ #error REDO, REDO REDO, for C only! ------------------------------------ * * All objects of type drt_trace share a common debugging trace output * file (.s_outf); all debugging output should be written to it. * * If the output file (.s_outf) is null, then the debugging output has not * yet been opened or has been suspended (see the suspend() and resume() * member functions). * This pointer is checked by the DE() macro. * * FUNCTION TRACING * * Constructing an object of type drt_trace causes the .enter() member * function to be called, which writes an "enter" line to the debugging * output. * Likewise, destructing such an object causes the .leave() member * function to be called, which writes an "exit" line to the debugging * output. * Thus, declaring an auto variable object of this class type results in * the runtime tracing of the entry and exit from a function. * * To trace the entry into and exit out of a member function: * * Type Class::foo() * { * drt_trace_t dbg("Class::foo", this); * ...body of function... * } * * To trace the entry and exit of a nonmember function: * * /*static*\ Type Class::bar() * { * drt_trace_t dbg("Class::bar"); * ...body of function... * } * * TRACING GROUPS * * Functions can be arranged into debugging groups; each group shares an * drt_trace_grp_t object, which contains a name for whole group. * The object should be a static object, either file-static or a private * static class member. * * To define a tracing group object: * * static drt_trace_grp_t Foo::s_grp("Name", * __FILE__, __DATE__, __TIME__); * * A tracing group may also belong to a supergroup, which is itself simply * another tracing group object: * * static drt_trace_grp_t Foo::s_grp(Bar::s_grp, "Name", * __FILE__, __DATE__, __TIME__); * * To trace the entry and exit of a member function for this group: * * Type Class::foo() * { * public: * drt_trace_t dbg(s_grp, "Class::foo", this); * ...body of function... * } * * Tracing a nonmember function is almost the same: * * drt_trace_t dbg(s_grp, "Class::bar"); * * If all of the member functions of a class are to be treated as a single * group (i.e., the class is the group), then the function entry/exit * tracing can be simplified somewhat: * * static drt_trace_grp_t Class::s_grp("Class", * __FILE__, __DATE__, __TIME__); * * Type Class::foo() * { * drt_trace_t dbg(s_grp, "foo", this); * ...body of function... * } * * STATEMENT TRACING * * To execute a statement if and only if the debugging output stream is * open (i.e., if debugging output is enabled): * * DE(expr); * * This is equivalent to: * * #if DEBUG * if (drt_trace_s_outf != null) * expr; * #endif * * To execute a statement if and only if compile-time debugging is * enabled: * * DS(stmt); * * To execute a group of statements if and only if compile-time debugging * is enabled without using the debugging macros: * * #if DEBUG * stmt; * stmt; * #endif * * TRACING OUTPUT * * To write formatted output (ala printf()) to the debugging output * stream if and only if compile-time and run-time debugging is enabled: * * DE(drt_trace_print("count=%d\n", count)); * Or: * DE(dbg.print("count=%d\n", count)); /* Uses 'dbg' object *\ * Or: * DE(dbg << "count=" << count << dbg.eoln); * * Caveats * These classes (DrtTraceXxx) do not inherit class DrtMagic, as they are * meant to be very primitive class types. * * See also * "sdebug.hpp" * * History * 0.01, 1998-04-16, David R Tribble. * First cut. * * 0.02, 1998-04-18, David R Tribble. * Added class DrtTraceGroup. * * 0.03, 1998-04-23, David R Tribble. * Added class DrtTraceInfo. * * 0.04, 1998-04-24, David R Tribble. * Renamed from "scdebug.h" to "jdebug.h". * * 0.05, 1998-05-30, David R Tribble. * Changed filename prefix from "j" to "k". * * 0.06, 1998-05-30, David R Tribble. * Added members .m_file, .m_cdate, and .m_ctime to class DrtTraceGroup. * * 0.07, 1998-05-30, David R Tribble. * Changed DrtTraceGroup reference args to be pointers instead. * * 0.08, 1998-06-23, David R Tribble. * Changed prototype for DrtTraceGroup::enter(). * * 0.09, 1999-02-27, David R Tribble. * Move to drt/sys/. * * 0.10, 1999-03-19, David R Tribble. * Converted from C++ to C. * * Copyright ©1998-1999, by David R. Tribble, all rights reserved. * See "drt/sys/copyr.txt" for more information. *----------------------------------------------------------------------------*/ #ifndef drt_sys_kdebug_h #define drt_sys_kdebug_h 1 #ifdef __cplusplus extern "C" { #endif /* Identification */ #ifndef NO_H_IDENT static const char drt_sys_kdebug_h_id[] = "@(#)drt/sys/kdebug.h 0.10"; #endif /* System includes */ #ifndef drt_std_stdio_h #include #define drt_std_stdio_h 1 #endif /* Special includes */ #ifndef drt_sys_kdefs_h #include "kdefs.h" #endif /* Local wrappers */ #include "klib1.h" /* Control macro constants */ #ifndef DEBUG #define DEBUG 0 #elif DEBUG-0 <= 0 #undef DEBUG #define DEBUG 0 #endif /* Function macros */ #if DEBUG #define DE(e) (drt_trace_s_outf != null ? (void)(e) : (void)0) #define DS(s) s #define DW() drt_trace_where(__FILE__, __LINE__) #else #define DE(e) ((void)0) #define DS(s) 0 #define DW() ((void)0) #endif #if DEBUG >= 2 #define DE2(e) DE(e) #else #define DE2(e) ((void)0) #endif #if 0 /* fake it for now, TEMPORARY */ /*----------------------------------------------------------------------------- * Class drt_trace_grp_t * Debugging group class. * This class implements very simple runtime debug tracing functions. * * Caveats * This class does not inherit class DrtMagic. * * See also * The notes in this file for more details about how to use this class. * * History * 100, 1998-04-18, David R Tribble. * First cut. * * 101, 1998-05-30, David R Tribble. * Added .m_magic and .m_vers members. * Added members .m_file, .m_cdate, and .m_ctime. * * 102, 1998-06-23, David R Tribble. * Added .m_enable member. * * 103, 1998-09-25, David R Tribble. * Added .m_sup member. * Replaced .m_enable member with .m_flags. * * 104, 1998-11-04, David R Tribble. * Added .m_color coloring bits member. *----------------------------------------------------------------------------*/ #define drt_trace_grp_t_VS 104 // Class version class DRTEXPORT drt_trace_grp_t { public: // Shared constants static const int VS; // Class version static const unsigned int MAGIC; // Class magic number public: // Shared types typedef drt_trace_grp_t Type; // This type public: // Constants enum Flags // Control bitflags { F_ENABLE = 0x0001, // Enable group tracing output F_COLOR = 0x0002, // Enable trace coloring F__DFL = 0x0000 // Default settings }; public: // Variables unsigned int m_magic; // Class magic number int m_vers; // Class version number drt_trace_grp_t * m_sup; // Parent supergroup const char *const m_name; // Group (e.g., class) name const char *const m_file; // Source filename (__FILE__) const char *const m_cdate; // Compilation date (__DATE__) const char *const m_ctime; // Compilation time (__TIME__) unsigned int m_flags; // Control bitflags public: // Functions /*void*/ ~drt_trace_grp_t(); // Destructor /*void*/ drt_trace_grp_t(const char *name, const char *file, const char *cdate, const char *ctime); // Constructor /*void*/ drt_trace_grp_t(drt_trace_grp_t &sup, const char *name, const char *file, const char *cdate, const char *ctime); // Constructor /*void*/ drt_trace_grp_t(const char *name); // Constructor, simplified /*void*/ drt_trace_grp_t(drt_trace_grp_t &sup, const char *name); // Constructor, simplified bool isEnabled() const; // Group output is enabled void setColor(int col); /* Set group's tracing color */ private: // Shared variables static const drt_trace_grp_t * s_list; // List of all trace groups private: // Variables const drt_trace_grp_t * m_next; // Next group in list unsigned long m_color; // Trace coloring bits private: // Functions // Constructors and destructors not provided /*void*/ drt_trace_grp_t(); // Default constructor /*void*/ drt_trace_grp_t(const drt_trace_grp_t &o); // Copy constructor const drt_trace_grp_t & operator =(const drt_trace_grp_t &o); // Assignment operator private: // Operators // Operators not provided void * operator new(size_t n); void * operator new[](size_t n); void operator delete(void *o); void operator delete[](void *o); }; // Inline member functions inline /*void*/ drt_trace_grp_t::~drt_trace_grp_t() { // No members to de-initialize } inline /*void*/ drt_trace_grp_t::drt_trace_grp_t(const char *name, const char *file, const char *cdate, const char *ctime): m_magic(MAGIC), m_vers(VS), m_sup(null), m_name(name), m_file(file), m_cdate(cdate), m_ctime(ctime), m_flags(F__DFL), m_next(null) { #if DEBUG // Insert this group into the list m_next = s_list; s_list = this; #endif } inline /*void*/ drt_trace_grp_t::drt_trace_grp_t(drt_trace_grp_t &sup, const char *name, const char *file, const char *cdate, const char *ctime): m_magic(MAGIC), m_vers(VS), m_sup(&sup), m_name(name), m_file(file), m_cdate(cdate), m_ctime(ctime), m_flags(F__DFL), m_next(null) { #if DEBUG // Insert this group into the list m_next = s_list; s_list = this; #endif } inline /*void*/ drt_trace_grp_t::drt_trace_grp_t(const char *name): m_magic(MAGIC), m_vers(VS), m_sup(null), m_name(name), m_file(""), m_cdate(""), m_ctime(""), m_flags(F__DFL), m_next(null) { #if DEBUG // Insert this group into the list m_next = s_list; s_list = this; #endif } inline /*void*/ drt_trace_grp_t::drt_trace_grp_t(drt_trace_grp_t &sup, const char *name): m_magic(MAGIC), m_vers(VS), m_sup(&sup), m_name(name), m_file(""), m_cdate(""), m_ctime(""), m_flags(F__DFL), m_next(null) { #if DEBUG // Insert this group into the list m_next = s_list; s_list = this; #endif } inline bool drt_trace_grp_t::isEnabled() const { #if DEBUG // Check that output is enabled for this group return ((m_flags & F_ENABLE) != 0); #else return (false); #endif } /*----------------------------------------------------------------------------- * Class DrtTraceInfo * Debugging function entry info. * * Notes * This is a POD class. * * Caveats * This class does not inherit class DrtMagic. * * History * 100, 1998-04-23, David R Tribble. * First cut. * * 101, 1998-05-30, David R Tribble. * Added .m_magic and .m_vers members. *----------------------------------------------------------------------------*/ #define DrtTraceInfo_VS 101 // Class version class DRTEXPORT DrtTraceInfo { public: // Shared constants static const int VS; // Class version static const unsigned int MAGIC; // Class magic number public: // Shared types typedef DrtTraceInfo Type; // This type public: // Variables unsigned int m_magic; // Class magic number int m_vers; // Class version number const char * m_func; // Func name const void * m_thisp; /* Func's object */ drt_trace_grp_t * m_group; // Group info public: // Functions // Constructors and destructors not provided // No destructor // No default constructor // No copy constructor // No assigment operator }; /*----------------------------------------------------------------------------- * Class drt_trace_t * Debugging (tracing) class. * This class implements very simple runtime debug tracing functions. * * Caveats * This class does not inherit class DrtMagic. * * See also * The notes in this file for more details about how to use this class. * * History * 100, 1998-04-16, David R Tribble. * First cut. *----------------------------------------------------------------------------*/ #define drt_trace_t_VS 100 // Class version class DRTEXPORT drt_trace_t { public: // Shared constants static const int VS; // Class version static const unsigned int MAGIC; // Class magic number enum Constants // Manifest constants { MAX_DEPTH = 200 // Max function nesting depth }; public: // Shared types typedef drt_trace_t Type; // This type public: // Shared variables static FILE * s_outf; // Debugging output stream public: // Variables // No members public: // Shared functions static bool open(const char *fn); // Open a debug output stream static void close(); // Close the debug output static void suspend(); // Suspend debug output static void resume(); // Resume debug output static void enterContext(); // Lock the debugging context static void leaveContext(); // Unlock the debugging context static void where(const char *func, int line); // Establish a location static int print(const char *fmt, ...); // Print formatted output static int printHead(); // Print a line heading public: // Formatting insertion functions static int eoln(); // Print an end-of-line static int width(int n); // Format width static int prec(int n); // Format precision static int radix(int n); // Format numeric radix public: // Functions /*void*/ ~drt_trace_t(); // Destructor /*void*/ drt_trace_t(const char *name, const void *thisp); // Constructor, member func /*void*/ drt_trace_t(const char *name); // Constructor, nonmember func /*void*/ drt_trace_t(drt_trace_grp_t &g, const char *name, const void *thisp); // Constructor, member func /*void*/ drt_trace_t(drt_trace_grp_t &g, const char *name); // Constructor, nonmember func public: // Operators drt_trace_t & operator <<(char x); // Print a char drt_trace_t & operator <<(int x); // Print an integer drt_trace_t & operator <<(unsigned int x); // Print an integer drt_trace_t & operator <<(long x); // Print an integer drt_trace_t & operator <<(const char *x); // Print a string drt_trace_t & operator <<(const void *x); // Print a pointer drt_trace_t & operator <<(int (*x)()); // Insert a formatter drt_trace_t & operator <<(int (*x)(int n)); // Insert a formatter private: // Shared variables static FILE * s_savef; // Suspended output stream static int s_depth; // Func nesting depth static DrtTraceInfo * s_stack; // Nested func call info private: // Variables // No members private: // Shared functions static int enter(const char *name, const void *thisp, drt_trace_grp_t *g); // Enter a function static void leave(); // Leave a function static void lock(); // Acquire a thread mutex static void unlock(); // Release a thread mutex private: // Functions // Constructors and destructors not provided /*void*/ drt_trace_t(); // Default constructor /*void*/ drt_trace_t(const drt_trace_t &o); // Copy constructor const drt_trace_t & operator =(const drt_trace_t &o); // Assignment operator private: // Operators // Operators not provided void * operator new(size_t n); void * operator new[](size_t n); void operator delete(void *o); void operator delete[](void *o); }; // Inline member functions inline /*void*/ drt_trace_~drt_trace_t() { #if DEBUG // No members to de-initialize leave(); #endif } inline /*void*/ drt_trace_drt_trace_t() { #if DEBUG // No members to initialize enter("", null, null); #endif } inline /*void*/ drt_trace_drt_trace_t(const char *name) { #if DEBUG // No members to initialize enter(name, null, null); #endif } inline /*void*/ drt_trace_drt_trace_t(const char *name, const void *thisp) { #if DEBUG // No members to initialize enter(name, thisp, null); #endif } inline /*void*/ drt_trace_drt_trace_t(drt_trace_grp_t &g, const char *name) { #if DEBUG // No members to initialize enter(name, null, &g); #endif } inline /*void*/ drt_trace_drt_trace_t(drt_trace_grp_t &g, const char *name, const void *thisp) { #if DEBUG // No members to initialize enter(name, thisp, &g); #endif } /* Wrapper end */ #include "klib2.h" #endif /* TEMPORARY */ #ifdef __cplusplus } #endif #endif /* drt_sys_kdebug_h */ /* End kdebug.h */