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