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 license
   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     int Check();
  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         Returns the output stream associated with the debug context.
  85
  86         @deprecated
  87         This is obsolete, replaced by wxLog functionality.
  88
  89         @see SetStream()
  90     */
  91     ostream GetStream();
  92
  93     /**
  94         Returns a pointer to the output stream buffer associated with the debug context.
  95         There may not necessarily be a stream buffer if the stream has been set
  96         by the user.
  97
  98         @deprecated
  99         This is obsolete, replaced by wxLog functionality.
 100     */
 101     streambuf* GetStreamBuf();
 102
 103     /**
 104         Returns @true if there is a stream currently associated
 105         with the debug context.
 106
 107         @deprecated
 108         This is obsolete, replaced by wxLog functionality.
 109
 110         @see SetStream(), GetStream()
 111     */
 112     bool HasStream();
 113
 114     /**
 115         Prints a list of the classes declared in this application, giving derivation
 116         and whether instances of this class can be dynamically created.
 117
 118         @see PrintStatistics()
 119     */
 120     static bool PrintClasses();
 121
 122     /**
 123         Performs a statistics analysis from the currently set checkpoint, writing
 124         to the current debug stream. The number of object and non-object
 125         allocations is printed, together with the total size.
 126
 127         @param detailed
 128             If @true, the function will also print how many objects of each class
 129             have been allocated, and the space taken by these class instances.
 130
 131         @see PrintStatistics()
 132     */
 133     static bool PrintStatistics(bool detailed = true);
 134
 135     /**
 136         Tells the memory allocator to check all previous memory blocks for errors.
 137         By default, this is @false since it slows down execution considerably.
 138
 139         @see GetCheckPrevious()
 140     */
 141     static void SetCheckPrevious(bool check);
 142
 143     /**
 144         Sets the current checkpoint: Dump and PrintStatistics operations will
 145         be performed from this point on. This allows you to ignore allocations
 146         that have been performed up to this point.
 147
 148         @param all
 149             If @true, the checkpoint is reset to include all memory allocations
 150             since the program started.
 151     */
 152     static void SetCheckpoint(bool all = false);
 153
 154     /**
 155         Sets the debug mode on or off.
 156
 157         If debug mode is on, the wxObject new and delete operators store or use
 158         information about memory allocation. Otherwise, a straight malloc and free
 159         will be performed by these operators.
 160
 161         By default, debug mode is on if __WXDEBUG__ is defined. If the application
 162         uses this function, it should make sure that all object memory allocated
 163         is deallocated with the same value of debug mode. Otherwise, the delete
 164         operator might try to look for memory information that does not exist.
 165
 166         @see GetDebugMode()
 167     */
 168     static void SetDebugMode(bool debug);
 169
 170     /**
 171         Sets the current debug file and creates a stream.
 172         This will delete any existing stream and stream buffer.
 173
 174         By default, the debug context stream outputs to the debugger (Windows)
 175         or standard error (other platforms).
 176     */
 177     bool SetFile(const wxString& filename);
 178
 179     /**
 180         Sets the debug level (default 1).
 181
 182         The debug level is used by the wxTraceLevel function and the WXTRACELEVEL
 183         macro to specify how detailed the trace information is; setting
 184         a different level will only have an effect if trace statements in the
 185         application specify a value other than one.
 186
 187         @deprecated
 188         This is obsolete, replaced by wxLog functionality.
 189
 190         @see GetLevel()
 191     */
 192     static void SetLevel(int level);
 193
 194     /**
 195         Installs a function to be called at the end of wxWidgets shutdown.
 196         It will be called after all files with global instances of
 197         wxDebugContextDumpDelayCounter have run their destructors.
 198
 199         The shutdown function must be take no parameters and return nothing.
 200     */
 201     static void SetShutdownNotifyFunction(wxShutdownNotifyFunction func);
 202
 203     /**
 204         Sets the debugging stream to be the debugger (Windows) or standard error (other
 205         platforms).
 206
 207         This is the default setting. The existing stream will be flushed and deleted.
 208
 209         @deprecated
 210         This is obsolete, replaced by wxLog functionality.
 211     */
 212     bool SetStandardError();
 213
 214     /**
 215         Sets the stream and optionally, stream buffer associated with the debug context.
 216         This operation flushes and deletes the existing stream (and stream buffer if any).
 217
 218         @deprecated
 219         This is obsolete, replaced by wxLog functionality.
 220
 221         @param stream
 222             Stream to associate with the debug context. Do not set this to @NULL.
 223         @param streamBuf
 224             Stream buffer to associate with the debug context.
 225     */
 226     void SetStream(ostream* stream, streambuf* streamBuf = NULL);
 227 };
 228
 229
 230
 231 // ============================================================================
 232 // Global functions/macros
 233 // ============================================================================
 234
 235 /** @ingroup group_funcmacro_log */
 236 //@{
 237
 238 /**
 239     @deprecated Use one of the wxLogTrace() functions or one of the
 240                 wxVLogTrace() functions instead.
 241
 242     Calls wxTrace() with printf-style variable argument syntax. Output is
 243     directed to the current output stream (see wxDebugContext).
 244
 245     @header{wx/memory.h}
 246 */
 247 #define WXTRACE(format, ...)
 248
 249 /**
 250     @deprecated Use one of the wxLogTrace() functions or one of the
 251                 wxVLogTrace() functions instead.
 252
 253     Calls wxTraceLevel with printf-style variable argument syntax. Output is
 254     directed to the current output stream (see wxDebugContext). The first
 255     argument should be the level at which this information is appropriate. It
 256     will only be output if the level returned by wxDebugContext::GetLevel is
 257     equal to or greater than this value.
 258
 259     @header{wx/memory.h}
 260 */
 261 #define WXTRACELEVEL(level, format, ...)
 262
 263 /**
 264     @deprecated Use one of the wxLogTrace() functions or one of the
 265                 wxVLogTrace() functions instead.
 266
 267     Takes printf-style variable argument syntax. Output is directed to the
 268     current output stream (see wxDebugContext).
 269
 270     @header{wx/memory.h}
 271 */
 272 void wxTrace(const wxString& format, ...);
 273
 274 /**
 275     @deprecated Use one of the wxLogTrace() functions or one of the
 276                 wxVLogTrace() functions instead.
 277
 278     Takes @e printf() style variable argument syntax. Output is directed to the
 279     current output stream (see wxDebugContext). The first argument should be
 280     the level at which this information is appropriate. It will only be output
 281     if the level returned by wxDebugContext::GetLevel() is equal to or greater
 282     than this value.
 283
 284     @header{wx/memory.h}
 285 */
 286 void wxTraceLevel(int level, const wxString& format, ...);
 287
 288 //@}
 289