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 #if defined(__cplusplus) && defined(__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 #ifdef __cplusplus
 126     // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
 127     // constant expression
 128     WXDLLIMPEXP_DATA_BASE(extern const bool) wxFalse;
 129 #endif
 130
 131 #define wxAssertFailure wxFalse
 132
 133 // special form of assert: always triggers it (in debug mode)
 134 #define wxFAIL                 wxASSERT(wxAssertFailure)
 135
 136 // FAIL with some message
 137 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxAssertFailure, msg)
 138
 139 // NB: the following macros work also in release mode!
 140
 141 /*
 142   These macros must be used only in invalid situation: for example, an
 143   invalid parameter (NULL pointer) is passed to a function. Instead of
 144   dereferencing it and causing core dump the function might try using
 145   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 146 */
 147
 148 // check that expression is true, "return" if not (also FAILs in debug mode)
 149 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 150
 151 // as wxCHECK but with a message explaining why we fail
 152 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 153
 154 // check that expression is true, perform op if not
 155 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 156
 157 // as wxCHECK2 but with a message explaining why we fail
 158 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 159
 160 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 161 //
 162 // NB: there is only one form (with msg parameter) and it's intentional:
 163 //     there is no other way to tell the caller what exactly went wrong
 164 //     from the void function (of course, the function shouldn't be void
 165 //     to begin with...)
 166 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 167
 168 // ----------------------------------------------------------------------------
 169 // Compile time asserts
 170 //
 171 // Unlike the normal assert and related macros above which are checked during
 172 // the program tun-time the macros below will result in a compilation error if
 173 // the condition they check is false. This is usually used to check the
 174 // expressions containing sizeof()s which cannot be tested with the
 175 // preprocessor. If you can use the #if's, do use them as you can give a more
 176 // detailed error message then.
 177 // ----------------------------------------------------------------------------
 178
 179 /*
 180   How this works (you don't have to understand it to be able to use the
 181   macros): we rely on the fact that it is invalid to define a named bit field
 182   in a struct of width 0. All the rest are just the hacks to minimize the
 183   possibility of the compiler warnings when compiling this macro: in
 184   particular, this is why we define a struct and not an object (which would
 185   result in a warning about unused variable) and a named struct (otherwise we'd
 186   get a warning about an unnamed struct not used to define an object!).
 187  */
 188
 189 #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_UNIQUE_NAME(wxAssert_)
 190
 191 /*
 192   The second argument of this macro must be a valid C++ identifier and not a
 193   string. I.e. you should use it like this:
 194
 195     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 196
 197  It may be used both within a function and in the global scope.
 198 */
 199 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 200     struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 201
 202 /*
 203    When using VC++ 6 with "Edit and Continue" on, the compiler completely
 204    mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
 205    way to make "unique" assert names by specifying a unique prefix explicitly
 206  */
 207 #define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
 208
 209 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
 210     struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
 211
 212 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 213 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 214
 215 // a special case of compile time assert: check that the size of the given type
 216 // is at least the given number of bits
 217 #define wxASSERT_MIN_BITSIZE(type, size) \
 218     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 219                           wxMAKE_BITSIZE_MSG(type, size))
 220
 221 // ----------------------------------------------------------------------------
 222 // other miscellaneous debugger-related functions
 223 // ----------------------------------------------------------------------------
 224
 225 // return true if we're running under debugger
 226 //
 227 // currently this only really works under Mac in CodeWarrior builds, it always
 228 // returns false otherwise
 229 #ifdef __cplusplus
 230     #ifdef __WXMAC__
 231         extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
 232     #else // !Mac
 233         inline bool wxIsDebuggerRunning() { return false; }
 234     #endif // Mac/!Mac
 235 #endif //__cplusplus
 236
 237 #endif  // _WX_DEBUG_H_
 238