1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Misc debug functions and macros
4 // Author: Vadim Zeitlin
7 // Copyright: (c) 1998-2009 Vadim Zeitlin <vadim@wxwidgets.org>
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
14 #if !defined(__WXWINCE__)
16 #endif // systems without assert.h
18 #include <limits.h> // for CHAR_BIT used below
20 #include "wx/chartype.h" // for __TFILE__ and wxChar
21 #include "wx/cpp.h" // for __WXFUNCTION__
22 #include "wx/dlimpexp.h" // for WXDLLIMPEXP_FWD_BASE
24 class WXDLLIMPEXP_FWD_BASE wxString
;
25 class WXDLLIMPEXP_FWD_BASE wxCStrData
;
27 // ----------------------------------------------------------------------------
28 // Defines controlling the debugging macros
29 // ----------------------------------------------------------------------------
32 wxWidgets can be built with several different levels of debug support
33 specified by the value of wxDEBUG_LEVEL constant:
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.
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)
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.
62 // Finally there is also a very old WXDEBUG macro not used anywhere at all, it
63 // is only defined for compatibility.
65 #if !defined(WXDEBUG) || !WXDEBUG
71 // ----------------------------------------------------------------------------
72 // Handling assertion failures
73 // ----------------------------------------------------------------------------
76 Type for the function called in case of assert failure, see
79 typedef void (*wxAssertHandler_t
)(const wxString
& file
,
87 // the global assert handler function, if it is NULL asserts don't check their
89 extern WXDLLIMPEXP_DATA_BASE(wxAssertHandler_t
) wxTheAssertHandler
;
92 Sets the function to be called in case of assertion failure.
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
99 While usually it is enough -- and more convenient -- to just override
100 OnAssertFailure(), to handle all assertion failures, including those
101 occurring even before wxApp object creation or after its destruction you
102 need to provide your assertion handler function.
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.
108 Notice that this function is not MT-safe, so you should call it before
109 starting any other threads.
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.
115 inline wxAssertHandler_t
wxSetAssertHandler(wxAssertHandler_t handler
)
117 const wxAssertHandler_t old
= wxTheAssertHandler
;
118 wxTheAssertHandler
= handler
;
123 Reset the default assert handler.
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).
128 extern void WXDLLIMPEXP_BASE
wxSetDefaultAssertHandler();
130 #else // !wxDEBUG_LEVEL
132 // provide empty stubs in case assertions are completely disabled
134 // NB: can't use WXUNUSED() here as we're included from wx/defs.h before it is
136 inline wxAssertHandler_t
wxSetAssertHandler(wxAssertHandler_t
/* handler */)
141 inline void wxSetDefaultAssertHandler() { }
143 #endif // wxDEBUG_LEVEL/!wxDEBUG_LEVEL
145 // simply a synonym for wxSetAssertHandler(NULL)
146 inline void wxDisableAsserts() { wxSetAssertHandler(NULL
); }
149 A macro which disables asserts for applications compiled in release build.
151 By default, wxIMPLEMENT_APP (or rather wxIMPLEMENT_WXWIN_MAIN) disable the
152 asserts in the applications compiled in the release build by calling this.
153 It does nothing if NDEBUG is not defined.
156 #define wxDISABLE_ASSERTS_IN_RELEASE_BUILD() wxDisableAsserts()
158 #define wxDISABLE_ASSERTS_IN_RELEASE_BUILD()
164 wxOnAssert() is used by the debugging macros defined below. Different
165 overloads are needed because these macros can be used with or without wxT().
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).
174 // these overloads are the ones typically used by debugging macros: we have to
175 // provide wxChar* msg version because it's common to use wxT() in the macros
176 // and finally, we can't use const wx(char)* msg = NULL, because that would
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)
181 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const char *file
,
186 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const char *file
,
192 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const char *file
,
197 #endif /* wxUSE_UNICODE */
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
202 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const wxChar
*file
,
206 const wxChar
*msg
= NULL
);
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() )
211 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const wxString
& file
,
213 const wxString
& func
,
214 const wxString
& cond
,
215 const wxString
& msg
);
217 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const wxString
& file
,
219 const wxString
& func
,
220 const wxString
& cond
);
222 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const char *file
,
226 const wxCStrData
& msg
);
228 extern WX_ATTRIBUTE_NORETURN WXDLLIMPEXP_BASE
void wxOnAssert(const char *file
,
232 const wxString
& msg
);
234 #endif // wxDEBUG_LEVEL
237 // ----------------------------------------------------------------------------
239 // ----------------------------------------------------------------------------
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.
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.
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.
254 // call this function to break into the debugger unconditionally (assuming
255 // the program is running under debugger, of course)
256 extern void WXDLLIMPEXP_BASE
wxTrap();
258 // assert checks if the condition is true and calls the assert handler with
259 // the provided message if it isn't
261 // NB: the macro is defined like this to ensure that nested if/else
262 // statements containing it are compiled in the same way whether it is
263 // defined as empty or not; also notice that we can't use ";" instead
264 // of "{}" as some compilers warn about "possible unwanted ;" then
265 #define wxASSERT_MSG(cond, msg) \
266 if ( !wxTheAssertHandler || (cond) ) \
269 wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, #cond, msg)
271 // a version without any additional message, don't use unless condition
272 // itself is fully self-explanatory
273 #define wxASSERT(cond) wxASSERT_MSG(cond, (const char*)NULL)
275 // wxFAIL is a special form of assert: it always triggers (and so is
276 // usually used in normally unreachable code)
277 #define wxFAIL_COND_MSG(cond, msg) \
278 if ( !wxTheAssertHandler ) \
281 wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, cond, msg)
282 #define wxFAIL_MSG(msg) wxFAIL_COND_MSG("Assert failure", msg)
283 #define wxFAIL wxFAIL_MSG((const char*)NULL)
284 #else // !wxDEBUG_LEVEL
287 #define wxASSERT(cond)
288 #define wxASSERT_MSG(cond, msg)
290 #define wxFAIL_MSG(msg)
291 #define wxFAIL_COND_MSG(cond, msg)
292 #endif // wxDEBUG_LEVEL
294 #if wxDEBUG_LEVEL >= 2
295 #define wxASSERT_LEVEL_2_MSG(cond, msg) wxASSERT_MSG(cond, msg)
296 #define wxASSERT_LEVEL_2(cond) wxASSERT(cond)
297 #else // wxDEBUG_LEVEL < 2
298 #define wxASSERT_LEVEL_2_MSG(cond, msg)
299 #define wxASSERT_LEVEL_2(cond)
302 // This is simply a wrapper for the standard abort() which is not available
303 // under all platforms.
305 // It isn't really debug-related but there doesn't seem to be any better place
306 // for it, so declare it here and define it in appbase.cpp, together with
308 extern void WXDLLIMPEXP_BASE
wxAbort();
311 wxCHECK macros always check their conditions, setting debug level to 0 only
312 makes them silent in case of failure, otherwise -- including at default
313 debug level 1 -- they call the assert handler if the condition is false
315 They are supposed to be used only in invalid situation: for example, an
316 invalid parameter (e.g. a NULL pointer) is passed to a function. Instead of
317 dereferencing it and causing core dump the function might use
319 wxCHECK_RET( p != NULL, "pointer can't be NULL" )
322 // the generic macro: takes the condition to check, the statement to be executed
323 // in case the condition is false and the message to pass to the assert handler
324 #define wxCHECK2_MSG(cond, op, msg) \
329 wxFAIL_COND_MSG(#cond, msg); \
332 struct wxDummyCheckStruct /* just to force a semicolon */
334 // check which returns with the specified return code if the condition fails
335 #define wxCHECK_MSG(cond, rc, msg) wxCHECK2_MSG(cond, return rc, msg)
337 // check that expression is true, "return" if not (also FAILs in debug mode)
338 #define wxCHECK(cond, rc) wxCHECK_MSG(cond, rc, (const char*)NULL)
340 // check that expression is true, perform op if not
341 #define wxCHECK2(cond, op) wxCHECK2_MSG(cond, op, (const char*)NULL)
343 // special form of wxCHECK2: as wxCHECK, but for use in void functions
345 // NB: there is only one form (with msg parameter) and it's intentional:
346 // there is no other way to tell the caller what exactly went wrong
347 // from the void function (of course, the function shouldn't be void
349 #define wxCHECK_RET(cond, msg) wxCHECK2_MSG(cond, return, msg)
352 // ----------------------------------------------------------------------------
353 // Compile time asserts
355 // Unlike the normal assert and related macros above which are checked during
356 // the program run-time the macros below will result in a compilation error if
357 // the condition they check is false. This is usually used to check the
358 // expressions containing sizeof()s which cannot be tested with the
359 // preprocessor. If you can use the #if's, do use them as you can give a more
360 // detailed error message then.
361 // ----------------------------------------------------------------------------
364 How this works (you don't have to understand it to be able to use the
365 macros): we rely on the fact that it is invalid to define a named bit field
366 in a struct of width 0. All the rest are just the hacks to minimize the
367 possibility of the compiler warnings when compiling this macro: in
368 particular, this is why we define a struct and not an object (which would
369 result in a warning about unused variable) and a named struct (otherwise we'd
370 get a warning about an unnamed struct not used to define an object!).
373 #define wxMAKE_UNIQUE_ASSERT_NAME wxMAKE_UNIQUE_NAME(wxAssert_)
376 The second argument of this macro must be a valid C++ identifier and not a
377 string. I.e. you should use it like this:
379 wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
381 It may be used both within a function and in the global scope.
383 #if defined(__WATCOMC__)
384 /* avoid "unused symbol" warning */
385 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
386 class wxMAKE_UNIQUE_ASSERT_NAME { \
387 unsigned int msg: expr; \
388 wxMAKE_UNIQUE_ASSERT_NAME() { wxUnusedVar(msg); } \
390 #elif defined( __VMS )
393 // HP aCC cannot deal with missing names for template value parameters
394 template <bool x
> struct STATIC_ASSERTION_FAILURE
;
396 template <> struct STATIC_ASSERTION_FAILURE
<true> { enum { value
= 1 }; };
398 // HP aCC cannot deal with missing names for template value parameters
399 template<int x
> struct static_assert_test
{};
402 #define WX_JOIN( X, Y ) X##Y
403 #define WX_STATIC_ASSERT_BOOL_CAST(x) (bool)(x)
404 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
405 typedef ::wxdebug::static_assert_test<\
406 sizeof(::wxdebug::STATIC_ASSERTION_FAILURE< WX_STATIC_ASSERT_BOOL_CAST( expr ) >)>\
407 WX_JOIN(wx_static_assert_typedef_, __LINE__)
409 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
410 struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
414 When using VC++ 6 with "Edit and Continue" on, the compiler completely
415 mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
416 way to make "unique" assert names by specifying a unique prefix explicitly
418 #define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
420 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
421 struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
423 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
424 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
426 // a special case of compile time assert: check that the size of the given type
427 // is at least the given number of bits
428 #define wxASSERT_MIN_BITSIZE(type, size) \
429 wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
430 wxMAKE_BITSIZE_MSG(type, size))
433 // ----------------------------------------------------------------------------
434 // other miscellaneous debugger-related functions
435 // ----------------------------------------------------------------------------
438 Return true if we're running under debugger.
440 Currently only really works under Win32 and just returns false elsewhere.
442 #if defined(__WIN32__)
443 extern bool WXDLLIMPEXP_BASE
wxIsDebuggerRunning();
445 inline bool wxIsDebuggerRunning() { return false; }
448 // An assert helper used to avoid warning when testing constant expressions,
449 // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
450 // expression being always true, but not using
451 // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
453 // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and should no
455 extern bool WXDLLIMPEXP_BASE
wxAssertIsEqual(int x
, int y
);
457 // Use of wxFalse instead of false suppresses compiler warnings about testing
458 // constant expression
459 extern WXDLLIMPEXP_DATA_BASE(const bool) wxFalse
;
461 #define wxAssertFailure wxFalse
463 // This is similar to WXUNUSED() and useful for parameters which are only used
466 #define WXUNUSED_UNLESS_DEBUG(param) param
468 #define WXUNUSED_UNLESS_DEBUG(param) WXUNUSED(param)
472 #endif // _WX_DEBUG_H_