interface/wx/debug.h

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