]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: memory.h | |
e54c96f1 | 3 | // Purpose: interface of wxDebugStreamBuf |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxDebugStreamBuf | |
11 | @wxheader{memory.h} | |
7c913512 | 12 | |
23324ae1 FM |
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). | |
7c913512 | 18 | |
23324ae1 | 19 | This is soon to be obsolete, replaced by wxLog functionality. |
7c913512 | 20 | |
23324ae1 FM |
21 | @library{wxbase} |
22 | @category{FIXME} | |
7c913512 | 23 | |
e54c96f1 | 24 | @see Overview() |
23324ae1 | 25 | */ |
7c913512 | 26 | class wxDebugStreamBuf |
23324ae1 FM |
27 | { |
28 | public: | |
7c913512 | 29 | |
23324ae1 FM |
30 | }; |
31 | ||
32 | ||
e54c96f1 | 33 | |
23324ae1 FM |
34 | /** |
35 | @class wxDebugContext | |
36 | @wxheader{memory.h} | |
7c913512 | 37 | |
23324ae1 FM |
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 | |
7c913512 | 44 | |
23324ae1 FM |
45 | @library{wxbase} |
46 | @category{debugging} | |
7c913512 | 47 | |
e54c96f1 | 48 | @see Overview() |
23324ae1 | 49 | */ |
7c913512 | 50 | class wxDebugContext |
23324ae1 FM |
51 | { |
52 | public: | |
53 | /** | |
54 | Checks the memory blocks for errors, starting from the currently set | |
55 | checkpoint. | |
3c4f71cc | 56 | |
d29a9a8a | 57 | @return Returns the number of errors, so a value of zero represents |
4cc4bfaf FM |
58 | success. Returns -1 if an error was detected that |
59 | prevents further checking. | |
23324ae1 FM |
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. | |
3c4f71cc | 67 | |
d29a9a8a | 68 | @return @true if the function succeeded, @false otherwise. |
23324ae1 FM |
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. | |
3c4f71cc | 76 | |
4cc4bfaf | 77 | @see SetCheckPrevious() |
23324ae1 FM |
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. | |
3c4f71cc | 86 | |
4cc4bfaf | 87 | @see SetDebugMode() |
23324ae1 FM |
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. | |
23324ae1 | 98 | This is obsolete, replaced by wxLog functionality. |
3c4f71cc | 99 | |
4cc4bfaf | 100 | @see SetLevel() |
23324ae1 FM |
101 | */ |
102 | int GetLevel(); | |
103 | ||
104 | /** | |
105 | Returns the output stream associated with the debug context. | |
23324ae1 | 106 | This is obsolete, replaced by wxLog functionality. |
3c4f71cc | 107 | |
4cc4bfaf | 108 | @see SetStream() |
23324ae1 FM |
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. | |
23324ae1 FM |
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. | |
23324ae1 | 123 | This is obsolete, replaced by wxLog functionality. |
3c4f71cc | 124 | |
4cc4bfaf | 125 | @see SetStream(), GetStream() |
23324ae1 FM |
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. | |
3c4f71cc | 132 | |
4cc4bfaf | 133 | @see PrintStatistics() |
23324ae1 FM |
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. | |
3c4f71cc | 141 | |
7c913512 | 142 | @param detailed |
4cc4bfaf FM |
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. | |
3c4f71cc | 146 | |
4cc4bfaf | 147 | @see PrintStatistics() |
23324ae1 | 148 | */ |
4cc4bfaf | 149 | bool PrintStatistics(bool detailed = true); |
23324ae1 FM |
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. | |
3c4f71cc | 154 | |
4cc4bfaf | 155 | @see GetCheckPrevious() |
23324ae1 FM |
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. | |
3c4f71cc | 163 | |
7c913512 | 164 | @param all |
4cc4bfaf FM |
165 | If @true, the checkpoint is reset to include all |
166 | memory allocations since the program started. | |
23324ae1 | 167 | */ |
4cc4bfaf | 168 | void SetCheckpoint(bool all = false); |
23324ae1 FM |
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. | |
23324ae1 FM |
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. | |
3c4f71cc | 179 | |
4cc4bfaf | 180 | @see GetDebugMode() |
23324ae1 FM |
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. | |
23324ae1 | 198 | This is obsolete, replaced by wxLog functionality. |
3c4f71cc | 199 | |
4cc4bfaf | 200 | @see GetLevel() |
23324ae1 FM |
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. | |
23324ae1 FM |
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. | |
23324ae1 FM |
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). | |
23324ae1 | 225 | This is obsolete, replaced by wxLog functionality. |
3c4f71cc | 226 | |
7c913512 | 227 | @param stream |
4cc4bfaf | 228 | Stream to associate with the debug context. Do not set this to @NULL. |
7c913512 | 229 | @param streamBuf |
4cc4bfaf | 230 | Stream buffer to associate with the debug context. |
23324ae1 | 231 | */ |
4cc4bfaf | 232 | void SetStream(ostream* stream, streambuf* streamBuf = NULL); |
23324ae1 FM |
233 | }; |
234 | ||
235 | ||
e54c96f1 | 236 | |
23324ae1 FM |
237 | // ============================================================================ |
238 | // Global functions/macros | |
239 | // ============================================================================ | |
240 | ||
ef477678 BP |
241 | /** @ingroup group_funcmacro_log */ |
242 | //@{ | |
243 | ||
23324ae1 | 244 | /** |
ef477678 BP |
245 | @deprecated Use one of the wxLogTrace() functions or one of the |
246 | wxVLogTrace() functions instead. | |
247 | ||
248 | Calls wxTrace() with printf-style variable argument syntax. Output is | |
249 | directed to the current output stream (see wxDebugContext). | |
250 | ||
251 | @header{wx/memory.h} | |
23324ae1 | 252 | */ |
ef477678 | 253 | #define WXTRACE(format, ...) |
23324ae1 FM |
254 | |
255 | /** | |
ef477678 BP |
256 | @deprecated Use one of the wxLogTrace() functions or one of the |
257 | wxVLogTrace() functions instead. | |
258 | ||
259 | Calls wxTraceLevel with printf-style variable argument syntax. Output is | |
260 | directed to the current output stream (see wxDebugContext). The first | |
261 | argument should be the level at which this information is appropriate. It | |
262 | will only be output if the level returned by wxDebugContext::GetLevel is | |
263 | equal to or greater than this value. | |
264 | ||
265 | @header{wx/memory.h} | |
23324ae1 | 266 | */ |
ef477678 | 267 | #define WXTRACELEVEL(level, format, ...) |
23324ae1 FM |
268 | |
269 | /** | |
ef477678 BP |
270 | @deprecated Use one of the wxLogTrace() functions or one of the |
271 | wxVLogTrace() functions instead. | |
272 | ||
273 | Takes printf-style variable argument syntax. Output is directed to the | |
274 | current output stream (see wxDebugContext). | |
275 | ||
276 | @header{wx/memory.h} | |
23324ae1 | 277 | */ |
ef477678 BP |
278 | void wxTrace(const wxString& format, ...); |
279 | ||
280 | /** | |
281 | @deprecated Use one of the wxLogTrace() functions or one of the | |
282 | wxVLogTrace() functions instead. | |
283 | ||
284 | Takes @e printf() style variable argument syntax. Output is directed to the | |
285 | current output stream (see wxDebugContext). The first argument should be | |
286 | the level at which this information is appropriate. It will only be output | |
287 | if the level returned by wxDebugContext::GetLevel() is equal to or greater | |
288 | than this value. | |
289 | ||
290 | @header{wx/memory.h} | |
291 | */ | |
292 | void wxTraceLevel(int level, const wxString& format, ...); | |
293 | ||
294 | //@} | |
23324ae1 | 295 |