]> git.saurik.com Git - wxWidgets.git/blame - include/wx/debug.h
adding comment
[wxWidgets.git] / include / wx / debug.h
CommitLineData
993df040
VZ
1/////////////////////////////////////////////////////////////////////////////
2// Name: wx/debug.h
3// Purpose: Misc debug functions and macros
4// Author: Vadim Zeitlin
5// Created: 29/01/98
6// RCS-ID: $Id$
7// Copyright: (c) 1998-2009 Vadim Zeitlin <vadim@wxwidgets.org>
8// Licence: wxWindows licence
9/////////////////////////////////////////////////////////////////////////////
e0c749a7 10
993df040
VZ
11#ifndef _WX_DEBUG_H_
12#define _WX_DEBUG_H_
c801d85f 13
bd362275 14#if !defined(__WXWINCE__)
993df040
VZ
15 #include <assert.h>
16#endif // systems without assert.h
c801d85f 17
993df040 18#include <limits.h> // for CHAR_BIT used below
c801d85f 19
993df040 20#include "wx/chartype.h" // for __TFILE__ and wxChar
a6ebdba6 21#include "wx/cpp.h" // for __WXFUNCTION__
e9c4f54e 22#include "wx/dlimpexp.h" // for WXDLLIMPEXP_FWD_BASE
9e3d3318 23
657a8a35
VZ
24class WXDLLIMPEXP_FWD_BASE wxString;
25class WXDLLIMPEXP_FWD_BASE wxCStrData;
26
993df040
VZ
27// ----------------------------------------------------------------------------
28// Defines controlling the debugging macros
29// ----------------------------------------------------------------------------
8b0bd21b 30
657a8a35
VZ
31/*
32 wxWidgets can be built with several different levels of debug support
33 specified by the value of wxDEBUG_LEVEL constant:
34
35 0: No assertion macros at all, this should only be used when optimizing
36 for resource-constrained systems (typically embedded ones).
37 1: Default level, most of the assertions are enabled.
38 2: Maximal (at least for now): asserts which are "expensive"
39 (performance-wise) or only make sense for finding errors in wxWidgets
40 itself, as opposed to bugs in applications using it, are also enabled.
657a8a35
VZ
41 */
42
7d9550df
VZ
43// unless wxDEBUG_LEVEL is predefined (by configure or via wx/setup.h under
44// Windows), use the default
45#if !defined(wxDEBUG_LEVEL)
46 #define wxDEBUG_LEVEL 1
47#endif // !defined(wxDEBUG_LEVEL)
48
49/*
50 __WXDEBUG__ is defined when wxDEBUG_LEVEL != 0. This is done mostly for
51 compatibility but it also provides a simpler way to check if asserts and
52 debug logging is enabled at all.
53 */
54#if wxDEBUG_LEVEL > 0
8b0bd21b
VZ
55 #ifndef __WXDEBUG__
56 #define __WXDEBUG__
7d9550df
VZ
57 #endif
58#else
8b0bd21b 59 #undef __WXDEBUG__
7d9550df 60#endif
8b0bd21b 61
7d9550df
VZ
62// Finally there is also a very old WXDEBUG macro not used anywhere at all, it
63// is only defined for compatibility.
8b0bd21b
VZ
64#ifdef __WXDEBUG__
65 #if !defined(WXDEBUG) || !WXDEBUG
66 #undef WXDEBUG
67 #define WXDEBUG 1
993df040
VZ
68 #endif // !WXDEBUG
69#endif // __WXDEBUG__
e0c749a7 70
993df040 71// ----------------------------------------------------------------------------
657a8a35 72// Handling assertion failures
993df040
VZ
73// ----------------------------------------------------------------------------
74
657a8a35
VZ
75/*
76 Type for the function called in case of assert failure, see
77 wxSetAssertHandler().
78 */
79typedef void (*wxAssertHandler_t)(const wxString& file,
80 int line,
81 const wxString& func,
82 const wxString& cond,
83 const wxString& msg);
84
85#if wxDEBUG_LEVEL
86
87// the global assert handler function, if it is NULL asserts don't check their
88// conditions
89extern WXDLLIMPEXP_DATA_BASE(wxAssertHandler_t) wxTheAssertHandler;
90
91/*
92 Sets the function to be called in case of assertion failure.
93
94 The default assert handler forwards to wxApp::OnAssertFailure() whose
95 default behaviour is, in turn, to show the standard assertion failure
96 dialog if a wxApp object exists or shows the same dialog itself directly
97 otherwise.
98
99 While usually it is enough -- and more convenient -- to just override
100 OnAssertFailure(), to handle all assertion failures, including those
72516be4 101 occurring even before wxApp object creation or after its destruction you
657a8a35
VZ
102 need to provide your assertion handler function.
103
104 This function also provides a simple way to disable all asserts: simply
105 pass NULL pointer to it. Doing this will result in not even evaluating
106 assert conditions at all, avoiding almost all run-time cost of asserts.
107
108 Notice that this function is not MT-safe, so you should call it before
109 starting any other threads.
110
111 The return value of this function is the previous assertion handler. It can
112 be called after any pre-processing by your handler and can also be restored
113 later if you uninstall your handler.
114 */
115inline wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler)
116{
117 const wxAssertHandler_t old = wxTheAssertHandler;
118 wxTheAssertHandler = handler;
119 return old;
120}
121
7d9550df
VZ
122/*
123 Reset the default assert handler.
124
125 This may be used to enable asserts, which are disabled by default in this
126 case, for programs built in release build (NDEBUG defined).
127 */
128extern void WXDLLIMPEXP_BASE wxSetDefaultAssertHandler();
129
657a8a35
VZ
130#else // !wxDEBUG_LEVEL
131
72516be4 132// provide empty stubs in case assertions are completely disabled
993df040 133//
657a8a35
VZ
134// NB: can't use WXUNUSED() here as we're included from wx/defs.h before it is
135// defined
136inline wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t /* handler */)
137{
138 return NULL;
139}
140
7d9550df
VZ
141inline void wxSetDefaultAssertHandler() { }
142
657a8a35
VZ
143#endif // wxDEBUG_LEVEL/!wxDEBUG_LEVEL
144
145// simply a synonym for wxSetAssertHandler(NULL)
146inline void wxDisableAsserts() { wxSetAssertHandler(NULL); }
147
7d9550df
VZ
148/*
149 A macro which disables asserts for applications compiled in release build.
150
e4431849 151 By default, wxIMPLEMENT_APP (or rather wxIMPLEMENT_WXWIN_MAIN) disable the
7d9550df
VZ
152 asserts in the applications compiled in the release build by calling this.
153 It does nothing if NDEBUG is not defined.
154 */
155#ifdef NDEBUG
156 #define wxDISABLE_ASSERTS_IN_RELEASE_BUILD() wxDisableAsserts()
157#else
158 #define wxDISABLE_ASSERTS_IN_RELEASE_BUILD()
159#endif
160
657a8a35
VZ
161#if wxDEBUG_LEVEL
162
163/*
164 wxOnAssert() is used by the debugging macros defined below. Different
ebd98179 165 overloads are needed because these macros can be used with or without wxT().
657a8a35
VZ
166
167 All of them are implemented in src/common/appcmn.cpp and unconditionally
168 call wxTheAssertHandler so the caller must check that it is non-NULL
169 (assert macros do it).
170 */
749b01f0 171
0accd1cf 172#if wxUSE_UNICODE
657a8a35
VZ
173
174// these overloads are the ones typically used by debugging macros: we have to
ebd98179 175// provide wxChar* msg version because it's common to use wxT() in the macros
657a8a35
VZ
176// and finally, we can't use const wx(char)* msg = NULL, because that would
177// be ambiguous
178//
179// also notice that these functions can't be inline as wxString is not defined
180// yet (and can't be as wxString code itself may use assertions)
2b760b6b 181extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
657a8a35
VZ
182 int line,
183 const char *func,
184 const char *cond);
185
2b760b6b 186extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
657a8a35
VZ
187 int line,
188 const char *func,
189 const char *cond,
190 const char *msg);
191
2b760b6b 192extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
657a8a35
VZ
193 int line,
194 const char *func,
195 const char *cond,
b625fff5 196 const wxChar *msg) ;
28efe654 197#endif /* wxUSE_UNICODE */
0accd1cf 198
657a8a35
VZ
199// this version is for compatibility with wx 2.8 Unicode build only, we don't
200// use it ourselves any more except in ANSI-only build in which case it is all
201// we need
2b760b6b 202extern WXDLLIMPEXP_BASE void wxOnAssert(const wxChar *file,
657a8a35
VZ
203 int line,
204 const char *func,
205 const wxChar *cond,
206 const wxChar *msg = NULL);
207
208// these overloads work when msg passed to debug macro is a string and we
209// also have to provide wxCStrData overload to resolve ambiguity which would
210// otherwise arise from wxASSERT( s.c_str() )
2b760b6b 211extern WXDLLIMPEXP_BASE void wxOnAssert(const wxString& file,
657a8a35
VZ
212 int line,
213 const wxString& func,
214 const wxString& cond,
215 const wxString& msg);
216
2b760b6b 217extern WXDLLIMPEXP_BASE void wxOnAssert(const wxString& file,
657a8a35
VZ
218 int line,
219 const wxString& func,
220 const wxString& cond);
221
2b760b6b 222extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
657a8a35
VZ
223 int line,
224 const char *func,
225 const char *cond,
226 const wxCStrData& msg);
227
2b760b6b 228extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
657a8a35
VZ
229 int line,
230 const char *func,
231 const char *cond,
232 const wxString& msg);
233
234#endif // wxDEBUG_LEVEL
749b01f0 235
c801d85f 236
657a8a35
VZ
237// ----------------------------------------------------------------------------
238// Debugging macros
239// ----------------------------------------------------------------------------
34cbe514 240
657a8a35
VZ
241/*
242 Assertion macros: check if the condition is true and call assert handler
243 (which will by default notify the user about failure) if it isn't.
8b0bd21b 244
657a8a35
VZ
245 wxASSERT and wxFAIL macros as well as wxTrap() function do nothing at all
246 if wxDEBUG_LEVEL is 0 however they do check their conditions at default
247 debug level 1, unlike the previous wxWidgets versions.
c801d85f 248
657a8a35
VZ
249 wxASSERT_LEVEL_2 is meant to be used for "expensive" asserts which should
250 normally be disabled because they have a big impact on performance and so
251 this macro only does anything if wxDEBUG_LEVEL >= 2.
252 */
253#if wxDEBUG_LEVEL
55fd62c1
VZ
254 // wxTrap() can be used to break into the debugger unconditionally
255 // (assuming the program is running under debugger, of course).
256 //
257 // If possible, we prefer to define it as a macro rather than as a function
258 // to open the debugger at the position where we trapped and not inside the
259 // trap function itself which is not very useful.
739c5499 260 #if wxCHECK_VISUALC_VERSION(7)
55fd62c1
VZ
261 #define wxTrap() __debugbreak()
262 #else
263 extern WXDLLIMPEXP_BASE void wxTrap();
264 #endif // Win VisualC
265
266 // Global flag used to indicate that assert macros should call wxTrap(): it
267 // is set by the default assert handler if the user answers yes to the
268 // question of whether to trap.
269 extern WXDLLIMPEXP_DATA_BASE(bool) wxTrapInAssert;
270
271 // This macro checks if the condition is true and calls the assert handler
272 // with the provided message if it isn't and finally traps if the special
273 // flag indicating that it should do it was set by the handler.
657a8a35 274 //
55fd62c1
VZ
275 // Notice that we don't use the handler return value for compatibility
276 // reasons (if we changed its return type, we'd need to change wxApp::
277 // OnAssertFailure() too which would break user code overriding it), hence
278 // the need for the ugly global flag.
657a8a35 279 #define wxASSERT_MSG(cond, msg) \
55fd62c1
VZ
280 wxSTATEMENT_MACRO_BEGIN \
281 if ( wxTheAssertHandler && !(cond) && \
282 (wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, \
283 #cond, msg), wxTrapInAssert) ) \
284 { \
285 wxTrapInAssert = false; \
286 wxTrap(); \
287 } \
288 wxSTATEMENT_MACRO_END
657a8a35
VZ
289
290 // a version without any additional message, don't use unless condition
291 // itself is fully self-explanatory
292 #define wxASSERT(cond) wxASSERT_MSG(cond, (const char*)NULL)
293
294 // wxFAIL is a special form of assert: it always triggers (and so is
295 // usually used in normally unreachable code)
55fd62c1
VZ
296 #define wxFAIL_COND_MSG(cond, msg) \
297 wxSTATEMENT_MACRO_BEGIN \
298 if ( wxTheAssertHandler && \
299 (wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, \
0a890608 300 cond, msg), wxTrapInAssert) ) \
55fd62c1
VZ
301 { \
302 wxTrapInAssert = false; \
303 wxTrap(); \
304 } \
305 wxSTATEMENT_MACRO_END
306
657a8a35
VZ
307 #define wxFAIL_MSG(msg) wxFAIL_COND_MSG("Assert failure", msg)
308 #define wxFAIL wxFAIL_MSG((const char*)NULL)
309#else // !wxDEBUG_LEVEL
310 #define wxTrap()
311
312 #define wxASSERT(cond)
313 #define wxASSERT_MSG(cond, msg)
314 #define wxFAIL
315 #define wxFAIL_MSG(msg)
316 #define wxFAIL_COND_MSG(cond, msg)
317#endif // wxDEBUG_LEVEL
318
319#if wxDEBUG_LEVEL >= 2
320 #define wxASSERT_LEVEL_2_MSG(cond, msg) wxASSERT_MSG(cond, msg)
321 #define wxASSERT_LEVEL_2(cond) wxASSERT(cond)
322#else // wxDEBUG_LEVEL < 2
b16f24dd
VZ
323 #define wxASSERT_LEVEL_2_MSG(cond, msg)
324 #define wxASSERT_LEVEL_2(cond)
657a8a35 325#endif
7ba4fbeb 326
975dc691
VZ
327// This is simply a wrapper for the standard abort() which is not available
328// under all platforms.
329//
330// It isn't really debug-related but there doesn't seem to be any better place
331// for it, so declare it here and define it in appbase.cpp, together with
332// wxTrap().
333extern void WXDLLIMPEXP_BASE wxAbort();
7ba4fbeb 334
657a8a35
VZ
335/*
336 wxCHECK macros always check their conditions, setting debug level to 0 only
337 makes them silent in case of failure, otherwise -- including at default
338 debug level 1 -- they call the assert handler if the condition is false
7ba4fbeb 339
657a8a35
VZ
340 They are supposed to be used only in invalid situation: for example, an
341 invalid parameter (e.g. a NULL pointer) is passed to a function. Instead of
342 dereferencing it and causing core dump the function might use
7ba4fbeb 343
657a8a35
VZ
344 wxCHECK_RET( p != NULL, "pointer can't be NULL" )
345*/
9d73af58 346
4c51a665 347// the generic macro: takes the condition to check, the statement to be executed
657a8a35 348// in case the condition is false and the message to pass to the assert handler
0d654944
SN
349#define wxCHECK2_MSG(cond, op, msg) \
350 if ( cond ) \
351 {} \
352 else \
353 { \
354 wxFAIL_COND_MSG(#cond, msg); \
355 op; \
356 } \
357 struct wxDummyCheckStruct /* just to force a semicolon */
7ba4fbeb 358
657a8a35
VZ
359// check which returns with the specified return code if the condition fails
360#define wxCHECK_MSG(cond, rc, msg) wxCHECK2_MSG(cond, return rc, msg)
361
362// check that expression is true, "return" if not (also FAILs in debug mode)
363#define wxCHECK(cond, rc) wxCHECK_MSG(cond, rc, (const char*)NULL)
364
365// check that expression is true, perform op if not
366#define wxCHECK2(cond, op) wxCHECK2_MSG(cond, op, (const char*)NULL)
367
993df040
VZ
368// special form of wxCHECK2: as wxCHECK, but for use in void functions
369//
370// NB: there is only one form (with msg parameter) and it's intentional:
371// there is no other way to tell the caller what exactly went wrong
372// from the void function (of course, the function shouldn't be void
373// to begin with...)
dfa0b52f 374#define wxCHECK_RET(cond, msg) wxCHECK2_MSG(cond, return, msg)
c801d85f 375
657a8a35 376
993df040
VZ
377// ----------------------------------------------------------------------------
378// Compile time asserts
379//
380// Unlike the normal assert and related macros above which are checked during
657a8a35 381// the program run-time the macros below will result in a compilation error if
993df040
VZ
382// the condition they check is false. This is usually used to check the
383// expressions containing sizeof()s which cannot be tested with the
384// preprocessor. If you can use the #if's, do use them as you can give a more
385// detailed error message then.
386// ----------------------------------------------------------------------------
8f5d9104
VZ
387
388/*
389 How this works (you don't have to understand it to be able to use the
390 macros): we rely on the fact that it is invalid to define a named bit field
391 in a struct of width 0. All the rest are just the hacks to minimize the
392 possibility of the compiler warnings when compiling this macro: in
393 particular, this is why we define a struct and not an object (which would
394 result in a warning about unused variable) and a named struct (otherwise we'd
395 get a warning about an unnamed struct not used to define an object!).
396 */
397
9bf41e06 398#define wxMAKE_UNIQUE_ASSERT_NAME wxMAKE_UNIQUE_NAME(wxAssert_)
8f5d9104
VZ
399
400/*
401 The second argument of this macro must be a valid C++ identifier and not a
402 string. I.e. you should use it like this:
403
404 wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
405
406 It may be used both within a function and in the global scope.
407*/
993df040 408#if defined(__WATCOMC__)
1c6f2414
WS
409 /* avoid "unused symbol" warning */
410 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
411 class wxMAKE_UNIQUE_ASSERT_NAME { \
412 unsigned int msg: expr; \
871cc651 413 wxMAKE_UNIQUE_ASSERT_NAME() { wxUnusedVar(msg); } \
1c6f2414 414 }
7126436a
JJ
415#elif defined( __VMS )
416namespace wxdebug{
417
418// HP aCC cannot deal with missing names for template value parameters
419template <bool x> struct STATIC_ASSERTION_FAILURE;
420
421template <> struct STATIC_ASSERTION_FAILURE<true> { enum { value = 1 }; };
422
423// HP aCC cannot deal with missing names for template value parameters
424template<int x> struct static_assert_test{};
425
426}
427 #define WX_JOIN( X, Y ) X##Y
428 #define WX_STATIC_ASSERT_BOOL_CAST(x) (bool)(x)
429 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
430 typedef ::wxdebug::static_assert_test<\
431 sizeof(::wxdebug::STATIC_ASSERTION_FAILURE< WX_STATIC_ASSERT_BOOL_CAST( expr ) >)>\
a4111501 432 WX_JOIN(wx_static_assert_typedef_, __LINE__)
1c6f2414
WS
433#else
434 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
435 struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
436#endif
8f5d9104 437
871cc651
VZ
438/*
439 When using VC++ 6 with "Edit and Continue" on, the compiler completely
440 mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
441 way to make "unique" assert names by specifying a unique prefix explicitly
442 */
443#define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
7bb688a8 444
17dc7ddd
WS
445#define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
446 struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
8de1759c 447
993df040 448// helpers for wxCOMPILE_TIME_ASSERT below, for private use only
8f5d9104
VZ
449#define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
450
993df040
VZ
451// a special case of compile time assert: check that the size of the given type
452// is at least the given number of bits
8f5d9104
VZ
453#define wxASSERT_MIN_BITSIZE(type, size) \
454 wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
455 wxMAKE_BITSIZE_MSG(type, size))
456
657a8a35 457
993df040
VZ
458// ----------------------------------------------------------------------------
459// other miscellaneous debugger-related functions
460// ----------------------------------------------------------------------------
a434b43f 461
c50a4038
VZ
462/*
463 Return true if we're running under debugger.
464
88ec47bb 465 Currently only really works under Win32 and just returns false elsewhere.
c50a4038 466 */
88ec47bb 467#if defined(__WIN32__)
993df040
VZ
468 extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
469#else // !Mac
470 inline bool wxIsDebuggerRunning() { return false; }
471#endif // Mac/!Mac
472
657a8a35
VZ
473// An assert helper used to avoid warning when testing constant expressions,
474// i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
475// expression being always true, but not using
476// wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
477//
478// NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and should no
479// longer be used.
480extern bool WXDLLIMPEXP_BASE wxAssertIsEqual(int x, int y);
481
482// Use of wxFalse instead of false suppresses compiler warnings about testing
483// constant expression
484extern WXDLLIMPEXP_DATA_BASE(const bool) wxFalse;
485
486#define wxAssertFailure wxFalse
487
488// This is similar to WXUNUSED() and useful for parameters which are only used
489// in assertions.
490#if wxDEBUG_LEVEL
491 #define WXUNUSED_UNLESS_DEBUG(param) param
492#else
493 #define WXUNUSED_UNLESS_DEBUG(param) WXUNUSED(param)
494#endif
495
496
993df040 497#endif // _WX_DEBUG_H_