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 licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef   _WX_DEBUG_H_
  13 #define   _WX_DEBUG_H_
  14
  15 #ifndef __WXWINCE__
  16 #include  <assert.h>
  17 #endif
  18 #include  <limits.h>            // for CHAR_BIT used below
  19
  20 #include  "wx/wxchar.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 // ----------------------------------------------------------------------------
  49 // Debugging macros
  50 //
  51 // All debugging macros rely on ASSERT() which in turn calls user-defined
  52 // OnAssert() function. To keep things simple, it's called even when the
  53 // expression is TRUE (i.e. everything is ok) and by default does nothing: just
  54 // returns the same value back. But if you redefine it to do something more sexy
  55 // (popping up a message box in your favourite GUI, sending you e-mail or
  56 // whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  57 //
  58 // Warning: if you don't like advice on programming style, don't read
  59 // further! ;-)
  60 //
  61 // Extensive use of these macros is recommended! Remember that ASSERTs are
  62 // disabled in final build (without __WXDEBUG__ defined), so they add strictly
  63 // nothing to your program's code. On the other hand, CHECK macros do stay
  64 // even in release builds, but in general are not much of a burden, while
  65 // a judicious use of them might increase your program's stability.
  66 // ----------------------------------------------------------------------------
  67
  68 // Macros which are completely disabled in 'release' mode
  69 //
  70 // NB: these functions are implemented in src/common/appcmn.cpp
  71 #ifdef  __WXDEBUG__
  72   /*
  73     this function may be redefined to do something non trivial and is called
  74     whenever one of debugging macros fails (i.e. condition is false in an
  75     assertion)
  76
  77     parameters:
  78        szFile and nLine - file name and line number of the ASSERT
  79        szMsg            - optional message explaining the reason
  80   */
  81   extern void WXDLLIMPEXP_BASE wxOnAssert(const wxChar *szFile,
  82                                           int nLine,
  83                                           const wxChar *szCond,
  84                                           const wxChar *szMsg = NULL);
  85
  86   // call this function to break into the debugger unconditionally (assuming
  87   // the program is running under debugger, of course)
  88   extern void WXDLLIMPEXP_BASE wxTrap();
  89
  90   // helper function used to implement wxASSERT and wxASSERT_MSG
  91   //
  92   // note using "int" and not "bool" for cond to avoid VC++ warnings about
  93   // implicit conversions when doing "wxAssert( pointer )" and also use of
  94   // "!!cond" below to ensure that everything is converted to int
  95   extern void WXDLLIMPEXP_BASE wxAssert(int cond,
  96                                         const wxChar *szFile,
  97                                         int nLine,
  98                                         const wxChar *szCond,
  99                                         const wxChar *szMsg = NULL) ;
 100
 101   // generic assert macro
 102   #define wxASSERT(cond) wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond))
 103
 104   // assert with additional message explaining it's cause
 105   #define wxASSERT_MSG(cond, msg) \
 106     wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond), msg)
 107
 108   // an assert helper used to avoid warning when testing constant expressions,
 109   // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
 110   // expression being always true, but not using
 111   // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
 112   //
 113   // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and shouldn't be
 114   //     used any longer
 115   extern bool WXDLLIMPEXP_BASE wxAssertIsEqual(int x, int y);
 116 #else
 117   #define wxTrap()
 118
 119   // nothing to do in release modes (hopefully at this moment there are
 120   // no more bugs ;-)
 121   #define wxASSERT(cond)
 122   #define wxASSERT_MSG(x, m)
 123 #endif  //__WXDEBUG__
 124
 125 // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
 126 // constant expression
 127 WXDLLIMPEXP_DATA_BASE(extern const bool) wxFalse;
 128 #define wxAssertFailure wxFalse
 129
 130 // special form of assert: always triggers it (in debug mode)
 131 #define wxFAIL                 wxASSERT(wxAssertFailure)
 132
 133 // FAIL with some message
 134 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxAssertFailure, msg)
 135
 136 // NB: the following macros work also in release mode!
 137
 138 /*
 139   These macros must be used only in invalid situation: for example, an
 140   invalid parameter (NULL pointer) is passed to a function. Instead of
 141   dereferencing it and causing core dump the function might try using
 142   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 143 */
 144
 145 // check that expression is true, "return" if not (also FAILs in debug mode)
 146 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 147
 148 // as wxCHECK but with a message explaining why we fail
 149 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 150
 151 // check that expression is true, perform op if not
 152 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 153
 154 // as wxCHECK2 but with a message explaining why we fail
 155 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 156
 157 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 158 //
 159 // NB: there is only one form (with msg parameter) and it's intentional:
 160 //     there is no other way to tell the caller what exactly went wrong
 161 //     from the void function (of course, the function shouldn't be void
 162 //     to begin with...)
 163 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 164
 165 // ----------------------------------------------------------------------------
 166 // Compile time asserts
 167 //
 168 // Unlike the normal assert and related macros above which are checked during
 169 // the program tun-time the macros below will result in a compilation error if
 170 // the condition they check is false. This is usually used to check the
 171 // expressions containing sizeof()s which cannot be tested with the
 172 // preprocessor. If you can use the #if's, do use them as you can give a more
 173 // detailed error message then.
 174 // ----------------------------------------------------------------------------
 175
 176 /*
 177   How this works (you don't have to understand it to be able to use the
 178   macros): we rely on the fact that it is invalid to define a named bit field
 179   in a struct of width 0. All the rest are just the hacks to minimize the
 180   possibility of the compiler warnings when compiling this macro: in
 181   particular, this is why we define a struct and not an object (which would
 182   result in a warning about unused variable) and a named struct (otherwise we'd
 183   get a warning about an unnamed struct not used to define an object!).
 184  */
 185
 186 #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_UNIQUE_NAME(wxAssert_)
 187 #define wxMAKE_UNIQUE_ASSERT_NAME2(text)    wxMAKE_UNIQUE_NAME(text)
 188
 189 /*
 190   The second argument of this macro must be a valid C++ identifier and not a
 191   string. I.e. you should use it like this:
 192
 193     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 194
 195  It may be used both within a function and in the global scope.
 196 */
 197 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 198     struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 199
 200 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
 201     struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
 202
 203 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 204 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 205
 206 // a special case of compile time assert: check that the size of the given type
 207 // is at least the given number of bits
 208 #define wxASSERT_MIN_BITSIZE(type, size) \
 209     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 210                           wxMAKE_BITSIZE_MSG(type, size))
 211
 212 // ----------------------------------------------------------------------------
 213 // other miscellaneous debugger-related functions
 214 // ----------------------------------------------------------------------------
 215
 216 // return true if we're running under debugger
 217 //
 218 // currently this only really works under Mac in CodeWarrior builds, it always
 219 // returns false otherwise
 220 #ifdef __WXMAC__
 221     extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
 222 #else // !Mac
 223     inline bool wxIsDebuggerRunning() { return false; }
 224 #endif // Mac/!Mac
 225
 226 #endif  // _WX_DEBUG_H_
 227