include/wx/debug.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/debug.h
   3 // Purpose:     Misc debug functions and macros
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     29/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef   _WX_DEBUG_H_
  13 #define   _WX_DEBUG_H_
  14
  15 #include  <assert.h>
  16 #include  <limits.h>            // for CHAR_BIT used below
  17
  18 #include  "wx/wxchar.h"         // for __TFILE__ and wxChar
  19
  20 // ----------------------------------------------------------------------------
  21 // Defines controlling the debugging macros
  22 // ----------------------------------------------------------------------------
  23
  24 // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
  25 // __WXDEBUG__ too
  26 #ifdef _DEBUG
  27     #ifndef __WXDEBUG__
  28         #define __WXDEBUG__
  29     #endif // !__WXDEBUG__
  30 #endif // _DEBUG
  31
  32 // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
  33 #ifdef NDEBUG
  34     #undef __WXDEBUG__
  35     #undef WXDEBUG
  36 #endif // NDEBUG
  37
  38 // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
  39 #ifdef __WXDEBUG__
  40     #if !defined(WXDEBUG) || !WXDEBUG
  41         #undef WXDEBUG
  42         #define WXDEBUG 1
  43     #endif // !WXDEBUG
  44 #endif // __WXDEBUG__
  45
  46 // ----------------------------------------------------------------------------
  47 // Debugging macros
  48 //
  49 // All debugging macros rely on ASSERT() which in turn calls user-defined
  50 // OnAssert() function. To keep things simple, it's called even when the
  51 // expression is TRUE (i.e. everything is ok) and by default does nothing: just
  52 // returns the same value back. But if you redefine it to do something more sexy
  53 // (popping up a message box in your favourite GUI, sending you e-mail or
  54 // whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  55 //
  56 // Warning: if you don't like advices on programming style, don't read
  57 // further! ;-)
  58 //
  59 // Extensive use of these macros is recommended! Remember that ASSERTs are
  60 // disabled in final (without __WXDEBUG__ defined) build, so they add strictly
  61 // nothing to your program's code. On the other hand, CHECK macros do stay
  62 // even in release builds, but in general are not much of a burden, while
  63 // a judicious use of them might increase your program's stability.
  64 // ----------------------------------------------------------------------------
  65
  66 // Macros which are completely disabled in 'release' mode
  67 //
  68 // NB: these functions are implemented in src/common/appcmn.cpp
  69 #ifdef  __WXDEBUG__
  70   /*
  71     this function may be redefined to do something non trivial and is called
  72     whenever one of debugging macros fails (i.e. condition is false in an
  73     assertion)
  74
  75     parameters:
  76        szFile and nLine - file name and line number of the ASSERT
  77        szMsg            - optional message explaining the reason
  78   */
  79   extern void WXDLLEXPORT wxOnAssert(const wxChar *szFile,
  80                                      int nLine,
  81                                      const wxChar *szMsg = NULL);
  82
  83   // call this function to break into the debugger uncodnitionally (assuming
  84   // the program is running under debugger, of course)
  85   extern void WXDLLEXPORT wxTrap();
  86
  87   /*
  88     notice the usage of else at the end of wxASSERT macro: this ensures that
  89     the following code
  90
  91         if ( ... )
  92             wxASSERT(...);
  93         else
  94             ...
  95
  96     works like expected: if there were no "else", the one in the code above
  97     would be matched with a wrong "if"
  98   */
  99
 100   // generic assert macro
 101   #define wxASSERT(cond) if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__); else
 102
 103   // assert with additional message explaining it's cause
 104   #define wxASSERT_MSG(cond, msg) \
 105                     if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__, msg); else
 106
 107   // an assert helper used to avoid warning when testing constant expressions,
 108   // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
 109   // expression being always true, but not using
 110   // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
 111   extern bool WXDLLEXPORT wxAssertIsEqual(int x, int y);
 112 #else
 113   #define wxTrap()
 114
 115   // nothing to do in release modes (hopefully at this moment there are
 116   // no more bugs ;-)
 117   #define wxASSERT(cond)
 118   #define wxASSERT_MSG(x, m)
 119 #endif  //__WXDEBUG__
 120
 121 // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
 122 // constant expression
 123 WXDLLEXPORT_DATA(extern const bool) wxFalse;
 124
 125 // special form of assert: always triggers it (in debug mode)
 126 #define wxFAIL                 wxASSERT(wxFalse)
 127
 128 // FAIL with some message
 129 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxFalse, msg)
 130
 131 // NB: the following macros work also in release mode!
 132
 133 /*
 134   These macros must be used only in invalid situation: for example, an
 135   invalid parameter (NULL pointer) is passed to a function. Instead of
 136   dereferencing it and causing core dump the function might try using
 137   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 138 */
 139
 140 // check that expression is true, "return" if not (also FAILs in debug mode)
 141 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 142
 143 // as wxCHECK but with a message explaining why we fail
 144 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 145
 146 // check that expression is true, perform op if not
 147 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 148
 149 // as wxCHECK2 but with a message explaining why we fail
 150 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 151
 152 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 153 //
 154 // NB: there is only one form (with msg parameter) and it's intentional:
 155 //     there is no other way to tell the caller what exactly went wrong
 156 //     from the void function (of course, the function shouldn't be void
 157 //     to begin with...)
 158 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 159
 160 // ----------------------------------------------------------------------------
 161 // Compile time asserts
 162 //
 163 // Unlike the normal assert and related macros above which are checked during
 164 // the program tun-time the macros below will result in a compilation error if
 165 // the condition they check is false. This is usually used to check the
 166 // expressions containing sizeof()s which cannot be tested with the
 167 // preprocessor. If you can use the #if's, do use them as you can give a more
 168 // detailed error message then.
 169 // ----------------------------------------------------------------------------
 170
 171 /*
 172   How this works (you don't have to understand it to be able to use the
 173   macros): we rely on the fact that it is invalid to define a named bit field
 174   in a struct of width 0. All the rest are just the hacks to minimize the
 175   possibility of the compiler warnings when compiling this macro: in
 176   particular, this is why we define a struct and not an object (which would
 177   result in a warning about unused variable) and a named struct (otherwise we'd
 178   get a warning about an unnamed struct not used to define an object!).
 179  */
 180
 181 #define wxMAKE_ASSERT_NAME_HELPER(line) wxAssert_ ## line
 182 #define wxMAKE_ASSERT_NAME(line)        wxMAKE_ASSERT_NAME_HELPER(line)
 183 #define wxMAKE_UNIQUE_ASSERT_NAME       wxMAKE_ASSERT_NAME(__LINE__)
 184
 185 /*
 186   The second argument of this macro must be a valid C++ identifier and not a
 187   string. I.e. you should use it like this:
 188
 189     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 190
 191  It may be used both within a function and in the global scope.
 192 */
 193 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 194     struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 195
 196 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 197 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 198
 199 // a special case of compile time assert: check that the size of the given type
 200 // is at least the given number of bits
 201 #define wxASSERT_MIN_BITSIZE(type, size) \
 202     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 203                           wxMAKE_BITSIZE_MSG(type, size))
 204
 205 #endif  // _WX_DEBUG_H_
 206