xpcom/base/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/glue/Debug.h"
  16 #include "mozilla/DbgMacro.h"
  17 #include "mozilla/Likely.h"
  18 #include <stdarg.h>
  19
  20 #ifdef DEBUG
  21 #  include "mozilla/ErrorNames.h"
  22 #  include "mozilla/IntegerPrintfMacros.h"
  23 #  include "mozilla/Printf.h"
  24 #endif
  25
  26 /**
  27  * Warn if the given condition is true. The condition is evaluated in both
  28  * release and debug builds, and the result is an expression which can be
  29  * used in subsequent expressions, such as:
  30  *
  31  * if (NS_WARN_IF(NS_FAILED(rv)) {
  32  *   return rv;
  33  * }
  34  *
  35  * This explicit warning and return is preferred to the NS_ENSURE_* macros
  36  * which hide the warning and the return control flow.
  37  *
  38  * This macro can also be used outside of conditions just to issue a warning,
  39  * like so:
  40  *
  41  *   Unused << NS_WARN_IF(NS_FAILED(FnWithSideEffects());
  42  *
  43  * (The |Unused <<| is necessary because of the [[nodiscard]] annotation.)
  44  *
  45  * However, note that the argument to this macro is evaluated in all builds. If
  46  * you just want a warning assertion, it is better to use NS_WARNING_ASSERTION
  47  * (which evaluates the condition only in debug builds) like so:
  48  *
  49  *   NS_WARNING_ASSERTION(NS_SUCCEEDED(rv), "operation failed");
  50  *
  51  * @note This is C++-only
  52  */
  53 #ifdef __cplusplus
  54 #  ifdef DEBUG
  55 [[nodiscard]] inline bool NS_warn_if_impl(bool aCondition, const char* aExpr,
  56                                           const char* aFile, int32_t aLine) {
  57   if (MOZ_UNLIKELY(aCondition)) {
  58     NS_DebugBreak(NS_DEBUG_WARNING, nullptr, aExpr, aFile, aLine);
  59   }
  60   return aCondition;
  61 }
  62 #    define NS_WARN_IF(condition) \
  63       NS_warn_if_impl(condition, #condition, __FILE__, __LINE__)
  64 #  else
  65 #    define NS_WARN_IF(condition) (bool)(condition)
  66 #  endif
  67 #endif
  68
  69 /**
  70  * Test an assertion for truth. If the expression is not true then
  71  * emit a warning.
  72  *
  73  * Program execution continues past the usage of this macro.
  74  *
  75  * Note also that the non-debug version of this macro does <b>not</b>
  76  * evaluate the message argument.
  77  */
  78 #ifdef DEBUG
  79 #  define NS_WARNING_ASSERTION(_expr, _msg)                                \
  80     do {                                                                   \
  81       if (!(_expr)) {                                                      \
  82         NS_DebugBreak(NS_DEBUG_WARNING, _msg, #_expr, __FILE__, __LINE__); \
  83       }                                                                    \
  84     } while (false)
  85 #else
  86 #  define NS_WARNING_ASSERTION(_expr, _msg) \
  87     do { /* nothing */                      \
  88     } while (false)
  89 #endif
  90
  91 /**
  92  * Test an assertion for truth. If the expression is not true then
  93  * trigger a program failure.
  94  *
  95  * Note that the non-debug version of this macro does <b>not</b>
  96  * evaluate the message argument.
  97  */
  98 #ifdef DEBUG
  99 inline void MOZ_PretendNoReturn() MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS {}
 100 #  define NS_ASSERTION(expr, str)                                          \
 101     do {                                                                   \
 102       if (!(expr)) {                                                       \
 103         NS_DebugBreak(NS_DEBUG_ASSERTION, str, #expr, __FILE__, __LINE__); \
 104         MOZ_PretendNoReturn();                                             \
 105       }                                                                    \
 106     } while (0)
 107 #else
 108 #  define NS_ASSERTION(expr, str) \
 109     do { /* nothing */            \
 110     } while (0)
 111 #endif
 112
 113 /**
 114  * Log an error message.
 115  */
 116 #ifdef DEBUG
 117 #  define NS_ERROR(str)                                                    \
 118     do {                                                                   \
 119       NS_DebugBreak(NS_DEBUG_ASSERTION, str, "Error", __FILE__, __LINE__); \
 120       MOZ_PretendNoReturn();                                               \
 121     } while (0)
 122 #else
 123 #  define NS_ERROR(str) \
 124     do { /* nothing */  \
 125     } while (0)
 126 #endif
 127
 128 /**
 129  * Log a warning message.
 130  */
 131 #ifdef DEBUG
 132 #  define NS_WARNING(str) \
 133     NS_DebugBreak(NS_DEBUG_WARNING, str, nullptr, __FILE__, __LINE__)
 134 #else
 135 #  define NS_WARNING(str) \
 136     do { /* nothing */    \
 137     } while (0)
 138 #endif
 139
 140 /**
 141  * Trigger a debugger breakpoint, only in debug builds.
 142  */
 143 #ifdef DEBUG
 144 #  define NS_BREAK()                                                       \
 145     do {                                                                   \
 146       NS_DebugBreak(NS_DEBUG_BREAK, nullptr, nullptr, __FILE__, __LINE__); \
 147       MOZ_PretendNoReturn();                                               \
 148     } while (0)
 149 #else
 150 #  define NS_BREAK()   \
 151     do { /* nothing */ \
 152     } while (0)
 153 #endif
 154
 155 /******************************************************************************
 156 ** Macros for static assertions.  These are used by the sixgill tool.
 157 ** When the tool is not running these macros are no-ops.
 158 ******************************************************************************/
 159
 160 /* Avoid name collision if included with other headers defining annotations. */
 161 #ifndef HAVE_STATIC_ANNOTATIONS
 162 #  define HAVE_STATIC_ANNOTATIONS
 163
 164 #  ifdef XGILL_PLUGIN
 165
 166 #    define STATIC_PRECONDITION(COND) __attribute__((precondition(#COND)))
 167 #    define STATIC_PRECONDITION_ASSUME(COND) \
 168       __attribute__((precondition_assume(#COND)))
 169 #    define STATIC_POSTCONDITION(COND) __attribute__((postcondition(#COND)))
 170 #    define STATIC_POSTCONDITION_ASSUME(COND) \
 171       __attribute__((postcondition_assume(#COND)))
 172 #    define STATIC_INVARIANT(COND) __attribute__((invariant(#COND)))
 173 #    define STATIC_INVARIANT_ASSUME(COND) \
 174       __attribute__((invariant_assume(#COND)))
 175
 176 /* Used to make identifiers for assert/assume annotations in a function. */
 177 #    define STATIC_PASTE2(X, Y) X##Y
 178 #    define STATIC_PASTE1(X, Y) STATIC_PASTE2(X, Y)
 179
 180 #    define STATIC_ASSUME(COND)                                          \
 181       do {                                                               \
 182         __attribute__((assume_static(#COND), unused)) int STATIC_PASTE1( \
 183             assume_static_, __COUNTER__);                                \
 184       } while (false)
 185
 186 #    define STATIC_ASSERT_RUNTIME(COND)                                   \
 187       do {                                                                \
 188         __attribute__((assert_static_runtime(#COND),                      \
 189                        unused)) int STATIC_PASTE1(assert_static_runtime_, \
 190                                                   __COUNTER__);           \
 191       } while (false)
 192
 193 #  else /* XGILL_PLUGIN */
 194
 195 #    define STATIC_PRECONDITION(COND)         /* nothing */
 196 #    define STATIC_PRECONDITION_ASSUME(COND)  /* nothing */
 197 #    define STATIC_POSTCONDITION(COND)        /* nothing */
 198 #    define STATIC_POSTCONDITION_ASSUME(COND) /* nothing */
 199 #    define STATIC_INVARIANT(COND)            /* nothing */
 200 #    define STATIC_INVARIANT_ASSUME(COND)     /* nothing */
 201
 202 #    define STATIC_ASSUME(COND) \
 203       do { /* nothing */        \
 204       } while (false)
 205 #    define STATIC_ASSERT_RUNTIME(COND) \
 206       do { /* nothing */                \
 207       } while (false)
 208
 209 #  endif /* XGILL_PLUGIN */
 210
 211 #  define STATIC_SKIP_INFERENCE STATIC_INVARIANT(skip_inference())
 212
 213 #endif /* HAVE_STATIC_ANNOTATIONS */
 214
 215 /******************************************************************************
 216 ** Macros for terminating execution when an unrecoverable condition is
 217 ** reached.  These need to be compiled regardless of the DEBUG flag.
 218 ******************************************************************************/
 219
 220 /* Macros for checking the trueness of an expression passed in within an
 221  * interface implementation.  These need to be compiled regardless of the
 222  * DEBUG flag. New code should use NS_WARN_IF(condition) instead!
 223  * @status deprecated
 224  */
 225
 226 #define NS_ENSURE_TRUE(x, ret)                     \
 227   do {                                             \
 228     if (MOZ_UNLIKELY(!(x))) {                      \
 229       NS_WARNING("NS_ENSURE_TRUE(" #x ") failed"); \
 230       return ret;                                  \
 231     }                                              \
 232   } while (false)
 233
 234 #define NS_ENSURE_FALSE(x, ret) NS_ENSURE_TRUE(!(x), ret)
 235
 236 #define NS_ENSURE_TRUE_VOID(x)                     \
 237   do {                                             \
 238     if (MOZ_UNLIKELY(!(x))) {                      \
 239       NS_WARNING("NS_ENSURE_TRUE(" #x ") failed"); \
 240       return;                                      \
 241     }                                              \
 242   } while (false)
 243
 244 #define NS_ENSURE_FALSE_VOID(x) NS_ENSURE_TRUE_VOID(!(x))
 245
 246 /******************************************************************************
 247 ** Macros for checking results
 248 ******************************************************************************/
 249
 250 #if defined(DEBUG) && !defined(XPCOM_GLUE_AVOID_NSPR)
 251
 252 #  define NS_ENSURE_SUCCESS_BODY(res, ret)                         \
 253     const char* name = mozilla::GetStaticErrorName(__rv);          \
 254     mozilla::SmprintfPointer msg = mozilla::Smprintf(              \
 255         "NS_ENSURE_SUCCESS(%s, %s) failed with "                   \
 256         "result 0x%" PRIX32 "%s%s%s",                              \
 257         #res, #ret, static_cast<uint32_t>(__rv), name ? " (" : "", \
 258         name ? name : "", name ? ")" : "");                        \
 259     NS_WARNING(msg.get());
 260
 261 #  define NS_ENSURE_SUCCESS_BODY_VOID(res)                                     \
 262     const char* name = mozilla::GetStaticErrorName(__rv);                      \
 263     mozilla::SmprintfPointer msg = mozilla::Smprintf(                          \
 264         "NS_ENSURE_SUCCESS_VOID(%s) failed with "                              \
 265         "result 0x%" PRIX32 "%s%s%s",                                          \
 266         #res, static_cast<uint32_t>(__rv), name ? " (" : "", name ? name : "", \
 267         name ? ")" : "");                                                      \
 268     NS_WARNING(msg.get());
 269
 270 #else
 271
 272 #  define NS_ENSURE_SUCCESS_BODY(res, ret) \
 273     NS_WARNING("NS_ENSURE_SUCCESS(" #res ", " #ret ") failed");
 274
 275 #  define NS_ENSURE_SUCCESS_BODY_VOID(res) \
 276     NS_WARNING("NS_ENSURE_SUCCESS_VOID(" #res ") failed");
 277
 278 #endif
 279
 280 #define NS_ENSURE_SUCCESS(res, ret)                                \
 281   do {                                                             \
 282     nsresult __rv = res; /* Don't evaluate |res| more than once */ \
 283     if (NS_FAILED(__rv)) {                                         \
 284       NS_ENSURE_SUCCESS_BODY(res, ret)                             \
 285       return ret;                                                  \
 286     }                                                              \
 287   } while (false)
 288
 289 #define NS_ENSURE_SUCCESS_VOID(res)    \
 290   do {                                 \
 291     nsresult __rv = res;               \
 292     if (NS_FAILED(__rv)) {             \
 293       NS_ENSURE_SUCCESS_BODY_VOID(res) \
 294       return;                          \
 295     }                                  \
 296   } while (false)
 297
 298 /******************************************************************************
 299 ** Macros for checking state and arguments upon entering interface boundaries
 300 ******************************************************************************/
 301
 302 #define NS_ENSURE_ARG(arg) NS_ENSURE_TRUE(arg, NS_ERROR_INVALID_ARG)
 303
 304 #define NS_ENSURE_ARG_POINTER(arg) NS_ENSURE_TRUE(arg, NS_ERROR_INVALID_POINTER)
 305
 306 #define NS_ENSURE_ARG_MIN(arg, min) \
 307   NS_ENSURE_TRUE((arg) >= min, NS_ERROR_INVALID_ARG)
 308
 309 #define NS_ENSURE_ARG_MAX(arg, max) \
 310   NS_ENSURE_TRUE((arg) <= max, NS_ERROR_INVALID_ARG)
 311
 312 #define NS_ENSURE_ARG_RANGE(arg, min, max) \
 313   NS_ENSURE_TRUE(((arg) >= min) && ((arg) <= max), NS_ERROR_INVALID_ARG)
 314
 315 #define NS_ENSURE_STATE(state) NS_ENSURE_TRUE(state, NS_ERROR_UNEXPECTED)
 316
 317 /*****************************************************************************/
 318
 319 #if (defined(DEBUG) || (defined(NIGHTLY_BUILD) && !defined(MOZ_PROFILING))) && \
 320     !defined(XPCOM_GLUE_AVOID_NSPR)
 321 #  define MOZ_THREAD_SAFETY_OWNERSHIP_CHECKS_SUPPORTED 1
 322 #endif
 323
 324 #ifdef MOZILLA_INTERNAL_API
 325 void NS_ABORT_OOM(size_t aSize);
 326 #else
 327 inline void NS_ABORT_OOM(size_t) { MOZ_CRASH(); }
 328 #endif
 329
 330 #endif /* nsDebug_h___ */