← Back to branch summary

~registry/dolphin-emu/triforce

« back to all changes in this revision

Viewing changes to Externals/wxWidgets3/include/wx/debug.h

  • Committer: Sérgio Benjamim
  • Date: 2015-02-13 05:54:40 UTC
  • Revision ID: sergio_br2@yahoo.com.br-20150213055440-ey2rt3sjpy27km78
Dolphin Triforce branch from code.google, commit b957980 (4.0-315).

Show diffs side-by-side

added added

removed removed

Lines of Context:
Externals/wxWidgets3/include/wx/debug.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        wx/debug.h
 
3
// Purpose:     Misc debug functions and macros
 
4
// Author:      Vadim Zeitlin
 
5
// Created:     29/01/98
 
6
// Copyright:   (c) 1998-2009 Vadim Zeitlin <vadim@wxwidgets.org>
 
7
// Licence:     wxWindows licence
 
8
/////////////////////////////////////////////////////////////////////////////
 
9
 
 
10
#ifndef _WX_DEBUG_H_
 
11
#define _WX_DEBUG_H_
 
12
 
 
13
#if !defined(__WXWINCE__)
 
14
    #include  <assert.h>
 
15
#endif // systems without assert.h
 
16
 
 
17
#include <limits.h>          // for CHAR_BIT used below
 
18
 
 
19
#include "wx/chartype.h"     // for __TFILE__ and wxChar
 
20
#include "wx/cpp.h"          // for __WXFUNCTION__
 
21
#include "wx/dlimpexp.h"     // for WXDLLIMPEXP_FWD_BASE
 
22
 
 
23
class WXDLLIMPEXP_FWD_BASE wxString;
 
24
class WXDLLIMPEXP_FWD_BASE wxCStrData;
 
25
 
 
26
// ----------------------------------------------------------------------------
 
27
// Defines controlling the debugging macros
 
28
// ----------------------------------------------------------------------------
 
29
 
 
30
/*
 
31
    wxWidgets can be built with several different levels of debug support
 
32
    specified by the value of wxDEBUG_LEVEL constant:
 
33
 
 
34
    0:  No assertion macros at all, this should only be used when optimizing
 
35
        for resource-constrained systems (typically embedded ones).
 
36
    1:  Default level, most of the assertions are enabled.
 
37
    2:  Maximal (at least for now): asserts which are "expensive"
 
38
        (performance-wise) or only make sense for finding errors in wxWidgets
 
39
        itself, as opposed to bugs in applications using it, are also enabled.
 
40
 */
 
41
 
 
42
// unless wxDEBUG_LEVEL is predefined (by configure or via wx/setup.h under
 
43
// Windows), use the default
 
44
#if !defined(wxDEBUG_LEVEL)
 
45
    #define wxDEBUG_LEVEL 1
 
46
#endif // !defined(wxDEBUG_LEVEL)
 
47
 
 
48
/*
 
49
    __WXDEBUG__ is defined when wxDEBUG_LEVEL != 0. This is done mostly for
 
50
    compatibility but it also provides a simpler way to check if asserts and
 
51
    debug logging is enabled at all.
 
52
 */
 
53
#if wxDEBUG_LEVEL > 0
 
54
    #ifndef __WXDEBUG__
 
55
        #define __WXDEBUG__
 
56
    #endif
 
57
#else
 
58
    #undef __WXDEBUG__
 
59
#endif
 
60
 
 
61
// Finally there is also a very old WXDEBUG macro not used anywhere at all, it
 
62
// is only defined for compatibility.
 
63
#ifdef __WXDEBUG__
 
64
    #if !defined(WXDEBUG) || !WXDEBUG
 
65
        #undef WXDEBUG
 
66
        #define WXDEBUG 1
 
67
    #endif // !WXDEBUG
 
68
#endif // __WXDEBUG__
 
69
 
 
70
// ----------------------------------------------------------------------------
 
71
// Handling assertion failures
 
72
// ----------------------------------------------------------------------------
 
73
 
 
74
/*
 
75
    Type for the function called in case of assert failure, see
 
76
    wxSetAssertHandler().
 
77
 */
 
78
typedef void (*wxAssertHandler_t)(const wxString& file,
 
79
                                  int line,
 
80
                                  const wxString& func,
 
81
                                  const wxString& cond,
 
82
                                  const wxString& msg);
 
83
 
 
84
#if wxDEBUG_LEVEL
 
85
 
 
86
// the global assert handler function, if it is NULL asserts don't check their
 
87
// conditions
 
88
extern WXDLLIMPEXP_DATA_BASE(wxAssertHandler_t) wxTheAssertHandler;
 
89
 
 
90
/*
 
91
    Sets the function to be called in case of assertion failure.
 
92
 
 
93
    The default assert handler forwards to wxApp::OnAssertFailure() whose
 
94
    default behaviour is, in turn, to show the standard assertion failure
 
95
    dialog if a wxApp object exists or shows the same dialog itself directly
 
96
    otherwise.
 
97
 
 
98
    While usually it is enough -- and more convenient -- to just override
 
99
    OnAssertFailure(), to handle all assertion failures, including those
 
100
    occurring even before wxApp object creation or after its destruction you
 
101
    need to provide your assertion handler function.
 
102
 
 
103
    This function also provides a simple way to disable all asserts: simply
 
104
    pass NULL pointer to it. Doing this will result in not even evaluating
 
105
    assert conditions at all, avoiding almost all run-time cost of asserts.
 
106
 
 
107
    Notice that this function is not MT-safe, so you should call it before
 
108
    starting any other threads.
 
109
 
 
110
    The return value of this function is the previous assertion handler. It can
 
111
    be called after any pre-processing by your handler and can also be restored
 
112
    later if you uninstall your handler.
 
113
 */
 
114
inline wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t handler)
 
115
{
 
116
    const wxAssertHandler_t old = wxTheAssertHandler;
 
117
    wxTheAssertHandler = handler;
 
118
    return old;
 
119
}
 
120
 
 
121
/*
 
122
    Reset the default assert handler.
 
123
 
 
124
    This may be used to enable asserts, which are disabled by default in this
 
125
    case, for programs built in release build (NDEBUG defined).
 
126
 */
 
127
extern void WXDLLIMPEXP_BASE wxSetDefaultAssertHandler();
 
128
 
 
129
#else // !wxDEBUG_LEVEL
 
130
 
 
131
// provide empty stubs in case assertions are completely disabled
 
132
//
 
133
// NB: can't use WXUNUSED() here as we're included from wx/defs.h before it is
 
134
//     defined
 
135
inline wxAssertHandler_t wxSetAssertHandler(wxAssertHandler_t /* handler */)
 
136
{
 
137
    return NULL;
 
138
}
 
139
 
 
140
inline void wxSetDefaultAssertHandler() { }
 
141
 
 
142
#endif // wxDEBUG_LEVEL/!wxDEBUG_LEVEL
 
143
 
 
144
// simply a synonym for wxSetAssertHandler(NULL)
 
145
inline void wxDisableAsserts() { wxSetAssertHandler(NULL); }
 
146
 
 
147
/*
 
148
    A macro which disables asserts for applications compiled in release build.
 
149
 
 
150
    By default, wxIMPLEMENT_APP (or rather wxIMPLEMENT_WXWIN_MAIN) disable the
 
151
    asserts in the applications compiled in the release build by calling this.
 
152
    It does nothing if NDEBUG is not defined.
 
153
 */
 
154
#ifdef NDEBUG
 
155
    #define wxDISABLE_ASSERTS_IN_RELEASE_BUILD() wxDisableAsserts()
 
156
#else
 
157
    #define wxDISABLE_ASSERTS_IN_RELEASE_BUILD()
 
158
#endif
 
159
 
 
160
#if wxDEBUG_LEVEL
 
161
 
 
162
/*
 
163
    wxOnAssert() is used by the debugging macros defined below. Different
 
164
    overloads are needed because these macros can be used with or without wxT().
 
165
 
 
166
    All of them are implemented in src/common/appcmn.cpp and unconditionally
 
167
    call wxTheAssertHandler so the caller must check that it is non-NULL
 
168
    (assert macros do it).
 
169
 */
 
170
 
 
171
#if wxUSE_UNICODE
 
172
 
 
173
// these overloads are the ones typically used by debugging macros: we have to
 
174
// provide wxChar* msg version because it's common to use wxT() in the macros
 
175
// and finally, we can't use const wx(char)* msg = NULL, because that would
 
176
// be ambiguous
 
177
//
 
178
// also notice that these functions can't be inline as wxString is not defined
 
179
// yet (and can't be as wxString code itself may use assertions)
 
180
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
 
181
                                        int line,
 
182
                                        const char *func,
 
183
                                        const char *cond);
 
184
 
 
185
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
 
186
                                        int line,
 
187
                                        const char *func,
 
188
                                        const char *cond,
 
189
                                        const char *msg);
 
190
 
 
191
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
 
192
                                        int line,
 
193
                                        const char *func,
 
194
                                        const char *cond,
 
195
                                        const wxChar *msg) ;
 
196
#endif /* wxUSE_UNICODE */
 
197
 
 
198
// this version is for compatibility with wx 2.8 Unicode build only, we don't
 
199
// use it ourselves any more except in ANSI-only build in which case it is all
 
200
// we need
 
201
extern WXDLLIMPEXP_BASE void wxOnAssert(const wxChar *file,
 
202
                                        int line,
 
203
                                        const char *func,
 
204
                                        const wxChar *cond,
 
205
                                        const wxChar *msg = NULL);
 
206
 
 
207
// these overloads work when msg passed to debug macro is a string and we
 
208
// also have to provide wxCStrData overload to resolve ambiguity which would
 
209
// otherwise arise from wxASSERT( s.c_str() )
 
210
extern WXDLLIMPEXP_BASE void wxOnAssert(const wxString& file,
 
211
                                        int line,
 
212
                                        const wxString& func,
 
213
                                        const wxString& cond,
 
214
                                        const wxString& msg);
 
215
 
 
216
extern WXDLLIMPEXP_BASE void wxOnAssert(const wxString& file,
 
217
                                        int line,
 
218
                                        const wxString& func,
 
219
                                        const wxString& cond);
 
220
 
 
221
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
 
222
                                        int line,
 
223
                                        const char *func,
 
224
                                        const char *cond,
 
225
                                        const wxCStrData& msg);
 
226
 
 
227
extern WXDLLIMPEXP_BASE void wxOnAssert(const char *file,
 
228
                                        int line,
 
229
                                        const char *func,
 
230
                                        const char *cond,
 
231
                                        const wxString& msg);
 
232
 
 
233
#endif // wxDEBUG_LEVEL
 
234
 
 
235
 
 
236
// ----------------------------------------------------------------------------
 
237
// Debugging macros
 
238
// ----------------------------------------------------------------------------
 
239
 
 
240
/*
 
241
    Assertion macros: check if the condition is true and call assert handler
 
242
    (which will by default notify the user about failure) if it isn't.
 
243
 
 
244
    wxASSERT and wxFAIL macros as well as wxTrap() function do nothing at all
 
245
    if wxDEBUG_LEVEL is 0 however they do check their conditions at default
 
246
    debug level 1, unlike the previous wxWidgets versions.
 
247
 
 
248
    wxASSERT_LEVEL_2 is meant to be used for "expensive" asserts which should
 
249
    normally be disabled because they have a big impact on performance and so
 
250
    this macro only does anything if wxDEBUG_LEVEL >= 2.
 
251
 */
 
252
#if wxDEBUG_LEVEL
 
253
    // wxTrap() can be used to break into the debugger unconditionally
 
254
    // (assuming the program is running under debugger, of course).
 
255
    //
 
256
    // If possible, we prefer to define it as a macro rather than as a function
 
257
    // to open the debugger at the position where we trapped and not inside the
 
258
    // trap function itself which is not very useful.
 
259
    #if wxCHECK_VISUALC_VERSION(7)
 
260
        #define wxTrap() __debugbreak()
 
261
    #else
 
262
        extern WXDLLIMPEXP_BASE void wxTrap();
 
263
    #endif // Win VisualC
 
264
 
 
265
    // Global flag used to indicate that assert macros should call wxTrap(): it
 
266
    // is set by the default assert handler if the user answers yes to the
 
267
    // question of whether to trap.
 
268
    extern WXDLLIMPEXP_DATA_BASE(bool) wxTrapInAssert;
 
269
 
 
270
    // This macro checks if the condition is true and calls the assert handler
 
271
    // with the provided message if it isn't and finally traps if the special
 
272
    // flag indicating that it should do it was set by the handler.
 
273
    //
 
274
    // Notice that we don't use the handler return value for compatibility
 
275
    // reasons (if we changed its return type, we'd need to change wxApp::
 
276
    // OnAssertFailure() too which would break user code overriding it), hence
 
277
    // the need for the ugly global flag.
 
278
    #define wxASSERT_MSG(cond, msg)                                           \
 
279
        wxSTATEMENT_MACRO_BEGIN                                               \
 
280
            if ( wxTheAssertHandler && !(cond) &&                             \
 
281
                    (wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__,           \
 
282
                                #cond, msg), wxTrapInAssert) )                \
 
283
            {                                                                 \
 
284
                wxTrapInAssert = false;                                       \
 
285
                wxTrap();                                                     \
 
286
            }                                                                 \
 
287
        wxSTATEMENT_MACRO_END
 
288
 
 
289
    // a version without any additional message, don't use unless condition
 
290
    // itself is fully self-explanatory
 
291
    #define wxASSERT(cond) wxASSERT_MSG(cond, (const char*)NULL)
 
292
 
 
293
    // wxFAIL is a special form of assert: it always triggers (and so is
 
294
    // usually used in normally unreachable code)
 
295
    #define wxFAIL_COND_MSG(cond, msg)                                        \
 
296
        wxSTATEMENT_MACRO_BEGIN                                               \
 
297
            if ( wxTheAssertHandler &&                                        \
 
298
                    (wxOnAssert(__FILE__, __LINE__, __WXFUNCTION__,           \
 
299
                                cond, msg), wxTrapInAssert) )                \
 
300
            {                                                                 \
 
301
                wxTrapInAssert = false;                                       \
 
302
                wxTrap();                                                     \
 
303
            }                                                                 \
 
304
        wxSTATEMENT_MACRO_END
 
305
 
 
306
    #define wxFAIL_MSG(msg) wxFAIL_COND_MSG("Assert failure", msg)
 
307
    #define wxFAIL wxFAIL_MSG((const char*)NULL)
 
308
#else // !wxDEBUG_LEVEL
 
309
    #define wxTrap()
 
310
 
 
311
    #define wxASSERT(cond)
 
312
    #define wxASSERT_MSG(cond, msg)
 
313
    #define wxFAIL
 
314
    #define wxFAIL_MSG(msg)
 
315
    #define wxFAIL_COND_MSG(cond, msg)
 
316
#endif  // wxDEBUG_LEVEL
 
317
 
 
318
#if wxDEBUG_LEVEL >= 2
 
319
    #define wxASSERT_LEVEL_2_MSG(cond, msg) wxASSERT_MSG(cond, msg)
 
320
    #define wxASSERT_LEVEL_2(cond) wxASSERT(cond)
 
321
#else // wxDEBUG_LEVEL < 2
 
322
    #define wxASSERT_LEVEL_2_MSG(cond, msg)
 
323
    #define wxASSERT_LEVEL_2(cond)
 
324
#endif
 
325
 
 
326
// This is simply a wrapper for the standard abort() which is not available
 
327
// under all platforms.
 
328
//
 
329
// It isn't really debug-related but there doesn't seem to be any better place
 
330
// for it, so declare it here and define it in appbase.cpp, together with
 
331
// wxTrap().
 
332
extern void WXDLLIMPEXP_BASE wxAbort();
 
333
 
 
334
/*
 
335
    wxCHECK macros always check their conditions, setting debug level to 0 only
 
336
    makes them silent in case of failure, otherwise -- including at default
 
337
    debug level 1 -- they call the assert handler if the condition is false
 
338
 
 
339
    They are supposed to be used only in invalid situation: for example, an
 
340
    invalid parameter (e.g. a NULL pointer) is passed to a function. Instead of
 
341
    dereferencing it and causing core dump the function might use
 
342
 
 
343
        wxCHECK_RET( p != NULL, "pointer can't be NULL" )
 
344
*/
 
345
 
 
346
// the generic macro: takes the condition to check, the statement to be executed
 
347
// in case the condition is false and the message to pass to the assert handler
 
348
#define wxCHECK2_MSG(cond, op, msg)                                       \
 
349
    if ( cond )                                                           \
 
350
    {}                                                                    \
 
351
    else                                                                  \
 
352
    {                                                                     \
 
353
        wxFAIL_COND_MSG(#cond, msg);                                      \
 
354
        op;                                                               \
 
355
    }                                                                     \
 
356
    struct wxDummyCheckStruct /* just to force a semicolon */
 
357
 
 
358
// check which returns with the specified return code if the condition fails
 
359
#define wxCHECK_MSG(cond, rc, msg)   wxCHECK2_MSG(cond, return rc, msg)
 
360
 
 
361
// check that expression is true, "return" if not (also FAILs in debug mode)
 
362
#define wxCHECK(cond, rc)            wxCHECK_MSG(cond, rc, (const char*)NULL)
 
363
 
 
364
// check that expression is true, perform op if not
 
365
#define wxCHECK2(cond, op)           wxCHECK2_MSG(cond, op, (const char*)NULL)
 
366
 
 
367
// special form of wxCHECK2: as wxCHECK, but for use in void functions
 
368
//
 
369
// NB: there is only one form (with msg parameter) and it's intentional:
 
370
//     there is no other way to tell the caller what exactly went wrong
 
371
//     from the void function (of course, the function shouldn't be void
 
372
//     to begin with...)
 
373
#define wxCHECK_RET(cond, msg)       wxCHECK2_MSG(cond, return, msg)
 
374
 
 
375
 
 
376
// ----------------------------------------------------------------------------
 
377
// Compile time asserts
 
378
//
 
379
// Unlike the normal assert and related macros above which are checked during
 
380
// the program run-time the macros below will result in a compilation error if
 
381
// the condition they check is false. This is usually used to check the
 
382
// expressions containing sizeof()s which cannot be tested with the
 
383
// preprocessor. If you can use the #if's, do use them as you can give a more
 
384
// detailed error message then.
 
385
// ----------------------------------------------------------------------------
 
386
 
 
387
/*
 
388
  How this works (you don't have to understand it to be able to use the
 
389
  macros): we rely on the fact that it is invalid to define a named bit field
 
390
  in a struct of width 0. All the rest are just the hacks to minimize the
 
391
  possibility of the compiler warnings when compiling this macro: in
 
392
  particular, this is why we define a struct and not an object (which would
 
393
  result in a warning about unused variable) and a named struct (otherwise we'd
 
394
  get a warning about an unnamed struct not used to define an object!).
 
395
 */
 
396
 
 
397
#define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_UNIQUE_NAME(wxAssert_)
 
398
 
 
399
/*
 
400
  The second argument of this macro must be a valid C++ identifier and not a
 
401
  string. I.e. you should use it like this:
 
402
 
 
403
    wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 
404
 
 
405
 It may be used both within a function and in the global scope.
 
406
*/
 
407
#if defined(__WATCOMC__)
 
408
    /* avoid "unused symbol" warning */
 
409
    #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 
410
        class wxMAKE_UNIQUE_ASSERT_NAME { \
 
411
          unsigned int msg: expr; \
 
412
          wxMAKE_UNIQUE_ASSERT_NAME() { wxUnusedVar(msg); } \
 
413
        }
 
414
#elif defined( __VMS )
 
415
namespace wxdebug{
 
416
 
 
417
// HP aCC cannot deal with missing names for template value parameters
 
418
template <bool x> struct STATIC_ASSERTION_FAILURE;
 
419
 
 
420
template <> struct STATIC_ASSERTION_FAILURE<true> { enum { value = 1 }; };
 
421
 
 
422
// HP aCC cannot deal with missing names for template value parameters
 
423
template<int x> struct static_assert_test{};
 
424
 
 
425
}
 
426
    #define WX_JOIN( X, Y ) X##Y
 
427
    #define WX_STATIC_ASSERT_BOOL_CAST(x) (bool)(x)
 
428
    #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 
429
       typedef ::wxdebug::static_assert_test<\
 
430
          sizeof(::wxdebug::STATIC_ASSERTION_FAILURE< WX_STATIC_ASSERT_BOOL_CAST( expr ) >)>\
 
431
            WX_JOIN(wx_static_assert_typedef_, __LINE__)
 
432
#else
 
433
    #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 
434
        struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 
435
#endif
 
436
 
 
437
/*
 
438
   When using VC++ 6 with "Edit and Continue" on, the compiler completely
 
439
   mishandles __LINE__ and so wxCOMPILE_TIME_ASSERT() doesn't work, provide a
 
440
   way to make "unique" assert names by specifying a unique prefix explicitly
 
441
 */
 
442
#define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxCONCAT(wxAssert_, text)
 
443
 
 
444
#define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
 
445
    struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
 
446
 
 
447
// helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 
448
#define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 
449
 
 
450
// a special case of compile time assert: check that the size of the given type
 
451
// is at least the given number of bits
 
452
#define wxASSERT_MIN_BITSIZE(type, size) \
 
453
    wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 
454
                          wxMAKE_BITSIZE_MSG(type, size))
 
455
 
 
456
 
 
457
// ----------------------------------------------------------------------------
 
458
// other miscellaneous debugger-related functions
 
459
// ----------------------------------------------------------------------------
 
460
 
 
461
/*
 
462
    Return true if we're running under debugger.
 
463
 
 
464
    Currently only really works under Win32 and just returns false elsewhere.
 
465
 */
 
466
#if defined(__WIN32__)
 
467
    extern bool WXDLLIMPEXP_BASE wxIsDebuggerRunning();
 
468
#else // !Mac
 
469
    inline bool wxIsDebuggerRunning() { return false; }
 
470
#endif // Mac/!Mac
 
471
 
 
472
// An assert helper used to avoid warning when testing constant expressions,
 
473
// i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
 
474
// expression being always true, but not using
 
475
// wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
 
476
//
 
477
// NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and should no
 
478
//     longer be used.
 
479
extern bool WXDLLIMPEXP_BASE wxAssertIsEqual(int x, int y);
 
480
 
 
481
// Use of wxFalse instead of false suppresses compiler warnings about testing
 
482
// constant expression
 
483
extern WXDLLIMPEXP_DATA_BASE(const bool) wxFalse;
 
484
 
 
485
#define wxAssertFailure wxFalse
 
486
 
 
487
// This is similar to WXUNUSED() and useful for parameters which are only used
 
488
// in assertions.
 
489
#if wxDEBUG_LEVEL
 
490
    #define WXUNUSED_UNLESS_DEBUG(param)  param
 
491
#else
 
492
    #define WXUNUSED_UNLESS_DEBUG(param)  WXUNUSED(param)
 
493
#endif
 
494
 
 
495
 
 
496
#endif // _WX_DEBUG_H_