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 // ----------------------------------------------------------------------------
  24 // Defines controlling the debugging macros
  25 // ----------------------------------------------------------------------------
  26
  27 // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
  28 // __WXDEBUG__ too
  29 #ifdef _DEBUG
  30     #ifndef __WXDEBUG__
  31         #define __WXDEBUG__
  32     #endif // !__WXDEBUG__
  33 #endif // _DEBUG
  34
  35 // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
  36 #ifdef NDEBUG
  37     #undef __WXDEBUG__
  38     #undef WXDEBUG
  39 #endif // NDEBUG
  40
  41 // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
  42 #ifdef __WXDEBUG__
  43     #if !defined(WXDEBUG) || !WXDEBUG
  44         #undef WXDEBUG
  45         #define WXDEBUG 1
  46     #endif // !WXDEBUG
  47 #endif // __WXDEBUG__
  48
  49 // ----------------------------------------------------------------------------
  50 // Debugging macros
  51 //
  52 // All debugging macros rely on ASSERT() which in turn calls the user-defined
  53 // OnAssert() function. To keep things simple, it's called even when the
  54 // expression is true (i.e. everything is ok) and by default does nothing: just
  55 // returns the same value back. But if you redefine it to do something more sexy
  56 // (popping up a message box in your favourite GUI, sending you e-mail or
  57 // whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  58 //
  59 // Warning: if you don't like advice on programming style, don't read
  60 // further! ;-)
  61 //
  62 // Extensive use of these macros is recommended! Remember that ASSERTs are
  63 // disabled in final build (without __WXDEBUG__ defined), so they add strictly
  64 // nothing to your program's code. On the other hand, CHECK macros do stay
  65 // even in release builds, but in general are not much of a burden, while
  66 // a judicious use of them might increase your program's stability.
  67 // ----------------------------------------------------------------------------
  68
  69 // Macros which are completely disabled in 'release' mode
  70 //
  71 // NB: these functions are implemented in src/common/appcmn.cpp
  72 #if defined(__WXDEBUG__)
  73   /*
  74     This function is called whenever one of debugging macros fails (i.e.
  75     condition is false in an assertion). To customize its behaviour, override
  76     wxApp::OnAssertFailure().
  77
  78     Parameters:
  79        szFile and nLine - file name and line number of the ASSERT
  80        szFunc           - function name of the ASSERT, may be NULL (NB: ASCII)
  81        szCond           - text form of the condition which failed
  82        szMsg            - optional message explaining the reason
  83   */
  84
  85   /* this version is for compatibility with wx 2.8 Unicode build only: */
  86   extern void WXDLLIMPEXP_BASE wxOnAssert(const wxChar *szFile,
  87                                           int nLine,
  88                                           const char *szFunc,
  89                                           const wxChar *szCond,
  90                                           const wxChar *szMsg = NULL);
  91
  92 #if wxUSE_UNICODE
  93   /* char versions are used by debugging macros; we have to provide
  94      wxChar* szMsg version because it's common to use _T() in the macros
  95      and finally, we can't use const wx(char)* szMsg = NULL, because that
  96      would be ambiguous: */
  97   extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
  98                                           int nLine,
  99                                           const char *szFunc,
 100                                           const char *szCond);
 101
 102   extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
 103                                           int nLine,
 104                                           const char *szFunc,
 105                                           const char *szCond,
 106                                           const char *szMsg);
 107
 108   extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
 109                                           int nLine,
 110                                           const char *szFunc,
 111                                           const char *szCond,
 112                                           const wxChar *szMsg);
 113 #endif /* wxUSE_UNICODE */
 114
 115   class WXDLLIMPEXP_FWD_BASE wxString;
 116   class WXDLLIMPEXP_FWD_BASE wxCStrData;
 117
 118   /* these two work when szMsg passed to debug macro is a string,
 119      we also have to provide wxCStrData overload to resolve ambiguity
 120      which would otherwise arise from wxASSERT( s.c_str() ): */
 121   extern void WXDLLIMPEXP_BASE wxOnAssert(const wxString& szFile,
 122                                           int nLine,
 123                                           const wxString& szFunc,
 124                                           const wxString& szCond,
 125                                           const wxString& szMsg);
 126
 127   extern void WXDLLIMPEXP_BASE wxOnAssert(const wxString& szFile,
 128                                           int nLine,
 129                                           const wxString& szFunc,
 130                                           const wxString& szCond);
 131
 132   extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
 133                                           int nLine,
 134                                           const char *szFunc,
 135                                           const char *szCond,
 136                                           const wxCStrData& msg);
 137
 138   extern void WXDLLIMPEXP_BASE wxOnAssert(const char *szFile,
 139                                           int nLine,
 140                                           const char *szFunc,
 141                                           const char *szCond,
 142                                           const wxString& szMsg);
 143
 144   // call this function to break into the debugger unconditionally (assuming
 145   // the program is running under debugger, of course)
 146   extern void WXDLLIMPEXP_BASE wxTrap();
 147
 148   // generic assert macro
 149   #define wxASSERT(cond) wxASSERT_MSG(cond, (const char*)NULL)
 150
 151
 152   // assert with additional message explaining its cause
 153
 154   // Note: some compilers will give  a warning (such as
 155   // "possible unwanted ;") when using a ";" instead of the "{}".
 156   #define wxASSERT_MSG(cond, msg)                                           \
 157     if ( cond )                                                             \
 158     {}                                                                      \
 159     else                                                                    \
 160         wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__, #cond, msg)
 161
 162   // special form of assert: always triggers it (in debug mode)
 163   #define wxFAIL wxFAIL_MSG((const char*)NULL)
 164
 165   // FAIL with some message
 166   #define wxFAIL_MSG(msg) wxFAIL_COND_MSG("wxAssertFailure", msg)
 167
 168   // FAIL with some message and a condition
 169   #define wxFAIL_COND_MSG(cond, msg)                                          \
 170       wxOnAssert(__FILE__, __LINE__,  __WXFUNCTION__, cond, msg)
 171
 172   // An assert helper used to avoid warning when testing constant expressions,
 173   // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
 174   // expression being always true, but not using
 175   // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
 176   //
 177   // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and should no
 178   //     longer be used.
 179   extern bool WXDLLIMPEXP_BASE wxAssertIsEqual(int x, int y);
 180 #else
 181   #define wxTrap()
 182
 183   // nothing to do in release mode (hopefully at this moment there are
 184   // no more bugs ;-)
 185   #define wxASSERT(cond)
 186   #define wxASSERT_MSG(cond, msg)
 187   #define wxFAIL
 188   #define wxFAIL_MSG(msg)
 189   #define wxFAIL_COND_MSG(cond, msg)
 190 #endif  /* __WXDEBUG__ */
 191
 192 // Use of wxFalse instead of false suppresses compiler warnings about testing
 193 // constant expression
 194 extern WXDLLIMPEXP_DATA_BASE(const bool) wxFalse;
 195
 196 #define wxAssertFailure wxFalse
 197
 198 // NB: the following macros also work in release mode!
 199
 200 /*
 201   These macros must be used only in invalid situation: for example, an
 202   invalid parameter (e.g. a NULL pointer) is passed to a function. Instead of
 203   dereferencing it and causing core dump the function might try using
 204   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 205 */
 206
 207 // check that expression is true, "return" if not (also FAILs in debug mode)
 208 #define wxCHECK(cond, rc)            wxCHECK_MSG(cond, rc, (const char*)NULL)
 209
 210 // as wxCHECK but with a message explaining why we fail
 211 #define wxCHECK_MSG(cond, rc, msg)   wxCHECK2_MSG(cond, return rc, msg)
 212
 213 // check that expression is true, perform op if not
 214 #define wxCHECK2(cond, op)           wxCHECK2_MSG(cond, op, (const char*)NULL)
 215
 216 // as wxCHECK2 but with a message explaining why we fail
 217
 218 #define wxCHECK2_MSG(cond, op, msg)                                       \
 219     if ( cond )                                                           \
 220     {}                                                                    \
 221     else                                                                  \
 222     {                                                                     \
 223         wxFAIL_COND_MSG(#cond, msg);                                      \
 224         op;                                                               \
 225     }                                                                     \
 226     struct wxDummyCheckStruct /* just to force a semicolon */
 227
 228 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 229 //
 230 // NB: there is only one form (with msg parameter) and it's intentional:
 231 //     there is no other way to tell the caller what exactly went wrong
 232 //     from the void function (of course, the function shouldn't be void
 233 //     to begin with...)
 234 #define wxCHECK_RET(cond, msg)       wxCHECK2_MSG(cond, return, msg)
 235
 236 // ----------------------------------------------------------------------------
 237 // Compile time asserts
 238 //
 239 // Unlike the normal assert and related macros above which are checked during
 240 // the program tun-time the macros below will result in a compilation error if
 241 // the condition they check is false. This is usually used to check the
 242 // expressions containing sizeof()s which cannot be tested with the
 243 // preprocessor. If you can use the #if's, do use them as you can give a more
 244 // detailed error message then.
 245 // ----------------------------------------------------------------------------
 246
 247 /*
 248   How this works (you don't have to understand it to be able to use the
 249   macros): we rely on the fact that it is invalid to define a named bit field
 250   in a struct of width 0. All the rest are just the hacks to minimize the
 251   possibility of the compiler warnings when compiling this macro: in
 252   particular, this is why we define a struct and not an object (which would
 253   result in a warning about unused variable) and a named struct (otherwise we'd
 254   get a warning about an unnamed struct not used to define an object!).
 255  */
 256
 257 #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_UNIQUE_NAME(wxAssert_)
 258
 259 /*
 260   The second argument of this macro must be a valid C++ identifier and not a
 261   string. I.e. you should use it like this:
 262
 263     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 264
 265  It may be used both within a function and in the global scope.
 266 */
 267 #if defined(__WATCOMC__)
 268     /* avoid "unused symbol" warning */
 269     #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 270         class wxMAKE_UNIQUE_ASSERT_NAME { \
 271           unsigned int msg: expr; \
 272           wxMAKE_UNIQUE_ASSERT_NAME() { wxUnusedVar(msg); } \
 273         }
 274 #else
 275     #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 276         struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 277 #endif
 278
 279 /*
 280    When using VC++ 6 with "Edit and Continue" on, the compiler completely
 281    mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
 282    way to make "unique" assert names by specifying a unique prefix explicitly
 283  */
 284 #define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
 285
 286 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
 287     struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
 288
 289 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 290 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 291
 292 // a special case of compile time assert: check that the size of the given type
 293 // is at least the given number of bits
 294 #define wxASSERT_MIN_BITSIZE(type, size) \
 295     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 296                           wxMAKE_BITSIZE_MSG(type, size))
 297
 298 // ----------------------------------------------------------------------------
 299 // other miscellaneous debugger-related functions
 300 // ----------------------------------------------------------------------------
 301
 302 /*
 303     Return true if we're running under debugger.
 304
 305     Currently this only really works under Win32 and Mac in CodeWarrior builds,
 306     it always returns false in other cases.
 307  */
 308 #if defined(__WXMAC__) || defined(__WIN32__)
 309     extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
 310 #else // !Mac
 311     inline bool wxIsDebuggerRunning() { return false; }
 312 #endif // Mac/!Mac
 313
 314 #endif // _WX_DEBUG_H_