interface/memory.h

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