xpcom/glue/nsDebug.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef nsDebug_h___
   7 #define nsDebug_h___
   8
   9 #ifndef nscore_h___
  10 #include "nscore.h"
  11 #endif
  12
  13 #ifndef nsError_h__
  14 #include "nsError.h"
  15 #endif
  16
  17 #include "nsXPCOM.h"
  18 #include "mozilla/Assertions.h"
  19 #include "mozilla/Likely.h"
  20
  21 #ifdef DEBUG
  22 #include "prprf.h"
  23 #endif
  24
  25 #ifdef DEBUG
  26
  27 /**
  28  * Abort the execution of the program if the expression evaluates to
  29  * false.
  30  *
  31  * There is no status value returned from the macro.
  32  *
  33  * Note that the non-debug version of this macro does <b>not</b>
  34  * evaluate the expression argument. Hence side effect statements
  35  * as arguments to the macro will yield improper execution in a
  36  * non-debug build. For example:
  37  *
  38  *      NS_ABORT_IF_FALSE(0 == foo++, "yikes foo should be zero");
  39  *
  40  * Note also that the non-debug version of this macro does <b>not</b>
  41  * evaluate the message argument.
  42  */
  43 #define NS_ABORT_IF_FALSE(_expr, _msg)                        \
  44   do {                                                        \
  45     if (!(_expr)) {                                           \
  46       NS_DebugBreak(NS_DEBUG_ABORT, _msg, #_expr, __FILE__, __LINE__); \
  47     }                                                         \
  48   } while(0)
  49
  50 /**
  51  * Warn if a given condition is false.
  52  *
  53  * Program execution continues past the usage of this macro.
  54  *
  55  * Note also that the non-debug version of this macro does <b>not</b>
  56  * evaluate the message argument.
  57  */
  58 #define NS_WARN_IF_FALSE(_expr,_msg)                          \
  59   do {                                                        \
  60     if (!(_expr)) {                                           \
  61       NS_DebugBreak(NS_DEBUG_WARNING, _msg, #_expr, __FILE__, __LINE__); \
  62     }                                                         \
  63   } while(0)
  64
  65 /**
  66  * Test a precondition for truth. If the expression is not true then
  67  * trigger a program failure.
  68  */
  69 #define NS_PRECONDITION(expr, str)                            \
  70   do {                                                        \
  71     if (!(expr)) {                                            \
  72       NS_DebugBreak(NS_DEBUG_ASSERTION, str, #expr, __FILE__, __LINE__); \
  73     }                                                         \
  74   } while(0)
  75
  76 /**
  77  * Test an assertion for truth. If the expression is not true then
  78  * trigger a program failure.
  79  */
  80 #define NS_ASSERTION(expr, str)                               \
  81   do {                                                        \
  82     if (!(expr)) {                                            \
  83       NS_DebugBreak(NS_DEBUG_ASSERTION, str, #expr, __FILE__, __LINE__); \
  84     }                                                         \
  85   } while(0)
  86
  87 /**
  88  * Test a post-condition for truth. If the expression is not true then
  89  * trigger a program failure.
  90  */
  91 #define NS_POSTCONDITION(expr, str)                           \
  92   do {                                                        \
  93     if (!(expr)) {                                            \
  94       NS_DebugBreak(NS_DEBUG_ASSERTION, str, #expr, __FILE__, __LINE__); \
  95     }                                                         \
  96   } while(0)
  97
  98 /**
  99  * This macros triggers a program failure if executed. It indicates that
 100  * an attempt was made to execute some unimplemented functionality.
 101  */
 102 #define NS_NOTYETIMPLEMENTED(str)                             \
 103   NS_DebugBreak(NS_DEBUG_ASSERTION, str, "NotYetImplemented", __FILE__, __LINE__)
 104
 105 /**
 106  * This macros triggers a program failure if executed. It indicates that
 107  * an attempt was made to execute some unimplemented functionality.
 108  */
 109 #define NS_NOTREACHED(str)                                    \
 110   NS_DebugBreak(NS_DEBUG_ASSERTION, str, "Not Reached", __FILE__, __LINE__)
 111
 112 /**
 113  * Log an error message.
 114  */
 115 #define NS_ERROR(str)                                         \
 116   NS_DebugBreak(NS_DEBUG_ASSERTION, str, "Error", __FILE__, __LINE__)
 117
 118 /**
 119  * Log a warning message.
 120  */
 121 #define NS_WARNING(str)                                       \
 122   NS_DebugBreak(NS_DEBUG_WARNING, str, nullptr, __FILE__, __LINE__)
 123
 124 /**
 125  * Trigger an abort
 126  */
 127 #define NS_ABORT()                                            \
 128   NS_DebugBreak(NS_DEBUG_ABORT, nullptr, nullptr, __FILE__, __LINE__)
 129
 130 /**
 131  * Cause a break
 132  */
 133 #define NS_BREAK()                                            \
 134   NS_DebugBreak(NS_DEBUG_BREAK, nullptr, nullptr, __FILE__, __LINE__)
 135
 136 #else /* DEBUG */
 137
 138 /**
 139  * The non-debug version of these macros do not evaluate the
 140  * expression or the message arguments to the macro.
 141  */
 142 #define NS_ABORT_IF_FALSE(_expr, _msg) do { /* nothing */ } while(0)
 143 #define NS_WARN_IF_FALSE(_expr, _msg)  do { /* nothing */ } while(0)
 144 #define NS_PRECONDITION(expr, str)     do { /* nothing */ } while(0)
 145 #define NS_ASSERTION(expr, str)        do { /* nothing */ } while(0)
 146 #define NS_POSTCONDITION(expr, str)    do { /* nothing */ } while(0)
 147 #define NS_NOTYETIMPLEMENTED(str)      do { /* nothing */ } while(0)
 148 #define NS_NOTREACHED(str)             do { /* nothing */ } while(0)
 149 #define NS_ERROR(str)                  do { /* nothing */ } while(0)
 150 #define NS_WARNING(str)                do { /* nothing */ } while(0)
 151 #define NS_ABORT()                     do { /* nothing */ } while(0)
 152 #define NS_BREAK()                     do { /* nothing */ } while(0)
 153
 154 #endif /* ! DEBUG */
 155
 156 /******************************************************************************
 157 ** Macros for static assertions.  These are used by the sixgill tool.
 158 ** When the tool is not running these macros are no-ops.
 159 ******************************************************************************/
 160
 161 /* Avoid name collision if included with other headers defining annotations. */
 162 #ifndef HAVE_STATIC_ANNOTATIONS
 163 #define HAVE_STATIC_ANNOTATIONS
 164
 165 #ifdef XGILL_PLUGIN
 166
 167 #define STATIC_PRECONDITION(COND)         __attribute__((precondition(#COND)))
 168 #define STATIC_PRECONDITION_ASSUME(COND)  __attribute__((precondition_assume(#COND)))
 169 #define STATIC_POSTCONDITION(COND)        __attribute__((postcondition(#COND)))
 170 #define STATIC_POSTCONDITION_ASSUME(COND) __attribute__((postcondition_assume(#COND)))
 171 #define STATIC_INVARIANT(COND)            __attribute__((invariant(#COND)))
 172 #define STATIC_INVARIANT_ASSUME(COND)     __attribute__((invariant_assume(#COND)))
 173
 174 /* Used to make identifiers for assert/assume annotations in a function. */
 175 #define STATIC_PASTE2(X,Y) X ## Y
 176 #define STATIC_PASTE1(X,Y) STATIC_PASTE2(X,Y)
 177
 178 #define STATIC_ASSERT(COND)                          \
 179   do {                                               \
 180     __attribute__((assert_static(#COND), unused))    \
 181     int STATIC_PASTE1(assert_static_, __COUNTER__);  \
 182   } while(0)
 183
 184 #define STATIC_ASSUME(COND)                          \
 185   do {                                               \
 186     __attribute__((assume_static(#COND), unused))    \
 187     int STATIC_PASTE1(assume_static_, __COUNTER__);  \
 188   } while(0)
 189
 190 #define STATIC_ASSERT_RUNTIME(COND)                         \
 191   do {                                                      \
 192     __attribute__((assert_static_runtime(#COND), unused))   \
 193     int STATIC_PASTE1(assert_static_runtime_, __COUNTER__); \
 194   } while(0)
 195
 196 #else /* XGILL_PLUGIN */
 197
 198 #define STATIC_PRECONDITION(COND)          /* nothing */
 199 #define STATIC_PRECONDITION_ASSUME(COND)   /* nothing */
 200 #define STATIC_POSTCONDITION(COND)         /* nothing */
 201 #define STATIC_POSTCONDITION_ASSUME(COND)  /* nothing */
 202 #define STATIC_INVARIANT(COND)             /* nothing */
 203 #define STATIC_INVARIANT_ASSUME(COND)      /* nothing */
 204
 205 #define STATIC_ASSERT(COND)          do { /* nothing */ } while(0)
 206 #define STATIC_ASSUME(COND)          do { /* nothing */ } while(0)
 207 #define STATIC_ASSERT_RUNTIME(COND)  do { /* nothing */ } while(0)
 208
 209 #endif /* XGILL_PLUGIN */
 210
 211 #define STATIC_SKIP_INFERENCE STATIC_INVARIANT(skip_inference())
 212
 213 #endif /* HAVE_STATIC_ANNOTATIONS */
 214
 215 #ifdef XGILL_PLUGIN
 216
 217 /* Redefine runtime assertion macros to perform static assertions, for both
 218  * debug and release builds. Don't include the original runtime assertions;
 219  * this ensures the tool will consider cases where the assertion fails. */
 220
 221 #undef NS_PRECONDITION
 222 #undef NS_ASSERTION
 223 #undef NS_POSTCONDITION
 224
 225 #define NS_PRECONDITION(expr, str)   STATIC_ASSERT_RUNTIME(expr)
 226 #define NS_ASSERTION(expr, str)      STATIC_ASSERT_RUNTIME(expr)
 227 #define NS_POSTCONDITION(expr, str)  STATIC_ASSERT_RUNTIME(expr)
 228
 229 #endif /* XGILL_PLUGIN */
 230
 231 /******************************************************************************
 232 ** Macros for terminating execution when an unrecoverable condition is
 233 ** reached.  These need to be compiled regardless of the DEBUG flag.
 234 ******************************************************************************/
 235
 236 /**
 237  * Terminate execution <i>immediately</i>, and if possible on the current
 238  * platform, in such a way that execution can't be continued by other
 239  * code (e.g., by intercepting a signal).
 240  */
 241 #define NS_RUNTIMEABORT(msg)                                    \
 242   NS_DebugBreak(NS_DEBUG_ABORT, msg, nullptr, __FILE__, __LINE__)
 243
 244
 245 /* Macros for checking the trueness of an expression passed in within an
 246  * interface implementation.  These need to be compiled regardless of the */
 247 /* DEBUG flag
 248 ******************************************************************************/
 249
 250 #define NS_ENSURE_TRUE(x, ret)                                \
 251   do {                                                        \
 252     if (MOZ_UNLIKELY(!(x))) {                                 \
 253        NS_WARNING("NS_ENSURE_TRUE(" #x ") failed");           \
 254        return ret;                                            \
 255     }                                                         \
 256   } while(0)
 257
 258 #define NS_ENSURE_FALSE(x, ret)                               \
 259   NS_ENSURE_TRUE(!(x), ret)
 260
 261 #define NS_ENSURE_TRUE_VOID(x)                                \
 262   do {                                                        \
 263     if (MOZ_UNLIKELY(!(x))) {                                 \
 264        NS_WARNING("NS_ENSURE_TRUE(" #x ") failed");           \
 265        return;                                                \
 266     }                                                         \
 267   } while(0)
 268
 269 #define NS_ENSURE_FALSE_VOID(x)                               \
 270   NS_ENSURE_TRUE_VOID(!(x))
 271
 272 /******************************************************************************
 273 ** Macros for checking results
 274 ******************************************************************************/
 275
 276 #if defined(DEBUG) && !defined(XPCOM_GLUE_AVOID_NSPR)
 277
 278 #define NS_ENSURE_SUCCESS_BODY(res, ret)                                  \
 279     char *msg = PR_smprintf("NS_ENSURE_SUCCESS(%s, %s) failed with "      \
 280                             "result 0x%X", #res, #ret, __rv);             \
 281     NS_WARNING(msg);                                                      \
 282     PR_smprintf_free(msg);
 283
 284 #define NS_ENSURE_SUCCESS_BODY_VOID(res)                                  \
 285     char *msg = PR_smprintf("NS_ENSURE_SUCCESS_VOID(%s) failed with "     \
 286                             "result 0x%X", #res, __rv);                   \
 287     NS_WARNING(msg);                                                      \
 288     PR_smprintf_free(msg);
 289
 290 #else
 291
 292 #define NS_ENSURE_SUCCESS_BODY(res, ret)                                  \
 293     NS_WARNING("NS_ENSURE_SUCCESS(" #res ", " #ret ") failed");
 294
 295 #define NS_ENSURE_SUCCESS_BODY_VOID(res)                                  \
 296     NS_WARNING("NS_ENSURE_SUCCESS_VOID(" #res ") failed");
 297
 298 #endif
 299
 300 #define NS_ENSURE_SUCCESS(res, ret)                                       \
 301   do {                                                                    \
 302     nsresult __rv = res; /* Don't evaluate |res| more than once */        \
 303     if (NS_FAILED(__rv)) {                                                \
 304       NS_ENSURE_SUCCESS_BODY(res, ret)                                    \
 305       return ret;                                                         \
 306     }                                                                     \
 307   } while(0)
 308
 309 #define NS_ENSURE_SUCCESS_VOID(res)                                       \
 310   do {                                                                    \
 311     nsresult __rv = res;                                                  \
 312     if (NS_FAILED(__rv)) {                                                \
 313       NS_ENSURE_SUCCESS_BODY_VOID(res)                                    \
 314       return;                                                             \
 315     }                                                                     \
 316   } while(0)
 317
 318 /******************************************************************************
 319 ** Macros for checking state and arguments upon entering interface boundaries
 320 ******************************************************************************/
 321
 322 #define NS_ENSURE_ARG(arg)                                    \
 323   NS_ENSURE_TRUE(arg, NS_ERROR_INVALID_ARG)
 324
 325 #define NS_ENSURE_ARG_POINTER(arg)                            \
 326   NS_ENSURE_TRUE(arg, NS_ERROR_INVALID_POINTER)
 327
 328 #define NS_ENSURE_ARG_MIN(arg, min)                           \
 329   NS_ENSURE_TRUE((arg) >= min, NS_ERROR_INVALID_ARG)
 330
 331 #define NS_ENSURE_ARG_MAX(arg, max)                           \
 332   NS_ENSURE_TRUE((arg) <= max, NS_ERROR_INVALID_ARG)
 333
 334 #define NS_ENSURE_ARG_RANGE(arg, min, max)                    \
 335   NS_ENSURE_TRUE(((arg) >= min) && ((arg) <= max), NS_ERROR_INVALID_ARG)
 336
 337 #define NS_ENSURE_STATE(state)                                \
 338   NS_ENSURE_TRUE(state, NS_ERROR_UNEXPECTED)
 339
 340 #define NS_ENSURE_NO_AGGREGATION(outer)                       \
 341   NS_ENSURE_FALSE(outer, NS_ERROR_NO_AGGREGATION)
 342
 343 #define NS_ENSURE_PROPER_AGGREGATION(outer, iid)              \
 344   NS_ENSURE_FALSE(outer && !iid.Equals(NS_GET_IID(nsISupports)), NS_ERROR_INVALID_ARG)
 345
 346 /*****************************************************************************/
 347
 348 #ifdef XPCOM_GLUE
 349   #define NS_CheckThreadSafe(owningThread, msg)
 350 #else
 351   #define NS_CheckThreadSafe(owningThread, msg)                 \
 352     MOZ_ASSERT(owningThread == PR_GetCurrentThread(), msg)
 353 #endif
 354
 355 /* When compiling the XPCOM Glue on Windows, we pretend that it's going to
 356  * be linked with a static CRT (-MT) even when it's not. This means that we
 357  * cannot link to data exports from the CRT, only function exports. So,
 358  * instead of referencing "stderr" directly, use fdopen.
 359  */
 360 #ifdef __cplusplus
 361 extern "C" {
 362 #endif
 363
 364 NS_COM_GLUE void
 365 printf_stderr(const char *fmt, ...);
 366
 367 #ifdef __cplusplus
 368 }
 369 #endif
 370
 371 #endif /* nsDebug_h___ */