interface/wx/debug.h

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