trace.h

Go to the documentation of this file.
00001 /** @file rutz/trace.h GVX_TRACE macro for user-controlled tracing and
00002     profiling */
00003 
00004 ///////////////////////////////////////////////////////////////////////
00005 //
00006 // Copyright (c) 1999-2004 California Institute of Technology
00007 // Copyright (c) 2004-2007 University of Southern California
00008 // Rob Peters <rjpeters at usc dot edu>
00009 //
00010 // created: Mon Jan  4 08:00:00 1999
00011 // commit: $Id: trace.h 9375 2008-03-04 17:04:59Z rjpeters $
00012 // $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/rutz/trace.h $
00013 //
00014 // --------------------------------------------------------------------
00015 //
00016 // This file is part of GroovX.
00017 //   [http://ilab.usc.edu/rjpeters/groovx/]
00018 //
00019 // GroovX is free software; you can redistribute it and/or modify it
00020 // under the terms of the GNU General Public License as published by
00021 // the Free Software Foundation; either version 2 of the License, or
00022 // (at your option) any later version.
00023 //
00024 // GroovX is distributed in the hope that it will be useful, but
00025 // WITHOUT ANY WARRANTY; without even the implied warranty of
00026 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00027 // General Public License for more details.
00028 //
00029 // You should have received a copy of the GNU General Public License
00030 // along with GroovX; if not, write to the Free Software Foundation,
00031 // Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
00032 //
00033 ///////////////////////////////////////////////////////////////////////
00034 
00035 #ifndef GROOVX_RUTZ_TRACE_H_UTC20050626084019_DEFINED
00036 #define GROOVX_RUTZ_TRACE_H_UTC20050626084019_DEFINED
00037 
00038 // The basic idea is that for each function for which profiling is
00039 // enabled, a static rutz::prof object is created. This object
00040 // maintains the call count and total elapsed time for that
00041 // function. The job of measuring and recording such information falls
00042 // to the rutz::trace class. A local object of the rutz::trace class
00043 // is constructed on entry to a function, and it is destructed just
00044 // prior to function exit. If a GVX_TRACE_EXPR macro is defined, and
00045 // that macro evaluates to true at the time the GVX_TRACE statement is
00046 // reached, then the rutz::trace object will emit "entering" and
00047 // "leaving" messages as it is constructed and destructed,
00048 // respectively. (Thus, to simply turn on verbose tracing in a source
00049 // file, just do "#define GVX_TRACE_EXPR true".) In any case, the
00050 // rutz::trace object takes care of teling the static rutz::prof
00051 // object to 1) increment its counter, and 2) record the elapsed time.
00052 //
00053 // The behavior of the control macros are as follows:
00054 //
00055 // 1) if GVX_NO_PROF is defined, no profiling/tracing will occur;
00056 //    OTHERWISE: profiling always occurs, AND
00057 // 2) if GVX_TRACE_EXPR is defined, that expression is used to control
00058 //    verbose tracing, otherwise verbose tracing will be off
00059 
00060 #include "rutz/prof.h"
00061 #include "rutz/time.h"
00062 
00063 #include <iosfwd>
00064 
00065 namespace rutz
00066 {
00067   class trace;
00068 }
00069 
00070 /// Times and traces execution in and out of a lexical scope.
00071 /** This class cooperates with rutz::prof. rutz::prof objects are
00072     expected to have "long" lifetimes, and accumulate timing
00073     information over multiple passes. In each pass, a rutz::trace
00074     object should be constructed, which will pass its runtime info
00075     onto the rutz::prof, which then accumulates the timing info. */
00076 class rutz::trace
00077 {
00078 public:
00079   /// Query whether we are unconditionally printing trace in/out messages.
00080   static bool get_global_trace() throw();
00081   /// Set whether to unconditionally print trace in/out messages.
00082   static void set_global_trace(bool on_off) throw();
00083 
00084   /// Get the max nesting level for printing trace in/out messages.
00085   static unsigned int get_max_level() throw();
00086   /// Set the max nesting level for printing trace in/out messages.
00087   static void         set_max_level(unsigned int lev) throw();
00088 
00089   /// Construct a rutz::trace object.
00090   /** Store the current time internally (either the wall clock time or
00091       current user+sys rusage, depending on the current
00092       timing_mode). If use_msg, then print a trace-begin message to
00093       stderr showing the name of the given rutz::prof. */
00094   trace(rutz::prof& p, bool use_msg) throw();
00095 
00096   /// Destruct the rutz::trace object, accumulating time information in the stored rutz::prof.
00097   /** Get the new time (either wall clock or user+sys rusage, matching
00098       whatever we did in the rutz::trace constructor. If we printed a
00099       trace-begin message, then also print a matching trace-end
00100       message. */
00101   ~trace() throw();
00102 
00103 private:
00104   rutz::prof&  m_prof;
00105   rutz::time   m_start;
00106   const bool   m_should_print_msg;
00107   const bool   m_should_pop;
00108   rutz::prof::timing_mode  m_timing_mode; ///< Store this in case somebody changes the timing mode before we finish
00109 };
00110 
00111 #ifndef GVX_TRACE_EXPR
00112 #  define GVX_TRACE_EXPR false
00113 #endif
00114 
00115 #define GVX_TRACE_CONCAT2(x,y) x##y
00116 #define GVX_TRACE_CONCAT(x,y) GVX_TRACE_CONCAT2(x,y)
00117 
00118 #ifndef GVX_NO_PROF
00119 #  define GVX_TRACE(x) \
00120          static rutz::prof  GVX_TRACE_CONCAT(P_x_, __LINE__)  (x,   __FILE__, __LINE__); \
00121          rutz::trace        GVX_TRACE_CONCAT(T_x_, __LINE__)  (GVX_TRACE_CONCAT(P_x_, __LINE__), GVX_TRACE_EXPR)
00122 #else
00123 #  define GVX_TRACE(x) do {} while(0)
00124 #endif
00125 
00126 static const char __attribute__((used)) vcid_groovx_rutz_trace_h_utc20050626084019[] = "$Id: trace.h 9375 2008-03-04 17:04:59Z rjpeters $ $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/rutz/trace.h $";
00127 #endif // !GROOVX_RUTZ_TRACE_H_UTC20050626084019_DEFINED
Generated on Sun May 8 08:42:13 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3