interface/wx/memory.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        memory.h
   3 // Purpose:     interface of wxDebugContext
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxDebugContext
  12
  13     A class for performing various debugging and memory tracing operations.
  14
  15     Full functionality (such as printing out objects currently allocated) is
  16     only present in a debugging build of wxWidgets, i.e. if the __WXDEBUG__
  17     symbol is defined. wxDebugContext and related functions and macros can be
  18     compiled out by setting wxUSE_DEBUG_CONTEXT to 0 is setup.h
  19
  20     @library{wxbase}
  21     @category{debugging}
  22
  23     @see @ref overview_debugging
  24 */
  25 class wxDebugContext
  26 {
  27 public:
  28     /**
  29         Checks the memory blocks for errors, starting from the currently set
  30         checkpoint.
  31
  32         @return Returns the number of errors, so a value of zero represents
  33                 success. Returns -1 if an error was detected that prevents
  34                 further checking.
  35     */
  36     static int Check(bool checkAll = false);
  37
  38     /**
  39         Performs a memory dump from the currently set checkpoint, writing to the
  40         current debug stream. Calls the @b Dump member function for each wxObject
  41         derived instance.
  42
  43         @return @true if the function succeeded, @false otherwise.
  44     */
  45     static bool Dump();
  46
  47     /**
  48         Returns @true if the memory allocator checks all previous memory blocks for
  49         errors.
  50
  51         By default, this is @false since it slows down execution considerably.
  52
  53         @see SetCheckPrevious()
  54     */
  55     static bool GetCheckPrevious();
  56
  57     /**
  58         Returns @true if debug mode is on.
  59
  60         If debug mode is on, the wxObject new and delete operators store or use
  61         information about memory allocation. Otherwise, a straight malloc and
  62         free will be performed by these operators.
  63
  64         @see SetDebugMode()
  65     */
  66     static bool GetDebugMode();
  67
  68     /**
  69         Gets the debug level (default 1).
  70
  71         The debug level is used by the wxTraceLevel function and the WXTRACELEVEL
  72         macro to specify how detailed the trace information is; setting a
  73         different level will only have an effect if trace statements in the
  74         application specify a value other than one.
  75
  76         @deprecated
  77         This is obsolete, replaced by wxLog functionality.
  78
  79         @see SetLevel()
  80     */
  81     static int GetLevel();
  82
  83     /**
  84         Prints a list of the classes declared in this application, giving derivation
  85         and whether instances of this class can be dynamically created.
  86
  87         @see PrintStatistics()
  88     */
  89     static bool PrintClasses();
  90
  91     /**
  92         Performs a statistics analysis from the currently set checkpoint, writing
  93         to the current debug stream. The number of object and non-object
  94         allocations is printed, together with the total size.
  95
  96         @param detailed
  97             If @true, the function will also print how many objects of each class
  98             have been allocated, and the space taken by these class instances.
  99
 100         @see PrintStatistics()
 101     */
 102     static bool PrintStatistics(bool detailed = true);
 103
 104     /**
 105         Tells the memory allocator to check all previous memory blocks for errors.
 106         By default, this is @false since it slows down execution considerably.
 107
 108         @see GetCheckPrevious()
 109     */
 110     static void SetCheckPrevious(bool check);
 111
 112     /**
 113         Sets the current checkpoint: Dump and PrintStatistics operations will
 114         be performed from this point on. This allows you to ignore allocations
 115         that have been performed up to this point.
 116
 117         @param all
 118             If @true, the checkpoint is reset to include all memory allocations
 119             since the program started.
 120     */
 121     static void SetCheckpoint(bool all = false);
 122
 123     /**
 124         Sets the debug mode on or off.
 125
 126         If debug mode is on, the wxObject new and delete operators store or use
 127         information about memory allocation. Otherwise, a straight malloc and free
 128         will be performed by these operators.
 129
 130         By default, debug mode is on if __WXDEBUG__ is defined. If the application
 131         uses this function, it should make sure that all object memory allocated
 132         is deallocated with the same value of debug mode. Otherwise, the delete
 133         operator might try to look for memory information that does not exist.
 134
 135         @see GetDebugMode()
 136     */
 137     static void SetDebugMode(bool debug);
 138
 139     /**
 140         Sets the debug level (default 1).
 141
 142         The debug level is used by the wxTraceLevel function and the WXTRACELEVEL
 143         macro to specify how detailed the trace information is; setting
 144         a different level will only have an effect if trace statements in the
 145         application specify a value other than one.
 146
 147         @deprecated
 148         This is obsolete, replaced by wxLog functionality.
 149
 150         @see GetLevel()
 151     */
 152     static void SetLevel(int level);
 153
 154     /**
 155         Installs a function to be called at the end of wxWidgets shutdown.
 156         It will be called after all files with global instances of
 157         wxDebugContextDumpDelayCounter have run their destructors.
 158
 159         The shutdown function must be take no parameters and return nothing.
 160     */
 161     static void SetShutdownNotifyFunction(wxShutdownNotifyFunction func);
 162 };
 163
 164
 165
 166 // ============================================================================
 167 // Global functions/macros
 168 // ============================================================================
 169
 170 /** @addtogroup group_funcmacro_log */
 171 //@{
 172
 173 /**
 174     @deprecated Use one of the wxLogTrace() functions or one of the
 175                 wxVLogTrace() functions instead.
 176
 177     Calls wxTrace() with printf-style variable argument syntax. Output is
 178     directed to the current output stream (see wxDebugContext).
 179
 180     @header{wx/memory.h}
 181 */
 182 #define WXTRACE(format, ...)
 183
 184 /**
 185     @deprecated Use one of the wxLogTrace() functions or one of the
 186                 wxVLogTrace() functions instead.
 187
 188     Calls wxTraceLevel with printf-style variable argument syntax. Output is
 189     directed to the current output stream (see wxDebugContext). The first
 190     argument should be the level at which this information is appropriate. It
 191     will only be output if the level returned by wxDebugContext::GetLevel is
 192     equal to or greater than this value.
 193
 194     @header{wx/memory.h}
 195 */
 196 #define WXTRACELEVEL(level, format, ...)
 197
 198 /**
 199     @deprecated Use one of the wxLogTrace() functions or one of the
 200                 wxVLogTrace() functions instead.
 201
 202     Takes printf-style variable argument syntax. Output is directed to the
 203     current output stream (see wxDebugContext).
 204
 205     @header{wx/memory.h}
 206 */
 207 void wxTrace(const wxString& format, ...);
 208
 209 /**
 210     @deprecated Use one of the wxLogTrace() functions or one of the
 211                 wxVLogTrace() functions instead.
 212
 213     Takes @e printf() style variable argument syntax. Output is directed to the
 214     current output stream (see wxDebugContext). The first argument should be
 215     the level at which this information is appropriate. It will only be output
 216     if the level returned by wxDebugContext::GetLevel() is equal to or greater
 217     than this value.
 218
 219     @header{wx/memory.h}
 220 */
 221 void wxTraceLevel(int level, const wxString& format, ...);
 222
 223 //@}
 224