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