xpcom/glue/nsDebug.h

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