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