interface/wx/memory.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        memory.h
   3 // Purpose:     interface of wxDebugStreamBuf
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDebugStreamBuf
  11
  12     This class allows you to treat debugging output in a similar
  13     (stream-based) fashion on different platforms. Under
  14     Windows, an ostream constructed with this buffer outputs
  15     to the debugger, or other program that intercepts debugging
  16     output. On other platforms, the output goes to standard error (cerr).
  17
  18     This is soon to be obsolete, replaced by wxLog functionality.
  19
  20     @library{wxbase}
  21     @category{FIXME}
  22
  23     @see Overview()
  24 */
  25 class wxDebugStreamBuf
  26 {
  27 public:
  28
  29 };
  30
  31
  32
  33 /**
  34     @class wxDebugContext
  35
  36     A class for performing various debugging and memory tracing
  37     operations. Full functionality (such as printing out objects
  38     currently allocated) is only present in a debugging build of wxWidgets,
  39     i.e. if the __WXDEBUG__ symbol is defined. wxDebugContext
  40     and related functions and macros can be compiled out by setting
  41     wxUSE_DEBUG_CONTEXT to 0 is setup.h
  42
  43     @library{wxbase}
  44     @category{debugging}
  45
  46     @see Overview()
  47 */
  48 class wxDebugContext
  49 {
  50 public:
  51     /**
  52         Checks the memory blocks for errors, starting from the currently set
  53         checkpoint.
  54
  55         @return Returns the number of errors, so a value of zero represents
  56                  success. Returns -1 if an error was detected that
  57                  prevents further checking.
  58     */
  59     int Check();
  60
  61     /**
  62         Performs a memory dump from the currently set checkpoint, writing to the
  63         current debug stream. Calls the @b Dump member function for each wxObject
  64         derived instance.
  65
  66         @return @true if the function succeeded, @false otherwise.
  67     */
  68     bool Dump();
  69
  70     /**
  71         Returns @true if the memory allocator checks all previous memory blocks for
  72         errors.
  73         By default, this is @false since it slows down execution considerably.
  74
  75         @see SetCheckPrevious()
  76     */
  77     bool GetCheckPrevious();
  78
  79     /**
  80         Returns @true if debug mode is on. If debug mode is on, the wxObject new and
  81         delete
  82         operators store or use information about memory allocation. Otherwise,
  83         a straight malloc and free will be performed by these operators.
  84
  85         @see SetDebugMode()
  86     */
  87     bool GetDebugMode();
  88
  89     /**
  90         Gets the debug level (default 1). The debug level is used by the wxTraceLevel
  91         function and
  92         the WXTRACELEVEL macro to specify how detailed the trace information is; setting
  93         a different level will only have an effect if trace statements in the
  94         application
  95         specify a value other than one.
  96         This is obsolete, replaced by wxLog functionality.
  97
  98         @see SetLevel()
  99     */
 100     int GetLevel();
 101
 102     /**
 103         Returns the output stream associated with the debug context.
 104         This is obsolete, replaced by wxLog functionality.
 105
 106         @see SetStream()
 107     */
 108     ostream GetStream();
 109
 110     /**
 111         Returns a pointer to the output stream buffer associated with the debug context.
 112         There may not necessarily be a stream buffer if the stream has been set
 113         by the user.
 114         This is obsolete, replaced by wxLog functionality.
 115     */
 116     streambuf* GetStreamBuf();
 117
 118     /**
 119         Returns @true if there is a stream currently associated
 120         with the debug context.
 121         This is obsolete, replaced by wxLog functionality.
 122
 123         @see SetStream(), GetStream()
 124     */
 125     bool HasStream();
 126
 127     /**
 128         Prints a list of the classes declared in this application, giving derivation
 129         and whether instances of this class can be dynamically created.
 130
 131         @see PrintStatistics()
 132     */
 133     bool PrintClasses();
 134
 135     /**
 136         Performs a statistics analysis from the currently set checkpoint, writing
 137         to the current debug stream. The number of object and non-object
 138         allocations is printed, together with the total size.
 139
 140         @param detailed
 141             If @true, the function will also print how many
 142             objects of each class have been allocated, and the space taken by
 143             these class instances.
 144
 145         @see PrintStatistics()
 146     */
 147     bool PrintStatistics(bool detailed = true);
 148
 149     /**
 150         Tells the memory allocator to check all previous memory blocks for errors.
 151         By default, this is @false since it slows down execution considerably.
 152
 153         @see GetCheckPrevious()
 154     */
 155     void SetCheckPrevious(bool check);
 156
 157     /**
 158         Sets the current checkpoint: Dump and PrintStatistics operations will
 159         be performed from this point on. This allows you to ignore allocations
 160         that have been performed up to this point.
 161
 162         @param all
 163             If @true, the checkpoint is reset to include all
 164             memory allocations since the program started.
 165     */
 166     void SetCheckpoint(bool all = false);
 167
 168     /**
 169         Sets the debug mode on or off. If debug mode is on, the wxObject new and delete
 170         operators store or use information about memory allocation. Otherwise,
 171         a straight malloc and free will be performed by these operators.
 172         By default, debug mode is on if __WXDEBUG__ is defined. If the application
 173         uses this function, it should make sure that all object memory allocated
 174         is deallocated with the same value of debug mode. Otherwise, the
 175         delete operator might try to look for memory information that does not
 176         exist.
 177
 178         @see GetDebugMode()
 179     */
 180     void SetDebugMode(bool debug);
 181
 182     /**
 183         Sets the current debug file and creates a stream. This will delete any existing
 184         stream and stream buffer. By default, the debug context stream
 185         outputs to the debugger (Windows) or standard error (other platforms).
 186     */
 187     bool SetFile(const wxString& filename);
 188
 189     /**
 190         Sets the debug level (default 1). The debug level is used by the wxTraceLevel
 191         function and
 192         the WXTRACELEVEL macro to specify how detailed the trace information is; setting
 193         a different level will only have an effect if trace statements in the
 194         application
 195         specify a value other than one.
 196         This is obsolete, replaced by wxLog functionality.
 197
 198         @see GetLevel()
 199     */
 200     void SetLevel(int level);
 201
 202     /**
 203         Installs a function to be called at the end of wxWidgets shutdown. It will be
 204         called after
 205         all files with global instances of wxDebugContextDumpDelayCounter have run
 206         their destructors.
 207         The shutdown function must be take no parameters and return nothing.
 208     */
 209     void SetShutdownNotifyFunction(wxShutdownNotifyFunction func);
 210
 211     /**
 212         Sets the debugging stream to be the debugger (Windows) or standard error (other
 213         platforms).
 214         This is the default setting. The existing stream will be flushed and deleted.
 215         This is obsolete, replaced by wxLog functionality.
 216     */
 217     bool SetStandardError();
 218
 219     /**
 220         Sets the stream and optionally, stream buffer associated with the debug context.
 221         This operation flushes and deletes the existing stream (and stream buffer if
 222         any).
 223         This is obsolete, replaced by wxLog functionality.
 224
 225         @param stream
 226             Stream to associate with the debug context. Do not set this to @NULL.
 227         @param streamBuf
 228             Stream buffer to associate with the debug context.
 229     */
 230     void SetStream(ostream* stream, streambuf* streamBuf = NULL);
 231 };
 232
 233
 234
 235 // ============================================================================
 236 // Global functions/macros
 237 // ============================================================================
 238
 239 /** @ingroup group_funcmacro_log */
 240 //@{
 241
 242 /**
 243     @deprecated Use one of the wxLogTrace() functions or one of the
 244                 wxVLogTrace() functions instead.
 245
 246     Calls wxTrace() with printf-style variable argument syntax. Output is
 247     directed to the current output stream (see wxDebugContext).
 248
 249     @header{wx/memory.h}
 250 */
 251 #define WXTRACE(format, ...)
 252
 253 /**
 254     @deprecated Use one of the wxLogTrace() functions or one of the
 255                 wxVLogTrace() functions instead.
 256
 257     Calls wxTraceLevel with printf-style variable argument syntax. Output is
 258     directed to the current output stream (see wxDebugContext). The first
 259     argument should be the level at which this information is appropriate. It
 260     will only be output if the level returned by wxDebugContext::GetLevel is
 261     equal to or greater than this value.
 262
 263     @header{wx/memory.h}
 264 */
 265 #define WXTRACELEVEL(level, format, ...)
 266
 267 /**
 268     @deprecated Use one of the wxLogTrace() functions or one of the
 269                 wxVLogTrace() functions instead.
 270
 271     Takes printf-style variable argument syntax. Output is directed to the
 272     current output stream (see wxDebugContext).
 273
 274     @header{wx/memory.h}
 275 */
 276 void wxTrace(const wxString& format, ...);
 277
 278 /**
 279     @deprecated Use one of the wxLogTrace() functions or one of the
 280                 wxVLogTrace() functions instead.
 281
 282     Takes @e printf() style variable argument syntax. Output is directed to the
 283     current output stream (see wxDebugContext). The first argument should be
 284     the level at which this information is appropriate. It will only be output
 285     if the level returned by wxDebugContext::GetLevel() is equal to or greater
 286     than this value.
 287
 288     @header{wx/memory.h}
 289 */
 290 void wxTraceLevel(int level, const wxString& format, ...);
 291
 292 //@}
 293