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 // RCS-ID:      $Id$
   7 // Copyright:   (c) 1998-2009 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_DEBUG_H_
  12 #define _WX_DEBUG_H_
  13
  14 #if !defined(__WXPALMOS5__) && !defined(__WXWINCE__)
  15     #include  <assert.h>
  16 #endif // systems without assert.h
  17
  18 #include <limits.h>          // for CHAR_BIT used below
  19
  20 #include "wx/chartype.h"     // for __TFILE__ and wxChar
  21 #include "wx/cpp.h"          // for __WXFUNCTION__
  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     For compatibility reasons, currently wxDEBUG_LEVEL is defined if
  42     __WXDEBUG__ is defined but in the near future (2.9.1) the role of the flags
  43     will change and wxDEBUG_LEVEL will be the primary value with __WXDEBUG__
  44     only used for compatibility.
  45  */
  46
  47 // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
  48 // __WXDEBUG__ too
  49 #ifdef _DEBUG
  50     #ifndef __WXDEBUG__
  51         #define __WXDEBUG__
  52     #endif // !__WXDEBUG__
  53 #endif // _DEBUG
  54
  55 // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
  56 #ifdef NDEBUG
  57     #undef __WXDEBUG__
  58     #undef WXDEBUG
  59 #endif // NDEBUG
  60
  61 // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
  62 #ifdef __WXDEBUG__
  63     #if !defined(WXDEBUG) || !WXDEBUG
  64         #undef WXDEBUG
  65         #define WXDEBUG 1
  66     #endif // !WXDEBUG
  67 #endif // __WXDEBUG__
  68
  69 // temporarily define wxDEBUG_LEVEL as function of __WXDEBUG__
  70 #if !defined(wxDEBUG_LEVEL)
  71     #ifdef __WXDEBUG__
  72         #define wxDEBUG_LEVEL 1
  73     #else
  74         #define wxDEBUG_LEVEL 0
  75     #endif
  76 #endif // !defined(wxDEBUG_LEVEL)
  77
  78 // ----------------------------------------------------------------------------
  79 // Handling assertion failures
  80 // ----------------------------------------------------------------------------
  81
  82 /*
  83     Type for the function called in case of assert failure, see
  84     wxSetAssertHandler().
  85  */
  86 typedef void (*wxAssertHandler_t)(const wxString& file,
  87                                   int line,
  88                                   const wxString& func,
  89                                   const wxString& cond,
  90                                   const wxString& msg);
  91
  92 #if wxDEBUG_LEVEL
  93
  94 // the global assert handler function, if it is NULL asserts don't check their
  95 // conditions
  96 extern WXDLLIMPEXP_DATA_BASE(wxAssertHandler_t) wxTheAssertHandler;
  97
  98 /*
  99     Sets the function to be called in case of assertion failure.
 100
 101     The default assert handler forwards to wxApp::OnAssertFailure() whose
 102     default behaviour is, in turn, to show the standard assertion failure
 103     dialog if a wxApp object exists or shows the same dialog itself directly
 104     otherwise.
 105
 106     While usually it is enough -- and more convenient -- to just override
 107     OnAssertFailure(), to handle all assertion failures, including those
 108     occurring even before wxApp object creation or after its destruction you
 109     need to provide your assertion handler function.
 110
 111     This function also provides a simple way to disable all asserts: simply
 112     pass NULL pointer to it. Doing this will result in not even evaluating
 113     assert conditions at all, avoiding almost all run-time cost of asserts.
 114
 115     Notice that this function is not MT-safe, so you should call it before
 116     starting any other threads.
 117
 118     The return value of this function is the previous assertion handler. It can
 119     be called after any pre-processing by your handler and can also be restored
 120     later if you uninstall your handler.
 121  */
 122 inline wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler)
 123 {
 124     const wxAssertHandler_t old = wxTheAssertHandler;
 125     wxTheAssertHandler = handler;
 126     return old;
 127 }
 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 #endif // wxDEBUG_LEVEL/!wxDEBUG_LEVEL
 141
 142 // simply a synonym for wxSetAssertHandler(NULL)
 143 inline void wxDisableAsserts() { wxSetAssertHandler(NULL); }
 144
 145 #if wxDEBUG_LEVEL
 146
 147 /*
 148     wxOnAssert() is used by the debugging macros defined below. Different
 149     overloads are needed because these macros can be used with or without _T().
 150
 151     All of them are implemented in src/common/appcmn.cpp and unconditionally
 152     call wxTheAssertHandler so the caller must check that it is non-NULL
 153     (assert macros do it).
 154  */
 155
 156 #if wxUSE_UNICODE
 157
 158 // these overloads are the ones typically used by debugging macros: we have to
 159 // provide wxChar* msg version because it's common to use _T() in the macros
 160 // and finally, we can't use const wx(char)* msg = NULL, because that would
 161 // be ambiguous
 162 //
 163 // also notice that these functions can't be inline as wxString is not defined
 164 // yet (and can't be as wxString code itself may use assertions)
 165 extern void WXDLLIMPEXP_BASE wxOnAssert(const char *file,
 166                                         int line,
 167                                         const char *func,
 168                                         const char *cond);
 169
 170 extern void WXDLLIMPEXP_BASE wxOnAssert(const char *file,
 171                                         int line,
 172                                         const char *func,
 173                                         const char *cond,
 174                                         const char *msg);
 175
 176 extern void WXDLLIMPEXP_BASE wxOnAssert(const char *file,
 177                                         int line,
 178                                         const char *func,
 179                                         const char *cond,
 180                                         const wxChar *msg);
 181 #endif /* wxUSE_UNICODE */
 182
 183 // this version is for compatibility with wx 2.8 Unicode build only, we don't
 184 // use it ourselves any more except in ANSI-only build in which case it is all
 185 // we need
 186 extern void WXDLLIMPEXP_BASE wxOnAssert(const wxChar *file,
 187                                         int line,
 188                                         const char *func,
 189                                         const wxChar *cond,
 190                                         const wxChar *msg = NULL);
 191
 192 // these overloads work when msg passed to debug macro is a string and we
 193 // also have to provide wxCStrData overload to resolve ambiguity which would
 194 // otherwise arise from wxASSERT( s.c_str() )
 195 extern void WXDLLIMPEXP_BASE wxOnAssert(const wxString& file,
 196                                         int line,
 197                                         const wxString& func,
 198                                         const wxString& cond,
 199                                         const wxString& msg);
 200
 201 extern void WXDLLIMPEXP_BASE wxOnAssert(const wxString& file,
 202                                         int line,
 203                                         const wxString& func,
 204                                         const wxString& cond);
 205
 206 extern void WXDLLIMPEXP_BASE wxOnAssert(const char *file,
 207                                         int line,
 208                                         const char *func,
 209                                         const char *cond,
 210                                         const wxCStrData& msg);
 211
 212 extern void WXDLLIMPEXP_BASE wxOnAssert(const char *file,
 213                                         int line,
 214                                         const char *func,
 215                                         const char *cond,
 216                                         const wxString& msg);
 217
 218 #endif // wxDEBUG_LEVEL
 219
 220
 221 // ----------------------------------------------------------------------------
 222 // Debugging macros
 223 // ----------------------------------------------------------------------------
 224
 225 /*
 226     Assertion macros: check if the condition is true and call assert handler
 227     (which will by default notify the user about failure) if it isn't.
 228
 229     wxASSERT and wxFAIL macros as well as wxTrap() function do nothing at all
 230     if wxDEBUG_LEVEL is 0 however they do check their conditions at default
 231     debug level 1, unlike the previous wxWidgets versions.
 232
 233     wxASSERT_LEVEL_2 is meant to be used for "expensive" asserts which should
 234     normally be disabled because they have a big impact on performance and so
 235     this macro only does anything if wxDEBUG_LEVEL >= 2.
 236  */
 237 #if wxDEBUG_LEVEL
 238     // call this function to break into the debugger unconditionally (assuming
 239     // the program is running under debugger, of course)
 240     extern void WXDLLIMPEXP_BASE wxTrap();
 241
 242     // assert checks if the condition is true and calls the assert handler with
 243     // the provided message if it isn't
 244     //
 245     // NB: the macro is defined like this to ensure that nested if/else
 246     //     statements containing it are compiled in the same way whether it is
 247     //     defined as empty or not; also notice that we can't use ";" instead
 248     //     of "{}" as some compilers warn about "possible unwanted ;" then
 249     #define wxASSERT_MSG(cond, msg)                                           \
 250         if ( !wxTheAssertHandler || (cond) )                                  \
 251         {}                                                                    \
 252         else                                                                  \
 253             wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, #cond, msg)
 254
 255     // a version without any additional message, don't use unless condition
 256     // itself is fully self-explanatory
 257     #define wxASSERT(cond) wxASSERT_MSG(cond, (const char*)NULL)
 258
 259     // wxFAIL is a special form of assert: it always triggers (and so is
 260     // usually used in normally unreachable code)
 261     #define wxFAIL_COND_MSG(cond, msg) \
 262         if ( !wxTheAssertHandler )                                            \
 263         {}                                                                    \
 264         else                                                                  \
 265             wxOnAssert(__FILE__, __LINE__,  __WXFUNCTION__, cond, msg)
 266     #define wxFAIL_MSG(msg) wxFAIL_COND_MSG("Assert failure", msg)
 267     #define wxFAIL wxFAIL_MSG((const char*)NULL)
 268 #else // !wxDEBUG_LEVEL
 269     #define wxTrap()
 270
 271     #define wxASSERT(cond)
 272     #define wxASSERT_MSG(cond, msg)
 273     #define wxFAIL
 274     #define wxFAIL_MSG(msg)
 275     #define wxFAIL_COND_MSG(cond, msg)
 276 #endif  // wxDEBUG_LEVEL
 277
 278 #if wxDEBUG_LEVEL >= 2
 279     #define wxASSERT_LEVEL_2_MSG(cond, msg) wxASSERT_MSG(cond, msg)
 280     #define wxASSERT_LEVEL_2(cond) wxASSERT(cond)
 281 #else // wxDEBUG_LEVEL < 2
 282     #define wxASSERT_LEVEL_2_MSG(cond, msg)
 283     #define wxASSERT_LEVEL_2(cond)
 284 #endif
 285
 286
 287 /*
 288     wxCHECK macros always check their conditions, setting debug level to 0 only
 289     makes them silent in case of failure, otherwise -- including at default
 290     debug level 1 -- they call the assert handler if the condition is false
 291
 292     They are supposed to be used only in invalid situation: for example, an
 293     invalid parameter (e.g. a NULL pointer) is passed to a function. Instead of
 294     dereferencing it and causing core dump the function might use
 295
 296         wxCHECK_RET( p != NULL, "pointer can't be NULL" )
 297 */
 298
 299 // the generic macro: takes the condition to check, the statement to be execute
 300 // in case the condition is false and the message to pass to the assert handler
 301 #define wxCHECK2_MSG(cond, op, msg)                                       \
 302     if ( cond )                                                           \
 303     {}                                                                    \
 304     else                                                                  \
 305     {                                                                     \
 306         wxFAIL_COND_MSG(#cond, msg);                                      \
 307         op;                                                               \
 308     }                                                                     \
 309     struct wxDummyCheckStruct /* just to force a semicolon */
 310
 311 // check which returns with the specified return code if the condition fails
 312 #define wxCHECK_MSG(cond, rc, msg)   wxCHECK2_MSG(cond, return rc, msg)
 313
 314 // check that expression is true, "return" if not (also FAILs in debug mode)
 315 #define wxCHECK(cond, rc)            wxCHECK_MSG(cond, rc, (const char*)NULL)
 316
 317 // check that expression is true, perform op if not
 318 #define wxCHECK2(cond, op)           wxCHECK2_MSG(cond, op, (const char*)NULL)
 319
 320 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 321 //
 322 // NB: there is only one form (with msg parameter) and it's intentional:
 323 //     there is no other way to tell the caller what exactly went wrong
 324 //     from the void function (of course, the function shouldn't be void
 325 //     to begin with...)
 326 #define wxCHECK_RET(cond, msg)       wxCHECK2_MSG(cond, return, msg)
 327
 328
 329 // ----------------------------------------------------------------------------
 330 // Compile time asserts
 331 //
 332 // Unlike the normal assert and related macros above which are checked during
 333 // the program run-time the macros below will result in a compilation error if
 334 // the condition they check is false. This is usually used to check the
 335 // expressions containing sizeof()s which cannot be tested with the
 336 // preprocessor. If you can use the #if's, do use them as you can give a more
 337 // detailed error message then.
 338 // ----------------------------------------------------------------------------
 339
 340 /*
 341   How this works (you don't have to understand it to be able to use the
 342   macros): we rely on the fact that it is invalid to define a named bit field
 343   in a struct of width 0. All the rest are just the hacks to minimize the
 344   possibility of the compiler warnings when compiling this macro: in
 345   particular, this is why we define a struct and not an object (which would
 346   result in a warning about unused variable) and a named struct (otherwise we'd
 347   get a warning about an unnamed struct not used to define an object!).
 348  */
 349
 350 #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_UNIQUE_NAME(wxAssert_)
 351
 352 /*
 353   The second argument of this macro must be a valid C++ identifier and not a
 354   string. I.e. you should use it like this:
 355
 356     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 357
 358  It may be used both within a function and in the global scope.
 359 */
 360 #if defined(__WATCOMC__)
 361     /* avoid "unused symbol" warning */
 362     #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 363         class wxMAKE_UNIQUE_ASSERT_NAME { \
 364           unsigned int msg: expr; \
 365           wxMAKE_UNIQUE_ASSERT_NAME() { wxUnusedVar(msg); } \
 366         }
 367 #else
 368     #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 369         struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 370 #endif
 371
 372 /*
 373    When using VC++ 6 with "Edit and Continue" on, the compiler completely
 374    mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
 375    way to make "unique" assert names by specifying a unique prefix explicitly
 376  */
 377 #define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
 378
 379 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
 380     struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
 381
 382 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 383 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 384
 385 // a special case of compile time assert: check that the size of the given type
 386 // is at least the given number of bits
 387 #define wxASSERT_MIN_BITSIZE(type, size) \
 388     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 389                           wxMAKE_BITSIZE_MSG(type, size))
 390
 391
 392 // ----------------------------------------------------------------------------
 393 // other miscellaneous debugger-related functions
 394 // ----------------------------------------------------------------------------
 395
 396 /*
 397     Return true if we're running under debugger.
 398
 399     Currently this only really works under Win32 and Mac in CodeWarrior builds,
 400     it always returns false in other cases.
 401  */
 402 #if defined(__WXMAC__) || defined(__WIN32__)
 403     extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
 404 #else // !Mac
 405     inline bool wxIsDebuggerRunning() { return false; }
 406 #endif // Mac/!Mac
 407
 408 // An assert helper used to avoid warning when testing constant expressions,
 409 // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
 410 // expression being always true, but not using
 411 // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
 412 //
 413 // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and should no
 414 //     longer be used.
 415 extern bool WXDLLIMPEXP_BASE wxAssertIsEqual(int x, int y);
 416
 417 // Use of wxFalse instead of false suppresses compiler warnings about testing
 418 // constant expression
 419 extern WXDLLIMPEXP_DATA_BASE(const bool) wxFalse;
 420
 421 #define wxAssertFailure wxFalse
 422
 423 // This is similar to WXUNUSED() and useful for parameters which are only used
 424 // in assertions.
 425 #if wxDEBUG_LEVEL
 426     #define WXUNUSED_UNLESS_DEBUG(param)  param
 427 #else
 428     #define WXUNUSED_UNLESS_DEBUG(param)  WXUNUSED(param)
 429 #endif
 430
 431
 432 #endif // _WX_DEBUG_H_