]>
Commit | Line | Data |
---|---|---|
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 | /** @ingroup group_funcmacro_log */ | |
242 | //@{ | |
243 | ||
244 | /** | |
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} | |
252 | */ | |
253 | #define WXTRACE(format, ...) | |
254 | ||
255 | /** | |
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} | |
266 | */ | |
267 | #define WXTRACELEVEL(level, format, ...) | |
268 | ||
269 | /** | |
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} | |
277 | */ | |
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 | //@} | |
295 |