interface/wx/memory.h

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