]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: memory.h | |
3 | // Purpose: interface of wxDebugContext | |
4 | // Author: wxWidgets team | |
5 | // Licence: wxWindows licence | |
6 | ///////////////////////////////////////////////////////////////////////////// | |
7 | ||
8 | ||
9 | /** | |
10 | @class wxDebugContext | |
11 | ||
12 | A class for performing various debugging and memory tracing operations. | |
13 | ||
14 | Full functionality (such as printing out objects currently allocated) is | |
15 | only present in a debugging build of wxWidgets, i.e. if the __WXDEBUG__ | |
16 | symbol is defined. wxDebugContext and related functions and macros can be | |
17 | compiled out by setting wxUSE_DEBUG_CONTEXT to 0 is setup.h | |
18 | ||
19 | @library{wxbase} | |
20 | @category{debugging} | |
21 | ||
22 | @see @ref overview_debugging | |
23 | */ | |
24 | class wxDebugContext | |
25 | { | |
26 | public: | |
27 | /** | |
28 | Checks the memory blocks for errors, starting from the currently set | |
29 | checkpoint. | |
30 | ||
31 | @return Returns the number of errors, so a value of zero represents | |
32 | success. Returns -1 if an error was detected that prevents | |
33 | further checking. | |
34 | */ | |
35 | static int Check(bool checkAll = false); | |
36 | ||
37 | /** | |
38 | Performs a memory dump from the currently set checkpoint, writing to the | |
39 | current debug stream. Calls the @b Dump member function for each wxObject | |
40 | derived instance. | |
41 | ||
42 | @return @true if the function succeeded, @false otherwise. | |
43 | */ | |
44 | static bool Dump(); | |
45 | ||
46 | /** | |
47 | Returns @true if the memory allocator checks all previous memory blocks for | |
48 | errors. | |
49 | ||
50 | By default, this is @false since it slows down execution considerably. | |
51 | ||
52 | @see SetCheckPrevious() | |
53 | */ | |
54 | static bool GetCheckPrevious(); | |
55 | ||
56 | /** | |
57 | Returns @true if debug mode is on. | |
58 | ||
59 | If debug mode is on, the wxObject new and delete operators store or use | |
60 | information about memory allocation. Otherwise, a straight malloc and | |
61 | free will be performed by these operators. | |
62 | ||
63 | @see SetDebugMode() | |
64 | */ | |
65 | static bool GetDebugMode(); | |
66 | ||
67 | /** | |
68 | Gets the debug level (default 1). | |
69 | ||
70 | The debug level is used by the wxTraceLevel function and the WXTRACELEVEL | |
71 | macro to specify how detailed the trace information is; setting a | |
72 | different level will only have an effect if trace statements in the | |
73 | application specify a value other than one. | |
74 | ||
75 | @deprecated | |
76 | This is obsolete, replaced by wxLog functionality. | |
77 | ||
78 | @see SetLevel() | |
79 | */ | |
80 | static int GetLevel(); | |
81 | ||
82 | /** | |
83 | Prints a list of the classes declared in this application, giving derivation | |
84 | and whether instances of this class can be dynamically created. | |
85 | ||
86 | @see PrintStatistics() | |
87 | */ | |
88 | static bool PrintClasses(); | |
89 | ||
90 | /** | |
91 | Performs a statistics analysis from the currently set checkpoint, writing | |
92 | to the current debug stream. The number of object and non-object | |
93 | allocations is printed, together with the total size. | |
94 | ||
95 | @param detailed | |
96 | If @true, the function will also print how many objects of each class | |
97 | have been allocated, and the space taken by these class instances. | |
98 | ||
99 | @see PrintStatistics() | |
100 | */ | |
101 | static bool PrintStatistics(bool detailed = true); | |
102 | ||
103 | /** | |
104 | Tells the memory allocator to check all previous memory blocks for errors. | |
105 | By default, this is @false since it slows down execution considerably. | |
106 | ||
107 | @see GetCheckPrevious() | |
108 | */ | |
109 | static void SetCheckPrevious(bool check); | |
110 | ||
111 | /** | |
112 | Sets the current checkpoint: Dump and PrintStatistics operations will | |
113 | be performed from this point on. This allows you to ignore allocations | |
114 | that have been performed up to this point. | |
115 | ||
116 | @param all | |
117 | If @true, the checkpoint is reset to include all memory allocations | |
118 | since the program started. | |
119 | */ | |
120 | static void SetCheckpoint(bool all = false); | |
121 | ||
122 | /** | |
123 | Sets the debug mode on or off. | |
124 | ||
125 | If debug mode is on, the wxObject new and delete operators store or use | |
126 | information about memory allocation. Otherwise, a straight malloc and free | |
127 | will be performed by these operators. | |
128 | ||
129 | By default, debug mode is on if __WXDEBUG__ is defined. If the application | |
130 | uses this function, it should make sure that all object memory allocated | |
131 | is deallocated with the same value of debug mode. Otherwise, the delete | |
132 | operator might try to look for memory information that does not exist. | |
133 | ||
134 | @see GetDebugMode() | |
135 | */ | |
136 | static void SetDebugMode(bool debug); | |
137 | ||
138 | /** | |
139 | Sets the debug level (default 1). | |
140 | ||
141 | The debug level is used by the wxTraceLevel function and the WXTRACELEVEL | |
142 | macro to specify how detailed the trace information is; setting | |
143 | a different level will only have an effect if trace statements in the | |
144 | application specify a value other than one. | |
145 | ||
146 | @deprecated | |
147 | This is obsolete, replaced by wxLog functionality. | |
148 | ||
149 | @see GetLevel() | |
150 | */ | |
151 | static void SetLevel(int level); | |
152 | ||
153 | /** | |
154 | Installs a function to be called at the end of wxWidgets shutdown. | |
155 | It will be called after all files with global instances of | |
156 | wxDebugContextDumpDelayCounter have run their destructors. | |
157 | ||
158 | The shutdown function must be take no parameters and return nothing. | |
159 | */ | |
160 | static void SetShutdownNotifyFunction(wxShutdownNotifyFunction func); | |
161 | }; | |
162 | ||
163 | ||
164 | ||
165 | // ============================================================================ | |
166 | // Global functions/macros | |
167 | // ============================================================================ | |
168 | ||
169 | /** @addtogroup group_funcmacro_log */ | |
170 | //@{ | |
171 | ||
172 | /** | |
173 | @deprecated Use one of the wxLogTrace() functions or one of the | |
174 | wxVLogTrace() functions instead. | |
175 | ||
176 | Calls wxTrace() with printf-style variable argument syntax. Output is | |
177 | directed to the current output stream (see wxDebugContext). | |
178 | ||
179 | @header{wx/memory.h} | |
180 | */ | |
181 | #define WXTRACE(format, ...) | |
182 | ||
183 | /** | |
184 | @deprecated Use one of the wxLogTrace() functions or one of the | |
185 | wxVLogTrace() functions instead. | |
186 | ||
187 | Calls wxTraceLevel with printf-style variable argument syntax. Output is | |
188 | directed to the current output stream (see wxDebugContext). The first | |
189 | argument should be the level at which this information is appropriate. It | |
190 | will only be output if the level returned by wxDebugContext::GetLevel is | |
191 | equal to or greater than this value. | |
192 | ||
193 | @header{wx/memory.h} | |
194 | */ | |
195 | #define WXTRACELEVEL(level, format, ...) | |
196 | ||
197 | /** | |
198 | @deprecated Use one of the wxLogTrace() functions or one of the | |
199 | wxVLogTrace() functions instead. | |
200 | ||
201 | Takes printf-style variable argument syntax. Output is directed to the | |
202 | current output stream (see wxDebugContext). | |
203 | ||
204 | @header{wx/memory.h} | |
205 | */ | |
206 | void wxTrace(const wxString& format, ...); | |
207 | ||
208 | /** | |
209 | @deprecated Use one of the wxLogTrace() functions or one of the | |
210 | wxVLogTrace() functions instead. | |
211 | ||
212 | Takes @e printf() style variable argument syntax. Output is directed to the | |
213 | current output stream (see wxDebugContext). The first argument should be | |
214 | the level at which this information is appropriate. It will only be output | |
215 | if the level returned by wxDebugContext::GetLevel() is equal to or greater | |
216 | than this value. | |
217 | ||
218 | @header{wx/memory.h} | |
219 | */ | |
220 | void wxTraceLevel(int level, const wxString& format, ...); | |
221 | ||
222 | //@} | |
223 |