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