include/wx/debug.h

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