interface/wx/debug.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        debug.h
   3 // Purpose:     interface of global functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /** @addtogroup group_funcmacro_debug */
  10 //@{
  11
  12 /**
  13     @def wxDEBUG_LEVEL
  14
  15     Preprocessor symbol defining the level of debug support available.
  16
  17     Currently wxDEBUG_LEVEL is 0 in release builds (__WXDEBUG__ not defined)
  18     and 1 in debug builds (it is). In the immediate future this will change
  19     however and this symbol will be defined directly as 0, 1 or 2 while
  20     __WXDEBUG__ won't be used by wxWidgets any longer.
  21
  22     @header{wx/debug.h}
  23  */
  24 #define wxDEBUG_LEVEL
  25
  26 /**
  27     Type for the function called in case of assert failure.
  28
  29     @see wxSetAssertHandler()
  30  */
  31 typedef void (*wxAssertHandler_t)(const wxString& file,
  32                                   int line,
  33                                   const wxString& func,
  34                                   const wxString& cond,
  35                                   const wxString& msg);
  36
  37 /**
  38     Assert macro. An error message will be generated if the condition is @false in
  39     debug mode, but nothing will be done in the release build.
  40
  41     Please note that the condition in wxASSERT() should have no side effects
  42     because it will not be executed in release mode at all.
  43
  44     This macro should be used to catch (in debug builds) logical errors done
  45     by the programmer.
  46
  47     @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT()
  48
  49     @header{wx/debug.h}
  50 */
  51 #define wxASSERT( condition )
  52
  53 /**
  54     Assert macro for expensive run-time checks.
  55
  56     This macro does nothing unless wxDEBUG_LEVEL is 2 or more and is meant to
  57     be used for the assertions with noticeable performance impact and which,
  58     hence, should be disabled during run-time.
  59
  60     If wxDEBUG_LEVEL is 2 or more, it becomes the same as wxASSERT().
  61
  62     @header{wx/debug.h}
  63  */
  64 #define wxASSERT_LEVEL_2( condition )
  65
  66 /**
  67     Assert macro with a custom message for expensive run-time checks.
  68
  69     If wxDEBUG_LEVEL is 2 or more, this is the same as wxASSERT_MSG(),
  70     otherwise it doesn't do anything at all.
  71
  72     @see wxASSERT_LEVEL_2()
  73
  74     @header{wx/debug.h}
  75  */
  76 #define wxASSERT_LEVEL_2_MSG( condition, msg)
  77
  78
  79 /**
  80     This macro results in a @ref wxCOMPILE_TIME_ASSERT "compile time assertion failure"
  81     if the size of the given @c type is less than @c size bits.
  82
  83     This macro should be used to catch (in debug builds) logical errors done
  84     by the programmer.
  85
  86     You may use it like this, for example:
  87
  88     @code
  89     // we rely on the int being able to hold values up to 2^32
  90     wxASSERT_MIN_BITSIZE(int, 32);
  91
  92     // can't work with the platforms using UTF-8 for wchar_t
  93     wxASSERT_MIN_BITSIZE(wchar_t, 16);
  94     @endcode
  95
  96     @header{wx/debug.h}
  97 */
  98 #define wxASSERT_MIN_BITSIZE( type, size )
  99
 100 /**
 101     Assert macro with message.
 102     An error message will be generated if the condition is @false.
 103
 104     This macro should be used to catch (in debug builds) logical errors done
 105     by the programmer.
 106
 107     @see wxASSERT(), wxCOMPILE_TIME_ASSERT()
 108
 109     @header{wx/debug.h}
 110 */
 111 #define wxASSERT_MSG( condition, message )
 112
 113 /**
 114     Checks that the condition is @true, returns with the given return value if
 115     not (stops execution in debug mode). This check is done even in release mode.
 116
 117     This macro should be used to catch (both in debug and release builds) logical
 118     errors done by the programmer.
 119
 120     @header{wx/debug.h}
 121 */
 122 #define wxCHECK( condition, retValue )
 123
 124 /**
 125     Checks that the condition is @true, returns with the given return value if
 126     not (stops execution in debug mode). This check is done even in release mode.
 127
 128     This macro may be only used in non-void functions, see also wxCHECK_RET().
 129
 130     This macro should be used to catch (both in debug and release builds) logical
 131     errors done by the programmer.
 132
 133     @header{wx/debug.h}
 134 */
 135 #define wxCHECK_MSG( condition, retValue, message )
 136
 137 /**
 138     Checks that the condition is @true, and returns if not (stops execution
 139     with the given error message in debug mode). This check is done even in
 140     release mode.
 141
 142     This macro should be used in void functions instead of wxCHECK_MSG().
 143
 144     This macro should be used to catch (both in debug and release builds) logical
 145     errors done by the programmer.
 146
 147     @header{wx/debug.h}
 148 */
 149 #define wxCHECK_RET( condition, message )
 150
 151 /**
 152     Checks that the condition is @true, and if not, it will wxFAIL() and
 153     execute the given @c operation if it is not. This is a generalisation of
 154     wxCHECK() and may be used when something else than just returning from the
 155     function must be done when the @c condition is @false. This check is done
 156     even in release mode.
 157
 158     This macro should be used to catch (both in debug and release builds) logical
 159     errors done by the programmer.
 160
 161     @header{wx/debug.h}
 162 */
 163 #define wxCHECK2(condition, operation)
 164
 165 /**
 166     This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified
 167     @c message is called instead of wxFAIL() if the @c condition is @false.
 168
 169     This macro should be used to catch (both in debug and release builds) logical
 170     errors done by the programmer.
 171
 172     @header{wx/debug.h}
 173 */
 174 #define wxCHECK2_MSG( condition, operation, message )
 175
 176 /**
 177     Using wxCOMPILE_TIME_ASSERT() results in a compilation error if the
 178     specified @c condition is @false. The compiler error message should include
 179     the @c message identifier - please note that it must be a valid C++
 180     identifier and not a string unlike in the other cases.
 181
 182     This macro is mostly useful for testing the expressions involving the
 183     @c sizeof operator as they can't be tested by the preprocessor but it is
 184     sometimes desirable to test them at the compile time.
 185
 186     Note that this macro internally declares a struct whose name it tries to
 187     make unique by using the @c __LINE__ in it but it may still not work if you
 188     use it on the same line in two different source files. In this case you may
 189     either change the line in which either of them appears on or use the
 190     wxCOMPILE_TIME_ASSERT2() macro.
 191
 192     Also note that Microsoft Visual C++ has a bug which results in compiler
 193     errors if you use this macro with 'Program Database For Edit And Continue'
 194     (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok
 195     though) for the code making use of this macro.
 196
 197     This macro should be used to catch misconfigurations at compile-time.
 198
 199     @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE()
 200
 201     @header{wx/debug.h}
 202 */
 203 #define wxCOMPILE_TIME_ASSERT( condition, message )
 204
 205 /**
 206     This macro is identical to wxCOMPILE_TIME_ASSERT() except that it allows
 207     you to specify a unique @c name for the struct internally defined by this
 208     macro to avoid getting the compilation errors described for
 209     wxCOMPILE_TIME_ASSERT().
 210
 211     This macro should be used to catch misconfigurations at compile-time.
 212
 213     @header{wx/debug.h}
 214 */
 215 #define wxCOMPILE_TIME_ASSERT2(condition, message, name)
 216
 217 /**
 218     Disable the condition checks in the assertions.
 219
 220     This is the same as calling wxSetAssertHandler() with @NULL handler.
 221  */
 222 void wxDisableAsserts();
 223
 224 /**
 225     Will always generate an assert error if this code is reached (in debug mode).
 226     Note that you don't have to (and cannot) use brackets when invoking this
 227     macro:
 228
 229     @code
 230         if (...some condition...) {
 231             wxFAIL;
 232         }
 233     @endcode
 234
 235     This macro should be used to catch (in debug builds) logical errors done
 236     by the programmer.
 237
 238     @see wxFAIL_MSG()
 239
 240     @header{wx/debug.h}
 241 */
 242 #define wxFAIL
 243
 244 /**
 245     Will always generate an assert error with specified message if this code is
 246     reached (in debug mode).
 247
 248     This macro is useful for marking unreachable" code areas, for example it
 249     may be used in the "default:" branch of a switch statement if all possible
 250     cases are processed above.
 251
 252     This macro should be used to catch (in debug builds) logical errors done
 253     by the programmer.
 254
 255     @see wxFAIL()
 256
 257     @header{wx/debug.h}
 258 */
 259 #define wxFAIL_MSG( message )
 260
 261 /**
 262     Returns @true if the program is running under debugger, @false otherwise.
 263
 264     Please note that this function is currently only implemented for Win32 and
 265     Mac builds using CodeWarrior and always returns @false elsewhere.
 266
 267     @header{wx/debug.h}
 268 */
 269 bool wxIsDebuggerRunning();
 270
 271 /**
 272     Sets the function to be called in case of assertion failure.
 273
 274     The default assert handler forwards to wxApp::OnAssertFailure() whose
 275     default behaviour is, in turn, to show the standard assertion failure
 276     dialog if a wxApp object exists or shows the same dialog itself directly
 277     otherwise.
 278
 279     While usually it is enough -- and more convenient -- to just override
 280     OnAssertFailure(), to handle all assertion failures, including those
 281     occurring even before wxApp object creation of after its destruction you
 282     need to provide your assertion handler function.
 283
 284     This function also provides a simple way to disable all asserts: simply
 285     pass @NULL pointer to it. Doing this will result in not even evaluating
 286     assert conditions at all, avoiding almost all run-time cost of asserts.
 287
 288     Notice that this function is not MT-safe, so you should call it before
 289     starting any other threads.
 290
 291     The return value of this function is the previous assertion handler. It can
 292     be called after any pre-processing by your handler and can also be restored
 293     later if you uninstall your handler.
 294
 295     @param handler
 296         The function to call in case of assertion failure or @NULL.
 297     @return
 298         The previous assert handler which is not @NULL by default but could be
 299         @NULL if it had been previously set to this value using this function.
 300
 301     @header{wx/debug.h}
 302  */
 303 wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler);
 304
 305 /**
 306     In debug mode (when @c __WXDEBUG__ is defined) this function generates a
 307     debugger exception meaning that the control is passed to the debugger if
 308     one is attached to the process. Otherwise the program just terminates
 309     abnormally. In release mode this function does nothing.
 310
 311     @header{wx/debug.h}
 312 */
 313 void wxTrap();
 314
 315 //@}
 316