]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: debugging.h | |
3 | // Purpose: topic overview | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | ||
11 | @page overview_debugging Debugging | |
12 | ||
13 | Classes, functions and macros: wxDebugContext, wxObject, wxLog, | |
14 | @ref group_funcmacro_log, @ref group_funcmacro_debug | |
15 | ||
16 | Various classes, functions and macros are provided in wxWidgets to help you debug | |
17 | your application. Most of these are only available if you compile both wxWidgets, | |
18 | your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol | |
19 | defined. You can also test the __WXDEBUG__ symbol in your own applications to execute | |
20 | code that should be active only in debug mode. | |
21 | ||
22 | @li @ref overview_debugging_dbgctx | |
23 | @li @ref overview_debugging_dbgmacros | |
24 | @li @ref overview_debugging_logging | |
25 | @li @ref overview_debugging_dbgctx2 | |
26 | ||
27 | ||
28 | <hr> | |
29 | ||
30 | ||
31 | @section overview_debugging_dbgctx wxDebugContext | |
32 | ||
33 | wxDebugContext is a class that never gets instantiated, but ties together | |
34 | various static functions and variables. It allows you to dump all objects to that stream, | |
35 | write statistics about object allocation, and check memory for errors. | |
36 | ||
37 | It is good practice to define a wxObject::Dump member function for each class you derive | |
38 | from a wxWidgets class, so that wxDebugContext::Dump can call it and | |
39 | give valuable information about the state of the application. | |
40 | ||
41 | If you have difficulty tracking down a memory leak, recompile | |
42 | in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at | |
43 | appropriate places. They will tell you what objects have not yet been | |
44 | deleted, and what kinds of object they are. In fact, in debug mode wxWidgets will automatically | |
45 | detect memory leaks when your application is about to exit, and if there are any leaks, | |
46 | will give you information about the problem. (How much information depends on the operating system | |
47 | and compiler -- some systems don't allow all memory logging to be enabled). See the | |
48 | memcheck sample for example of usage. | |
49 | ||
50 | For wxDebugContext to do its work, the @e new and @e delete operators for wxObject | |
51 | have been redefined to store extra information about dynamically allocated objects | |
52 | (but not statically declared objects). | |
53 | ||
54 | This slows down a debugging version of an application, but can | |
55 | find difficult-to-detect memory leaks (objects are not | |
56 | deallocated), overwrites (writing past the end of your object) and | |
57 | underwrites (writing to memory in front of the object). | |
58 | ||
59 | If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and | |
60 | wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be: | |
61 | ||
62 | @code | |
63 | #define new new(__FILE__,__LINE__) | |
64 | @endcode | |
65 | ||
66 | All occurrences of 'new' in wxWidgets and your own application will use | |
67 | the overridden form of the operator with two extra arguments. This means that | |
68 | the debugging output (and error messages reporting memory problems) will tell you what | |
69 | file and on what line you allocated the object. Unfortunately not all | |
70 | compilers allow this definition to work properly, but most do. | |
71 | ||
72 | ||
73 | ||
74 | @section overview_debugging_dbgmacros Debug macros | |
75 | ||
76 | You should also use @ref group_funcmacro_debug as part of a 'defensive programming' | |
77 | strategy, scattering wxASSERTs liberally to test for problems in your code as early as | |
78 | possible. | |
79 | Forward thinking will save a surprising amount of time in the long run. | |
80 | ||
81 | #wxASSERT is used to pop up an error message box when a condition | |
82 | is not @true. You can also use #wxASSERT_MSG to supply your | |
83 | own helpful error message. For example: | |
84 | ||
85 | @code | |
86 | void MyClass::MyFunction(wxObject* object) | |
87 | { | |
88 | wxASSERT_MSG( (object != NULL), "object should not be NULL in MyFunction!" ); | |
89 | ||
90 | ... | |
91 | }; | |
92 | @endcode | |
93 | ||
94 | The message box allows you to continue execution or abort the program. If you are running | |
95 | the application inside a debugger, you will be able to see exactly where the problem was. | |
96 | ||
97 | ||
98 | ||
99 | @section overview_debugging_logging Logging functions | |
100 | ||
101 | You can use the wxLogDebug and wxLogTrace functions to output debugging information in | |
102 | debug mode; it will do nothing for non-debugging code. | |
103 | ||
104 | ||
105 | ||
106 | @section overview_debugging_dbgctx2 wxDebugContext overview | |
107 | ||
108 | Class: wxDebugContext | |
109 | ||
110 | wxDebugContext is a class for performing various debugging and memory tracing operations. | |
111 | ||
112 | This class has only static data and function members, and there should be | |
113 | no instances. Probably the most useful members are SetFile (for directing output | |
114 | to a file, instead of the default standard error or debugger output); | |
115 | Dump (for dumping the dynamically allocated objects) and PrintStatistics | |
116 | (for dumping information about allocation of objects). You can also call | |
117 | Check to check memory blocks for integrity. | |
118 | ||
119 | Here's an example of use. The SetCheckpoint ensures that only the | |
120 | allocations done after the checkpoint will be dumped. | |
121 | ||
122 | @code | |
123 | wxDebugContext::SetCheckpoint(); | |
124 | ||
125 | wxDebugContext::SetFile("c:\\temp\\debug.log"); | |
126 | ||
127 | wxString *thing = new wxString; | |
128 | ||
129 | char *ordinaryNonObject = new char[1000]; | |
130 | ||
131 | wxDebugContext::Dump(); | |
132 | wxDebugContext::PrintStatistics(); | |
133 | @endcode | |
134 | ||
135 | You can use wxDebugContext if __WXDEBUG__ is defined, or you can use it | |
136 | at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled | |
137 | in non-debug mode because you may not wish to recompile wxWidgets and your entire application | |
138 | just to make use of the error logging facility. | |
139 | ||
140 | @note wxDebugContext::SetFile has a problem at present, so use the default stream instead. | |
141 | Eventually the logging will be done through the wxLog facilities instead. | |
142 | ||
143 | */ | |
144 |