← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/debug.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/debug.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        wx/debug.h
 
3
// Purpose:     interface of global functions
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: debug.h 71102 2012-04-05 18:40:11Z VZ $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
/** @addtogroup group_funcmacro_debug */
 
10
//@{
 
11
 
 
12
/**
 
13
    Exits the program immediately.
 
14
 
 
15
    This is a simple wrapper for the standard abort() function which is not
 
16
    available under all platforms (currently only Windows CE doesn't provide
 
17
    it).
 
18
 
 
19
    @since 2.9.4
 
20
 */
 
21
void wxAbort();
 
22
 
 
23
/**
 
24
    @def wxDEBUG_LEVEL
 
25
 
 
26
    Preprocessor symbol defining the level of debug support available.
 
27
 
 
28
    This symbol is defined to 1 by default meaning that asserts are compiled in
 
29
    (although they may be disabled by a call to wxDisableAsserts()). You may
 
30
    predefine it as 0 prior to including any wxWidgets headers to omit the
 
31
    calls to wxASSERT() and related macros entirely in your own code and you
 
32
    may also predefine it as 0 when building wxWidgets to also avoid including
 
33
    any asserts in wxWidgets itself.
 
34
 
 
35
    Alternatively, you may predefine it as 2 to include wxASSERT_LEVEL_2() and
 
36
    similar macros which are used for asserts which have non-trivial run-time
 
37
    costs and so are disabled by default.
 
38
 
 
39
    @since 2.9.1
 
40
 
 
41
    @header{wx/debug.h}
 
42
 */
 
43
#define wxDEBUG_LEVEL
 
44
 
 
45
/**
 
46
    @def __WXDEBUG__
 
47
 
 
48
    Compatibility macro indicating presence of debug support.
 
49
 
 
50
    This symbol is defined if wxDEBUG_LEVEL is greater than 0 and undefined
 
51
    otherwise.
 
52
 
 
53
    @header{wx/debug.h}
 
54
 */
 
55
#define __WXDEBUG__
 
56
 
 
57
/**
 
58
    Type for the function called in case of assert failure.
 
59
 
 
60
    @see wxSetAssertHandler()
 
61
 */
 
62
typedef void (*wxAssertHandler_t)(const wxString& file,
 
63
                                  int line,
 
64
                                  const wxString& func,
 
65
                                  const wxString& cond,
 
66
                                  const wxString& msg);
 
67
 
 
68
/**
 
69
    Assert macro. An error message will be generated if the condition is @false in
 
70
    debug mode, but nothing will be done in the release build.
 
71
 
 
72
    Please note that the condition in wxASSERT() should have no side effects
 
73
    because it will not be executed in release mode at all.
 
74
 
 
75
    This macro should be used to catch (in debug builds) logical errors done
 
76
    by the programmer.
 
77
 
 
78
    @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
 
79
 
 
80
    @header{wx/debug.h}
 
81
*/
 
82
#define wxASSERT( condition )
 
83
 
 
84
/**
 
85
    Assert macro for expensive run-time checks.
 
86
 
 
87
    This macro does nothing unless wxDEBUG_LEVEL is 2 or more and is meant to
 
88
    be used for the assertions with noticeable performance impact and which,
 
89
    hence, should be disabled during run-time.
 
90
 
 
91
    If wxDEBUG_LEVEL is 2 or more, it becomes the same as wxASSERT().
 
92
 
 
93
    @header{wx/debug.h}
 
94
 */
 
95
#define wxASSERT_LEVEL_2( condition )
 
96
 
 
97
/**
 
98
    Assert macro with a custom message for expensive run-time checks.
 
99
 
 
100
    If wxDEBUG_LEVEL is 2 or more, this is the same as wxASSERT_MSG(),
 
101
    otherwise it doesn't do anything at all.
 
102
 
 
103
    @see wxASSERT_LEVEL_2()
 
104
 
 
105
    @header{wx/debug.h}
 
106
 */
 
107
#define wxASSERT_LEVEL_2_MSG( condition, msg)
 
108
 
 
109
 
 
110
/**
 
111
    This macro results in a @ref wxCOMPILE_TIME_ASSERT "compile time assertion failure"
 
112
    if the size of the given @c type is less than @c size bits.
 
113
 
 
114
    This macro should be used to catch (in debug builds) logical errors done
 
115
    by the programmer.
 
116
 
 
117
    You may use it like this, for example:
 
118
 
 
119
    @code
 
120
    // we rely on the int being able to hold values up to 2^32
 
121
    wxASSERT_MIN_BITSIZE(int, 32);
 
122
 
 
123
    // can't work with the platforms using UTF-8 for wchar_t
 
124
    wxASSERT_MIN_BITSIZE(wchar_t, 16);
 
125
    @endcode
 
126
 
 
127
    @header{wx/debug.h}
 
128
*/
 
129
#define wxASSERT_MIN_BITSIZE( type, size )
 
130
 
 
131
/**
 
132
    Assert macro with message.
 
133
    An error message will be generated if the condition is @false.
 
134
 
 
135
    This macro should be used to catch (in debug builds) logical errors done
 
136
    by the programmer.
 
137
 
 
138
    @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
 
139
 
 
140
    @header{wx/debug.h}
 
141
*/
 
142
#define wxASSERT_MSG( condition, message )
 
143
 
 
144
/**
 
145
    Checks that the condition is @true, returns with the given return value if
 
146
    not (stops execution in debug mode). This check is done even in release mode.
 
147
 
 
148
    This macro should be used to catch (both in debug and release builds) logical
 
149
    errors done by the programmer.
 
150
 
 
151
    @header{wx/debug.h}
 
152
*/
 
153
#define wxCHECK( condition, retValue )
 
154
 
 
155
/**
 
156
    Checks that the condition is @true, returns with the given return value if
 
157
    not (stops execution in debug mode). This check is done even in release mode.
 
158
 
 
159
    This macro may be only used in non-void functions, see also wxCHECK_RET().
 
160
 
 
161
    This macro should be used to catch (both in debug and release builds) logical
 
162
    errors done by the programmer.
 
163
 
 
164
    @header{wx/debug.h}
 
165
*/
 
166
#define wxCHECK_MSG( condition, retValue, message )
 
167
 
 
168
/**
 
169
    Checks that the condition is @true, and returns if not (stops execution
 
170
    with the given error message in debug mode). This check is done even in
 
171
    release mode.
 
172
 
 
173
    This macro should be used in void functions instead of wxCHECK_MSG().
 
174
 
 
175
    This macro should be used to catch (both in debug and release builds) logical
 
176
    errors done by the programmer.
 
177
 
 
178
    @header{wx/debug.h}
 
179
*/
 
180
#define wxCHECK_RET( condition, message )
 
181
 
 
182
/**
 
183
    Checks that the condition is @true, and if not, it will wxFAIL() and
 
184
    execute the given @c operation if it is not. This is a generalisation of
 
185
    wxCHECK() and may be used when something else than just returning from the
 
186
    function must be done when the @c condition is @false. This check is done
 
187
    even in release mode.
 
188
 
 
189
    This macro should be used to catch (both in debug and release builds) logical
 
190
    errors done by the programmer.
 
191
 
 
192
    @header{wx/debug.h}
 
193
*/
 
194
#define wxCHECK2(condition, operation)
 
195
 
 
196
/**
 
197
    This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified
 
198
    @c message is called instead of wxFAIL() if the @c condition is @false.
 
199
 
 
200
    This macro should be used to catch (both in debug and release builds) logical
 
201
    errors done by the programmer.
 
202
 
 
203
    @header{wx/debug.h}
 
204
*/
 
205
#define wxCHECK2_MSG( condition, operation, message )
 
206
 
 
207
/**
 
208
    Using wxCOMPILE_TIME_ASSERT() results in a compilation error if the
 
209
    specified @c condition is @false. The compiler error message should include
 
210
    the @c message identifier - please note that it must be a valid C++
 
211
    identifier and not a string unlike in the other cases.
 
212
 
 
213
    This macro is mostly useful for testing the expressions involving the
 
214
    @c sizeof operator as they can't be tested by the preprocessor but it is
 
215
    sometimes desirable to test them at the compile time.
 
216
 
 
217
    Note that this macro internally declares a struct whose name it tries to
 
218
    make unique by using the @c __LINE__ in it but it may still not work if you
 
219
    use it on the same line in two different source files. In this case you may
 
220
    either change the line in which either of them appears on or use the
 
221
    wxCOMPILE_TIME_ASSERT2() macro.
 
222
 
 
223
    Also note that Microsoft Visual C++ has a bug which results in compiler
 
224
    errors if you use this macro with 'Program Database For Edit And Continue'
 
225
    (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok
 
226
    though) for the code making use of this macro.
 
227
 
 
228
    This macro should be used to catch misconfigurations at compile-time.
 
229
 
 
230
    @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
 
231
 
 
232
    @header{wx/debug.h}
 
233
*/
 
234
#define wxCOMPILE_TIME_ASSERT( condition, message )
 
235
 
 
236
/**
 
237
    This macro is identical to wxCOMPILE_TIME_ASSERT() except that it allows
 
238
    you to specify a unique @c name for the struct internally defined by this
 
239
    macro to avoid getting the compilation errors described for
 
240
    wxCOMPILE_TIME_ASSERT().
 
241
 
 
242
    This macro should be used to catch misconfigurations at compile-time.
 
243
 
 
244
    @header{wx/debug.h}
 
245
*/
 
246
#define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 
247
 
 
248
/**
 
249
    Disable the condition checks in the assertions.
 
250
 
 
251
    This is the same as calling wxSetAssertHandler() with @NULL handler.
 
252
 
 
253
    @since 2.9.0
 
254
 
 
255
    @header{wx/debug.h}
 
256
 */
 
257
void wxDisableAsserts();
 
258
 
 
259
/**
 
260
    @def wxDISABLE_ASSERTS_IN_RELEASE_BUILD
 
261
 
 
262
    Use this macro to disable asserts in release build when not using
 
263
    wxIMPLEMENT_APP().
 
264
 
 
265
    By default, assert message boxes are suppressed in release build by
 
266
    wxIMPLEMENT_APP() which uses this macro. If you don't use wxIMPLEMENT_APP()
 
267
    because your application initializes wxWidgets directly (e.g. calls
 
268
    wxEntry() or wxEntryStart() itself) but still want to suppress assert
 
269
    notifications in release build you need to use this macro directly.
 
270
 
 
271
    @see wxDISABLE_DEBUG_SUPPORT()
 
272
 
 
273
    @since 2.9.1
 
274
 
 
275
    @header{wx/debug.h}
 
276
 */
 
277
#define wxDISABLE_ASSERTS_IN_RELEASE_BUILD() wxDisableAsserts()
 
278
 
 
279
/**
 
280
    Will always generate an assert error if this code is reached (in debug mode).
 
281
    Note that you don't have to (and cannot) use brackets when invoking this
 
282
    macro:
 
283
 
 
284
    @code
 
285
        if (...some condition...) {
 
286
            wxFAIL;
 
287
        }
 
288
    @endcode
 
289
 
 
290
    This macro should be used to catch (in debug builds) logical errors done
 
291
    by the programmer.
 
292
 
 
293
    @see wxFAIL_MSG()
 
294
 
 
295
    @header{wx/debug.h}
 
296
*/
 
297
#define wxFAIL
 
298
 
 
299
/**
 
300
    Will always generate an assert error with specified message if this code is
 
301
    reached (in debug mode).
 
302
 
 
303
    This macro is useful for marking "unreachable" code areas, for example it
 
304
    may be used in the "default:" branch of a switch statement if all possible
 
305
    cases are processed above.
 
306
 
 
307
    This macro should be used to catch (in debug builds) logical errors done
 
308
    by the programmer.
 
309
 
 
310
    @see wxFAIL()
 
311
 
 
312
    @header{wx/debug.h}
 
313
*/
 
314
#define wxFAIL_MSG( message )
 
315
 
 
316
/**
 
317
    Returns @true if the program is running under debugger, @false otherwise.
 
318
 
 
319
    Please note that this function is currently only implemented for Win32 and
 
320
    always returns @false elsewhere.
 
321
 
 
322
    @header{wx/debug.h}
 
323
*/
 
324
bool wxIsDebuggerRunning();
 
325
 
 
326
/**
 
327
    Sets the function to be called in case of assertion failure.
 
328
 
 
329
    The default assert handler forwards to wxApp::OnAssertFailure() whose
 
330
    default behaviour is, in turn, to show the standard assertion failure
 
331
    dialog if a wxApp object exists or shows the same dialog itself directly
 
332
    otherwise.
 
333
 
 
334
    While usually it is enough -- and more convenient -- to just override
 
335
    OnAssertFailure(), to handle all assertion failures, including those
 
336
    occurring even before wxApp object creation of after its destruction you
 
337
    need to provide your assertion handler function.
 
338
 
 
339
    This function also provides a simple way to disable all asserts: simply
 
340
    pass @NULL pointer to it. Doing this will result in not even evaluating
 
341
    assert conditions at all, avoiding almost all run-time cost of asserts.
 
342
 
 
343
    Notice that this function is not MT-safe, so you should call it before
 
344
    starting any other threads.
 
345
 
 
346
    The return value of this function is the previous assertion handler. It can
 
347
    be called after any pre-processing by your handler and can also be restored
 
348
    later if you uninstall your handler.
 
349
 
 
350
    @param handler
 
351
        The function to call in case of assertion failure or @NULL.
 
352
    @return
 
353
        The previous assert handler which is not @NULL by default but could be
 
354
        @NULL if it had been previously set to this value using this function.
 
355
 
 
356
    @since 2.9.0
 
357
 
 
358
    @header{wx/debug.h}
 
359
 */
 
360
wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler);
 
361
 
 
362
/**
 
363
    Reset the assert handler to default function which shows a message box when
 
364
    an assert happens.
 
365
 
 
366
    This can be useful for the applications compiled in release build (with @c
 
367
    NDEBUG defined) for which the asserts are by default disabled: if you wish
 
368
    to enable them even in this case you need to call this function.
 
369
 
 
370
    @since 2.9.1
 
371
 
 
372
    @header{wx/debug.h}
 
373
 */
 
374
void wxSetDefaultAssertHandler();
 
375
 
 
376
/**
 
377
    Generate a debugger exception meaning that the control is passed to the
 
378
    debugger if one is attached to the process.
 
379
 
 
380
    Otherwise the program just terminates abnormally.
 
381
 
 
382
    If @c wxDEBUG_LEVEL is 0 (which is not the default) this function does
 
383
    nothing.
 
384
 
 
385
    @header{wx/debug.h}
 
386
*/
 
387
void wxTrap();
 
388
 
 
389
//@}
 
390