mfbt/Assertions.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 /* Implementations of runtime and static assertion macros for C and C++. */
   8
   9 #ifndef mozilla_Assertions_h
  10 #define mozilla_Assertions_h
  11
  12 #if defined(MOZ_HAS_MOZGLUE) || defined(MOZILLA_INTERNAL_API)
  13 #  define MOZ_DUMP_ASSERTION_STACK
  14 #endif
  15
  16 #include "mozilla/Attributes.h"
  17 #include "mozilla/Compiler.h"
  18 #include "mozilla/Likely.h"
  19 #include "mozilla/MacroArgs.h"
  20 #include "mozilla/StaticAnalysisFunctions.h"
  21 #include "mozilla/Types.h"
  22 #ifdef MOZ_DUMP_ASSERTION_STACK
  23 #  include "mozilla/StackWalk.h"
  24 #endif
  25
  26 /*
  27  * The crash reason set by MOZ_CRASH_ANNOTATE is consumed by the crash reporter
  28  * if present. It is declared here (and defined in Assertions.cpp) to make it
  29  * available to all code, even libraries that don't link with the crash reporter
  30  * directly.
  31  */
  32 MOZ_BEGIN_EXTERN_C
  33 extern MFBT_DATA const char* gMozCrashReason;
  34 MOZ_END_EXTERN_C
  35
  36 #if defined(MOZ_HAS_MOZGLUE) || defined(MOZILLA_INTERNAL_API)
  37 static inline void AnnotateMozCrashReason(const char* reason) {
  38   gMozCrashReason = reason;
  39 }
  40 #  define MOZ_CRASH_ANNOTATE(...) AnnotateMozCrashReason(__VA_ARGS__)
  41 #else
  42 #  define MOZ_CRASH_ANNOTATE(...) \
  43     do { /* nothing */            \
  44     } while (false)
  45 #endif
  46
  47 #include <stddef.h>
  48 #include <stdio.h>
  49 #include <stdlib.h>
  50 #ifdef _MSC_VER
  51 /*
  52  * TerminateProcess and GetCurrentProcess are defined in <winbase.h>, which
  53  * further depends on <windef.h>.  We hardcode these few definitions manually
  54  * because those headers clutter the global namespace with a significant
  55  * number of undesired macros and symbols.
  56  */
  57 MOZ_BEGIN_EXTERN_C
  58 __declspec(dllimport) int __stdcall TerminateProcess(void* hProcess,
  59                                                      unsigned int uExitCode);
  60 __declspec(dllimport) void* __stdcall GetCurrentProcess(void);
  61 MOZ_END_EXTERN_C
  62 #else
  63 #  include <signal.h>
  64 #endif
  65 #ifdef ANDROID
  66 #  include <android/log.h>
  67 #endif
  68
  69 MOZ_BEGIN_EXTERN_C
  70
  71 #if defined(ANDROID) && defined(MOZ_DUMP_ASSERTION_STACK)
  72 MOZ_MAYBE_UNUSED static void MOZ_ReportAssertionFailurePrintFrame(
  73     const char* aBuf) {
  74   __android_log_print(ANDROID_LOG_FATAL, "MOZ_Assert", "%s\n", aBuf);
  75 }
  76 #endif
  77
  78 /*
  79  * Prints |aStr| as an assertion failure (using aFilename and aLine as the
  80  * location of the assertion) to the standard debug-output channel.
  81  *
  82  * Usually you should use MOZ_ASSERT or MOZ_CRASH instead of this method.  This
  83  * method is primarily for internal use in this header, and only secondarily
  84  * for use in implementing release-build assertions.
  85  */
  86 MOZ_MAYBE_UNUSED static MOZ_COLD MOZ_NEVER_INLINE void
  87 MOZ_ReportAssertionFailure(const char* aStr, const char* aFilename,
  88                            int aLine) MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS {
  89 #ifdef ANDROID
  90   __android_log_print(ANDROID_LOG_FATAL, "MOZ_Assert",
  91                       "Assertion failure: %s, at %s:%d\n", aStr, aFilename,
  92                       aLine);
  93 #  if defined(MOZ_DUMP_ASSERTION_STACK)
  94   MozWalkTheStackWithWriter(MOZ_ReportAssertionFailurePrintFrame,
  95                             /* aSkipFrames */ 1, /* aMaxFrames */ 0);
  96 #  endif
  97 #else
  98   fprintf(stderr, "Assertion failure: %s, at %s:%d\n", aStr, aFilename, aLine);
  99 #  if defined(MOZ_DUMP_ASSERTION_STACK)
 100   MozWalkTheStack(stderr, /* aSkipFrames */ 1, /* aMaxFrames */ 0);
 101 #  endif
 102   fflush(stderr);
 103 #endif
 104 }
 105
 106 MOZ_MAYBE_UNUSED static MOZ_COLD MOZ_NEVER_INLINE void MOZ_ReportCrash(
 107     const char* aStr, const char* aFilename,
 108     int aLine) MOZ_PRETEND_NORETURN_FOR_STATIC_ANALYSIS {
 109 #ifdef ANDROID
 110   __android_log_print(ANDROID_LOG_FATAL, "MOZ_CRASH",
 111                       "Hit MOZ_CRASH(%s) at %s:%d\n", aStr, aFilename, aLine);
 112 #else
 113   fprintf(stderr, "Hit MOZ_CRASH(%s) at %s:%d\n", aStr, aFilename, aLine);
 114 #  if defined(MOZ_DUMP_ASSERTION_STACK)
 115   MozWalkTheStack(stderr, /* aSkipFrames */ 1, /* aMaxFrames */ 0);
 116 #  endif
 117   fflush(stderr);
 118 #endif
 119 }
 120
 121 /**
 122  * MOZ_REALLY_CRASH is used in the implementation of MOZ_CRASH().  You should
 123  * call MOZ_CRASH instead.
 124  */
 125 #if defined(_MSC_VER)
 126 /*
 127  * On MSVC use the __debugbreak compiler intrinsic, which produces an inline
 128  * (not nested in a system function) breakpoint.  This distinctively invokes
 129  * Breakpad without requiring system library symbols on all stack-processing
 130  * machines, as a nested breakpoint would require.
 131  *
 132  * We use __LINE__ to prevent the compiler from folding multiple crash sites
 133  * together, which would make crash reports hard to understand.
 134  *
 135  * We use TerminateProcess with the exit code aborting would generate
 136  * because we don't want to invoke atexit handlers, destructors, library
 137  * unload handlers, and so on when our process might be in a compromised
 138  * state.
 139  *
 140  * We don't use abort() because it'd cause Windows to annoyingly pop up the
 141  * process error dialog multiple times.  See bug 345118 and bug 426163.
 142  *
 143  * (Technically these are Windows requirements, not MSVC requirements.  But
 144  * practically you need MSVC for debugging, and we only ship builds created
 145  * by MSVC, so doing it this way reduces complexity.)
 146  */
 147
 148 MOZ_MAYBE_UNUSED static MOZ_COLD MOZ_NORETURN MOZ_NEVER_INLINE void
 149 MOZ_NoReturn(int aLine) {
 150   *((volatile int*)NULL) = aLine;
 151   TerminateProcess(GetCurrentProcess(), 3);
 152 }
 153
 154 #  define MOZ_REALLY_CRASH(line) \
 155     do {                         \
 156       __debugbreak();            \
 157       MOZ_NoReturn(line);        \
 158     } while (false)
 159 #else
 160
 161 /*
 162  * MOZ_CRASH_WRITE_ADDR is the address to be used when performing a forced
 163  * crash. NULL is preferred however if for some reason NULL cannot be used
 164  * this makes choosing another value possible.
 165  *
 166  * In the case of UBSan certain checks, bounds specifically, cause the compiler
 167  * to emit the 'ud2' instruction when storing to 0x0. This causes forced
 168  * crashes to manifest as ILL (at an arbitrary address) instead of the expected
 169  * SEGV at 0x0.
 170  */
 171 #  ifdef MOZ_UBSAN
 172 #    define MOZ_CRASH_WRITE_ADDR 0x1
 173 #  else
 174 #    define MOZ_CRASH_WRITE_ADDR NULL
 175 #  endif
 176
 177 #  ifdef __cplusplus
 178 #    define MOZ_REALLY_CRASH(line)                                  \
 179       do {                                                          \
 180         *((volatile int*)MOZ_CRASH_WRITE_ADDR) = line; /* NOLINT */ \
 181         ::abort();                                                  \
 182       } while (false)
 183 #  else
 184 #    define MOZ_REALLY_CRASH(line)                                  \
 185       do {                                                          \
 186         *((volatile int*)MOZ_CRASH_WRITE_ADDR) = line; /* NOLINT */ \
 187         abort();                                                    \
 188       } while (false)
 189 #  endif
 190 #endif
 191
 192 /*
 193  * MOZ_CRASH([explanation-string]) crashes the program, plain and simple, in a
 194  * Breakpad-compatible way, in both debug and release builds.
 195  *
 196  * MOZ_CRASH is a good solution for "handling" failure cases when you're
 197  * unwilling or unable to handle them more cleanly -- for OOM, for likely memory
 198  * corruption, and so on.  It's also a good solution if you need safe behavior
 199  * in release builds as well as debug builds.  But if the failure is one that
 200  * should be debugged and fixed, MOZ_ASSERT is generally preferable.
 201  *
 202  * The optional explanation-string, if provided, must be a string literal
 203  * explaining why we're crashing.  This argument is intended for use with
 204  * MOZ_CRASH() calls whose rationale is non-obvious; don't use it if it's
 205  * obvious why we're crashing.
 206  *
 207  * If we're a DEBUG build and we crash at a MOZ_CRASH which provides an
 208  * explanation-string, we print the string to stderr.  Otherwise, we don't
 209  * print anything; this is because we want MOZ_CRASH to be 100% safe in release
 210  * builds, and it's hard to print to stderr safely when memory might have been
 211  * corrupted.
 212  */
 213 #ifndef DEBUG
 214 #  define MOZ_CRASH(...)                                \
 215     do {                                                \
 216       MOZ_CRASH_ANNOTATE("MOZ_CRASH(" __VA_ARGS__ ")"); \
 217       MOZ_REALLY_CRASH(__LINE__);                       \
 218     } while (false)
 219 #else
 220 #  define MOZ_CRASH(...)                                   \
 221     do {                                                   \
 222       MOZ_ReportCrash("" __VA_ARGS__, __FILE__, __LINE__); \
 223       MOZ_CRASH_ANNOTATE("MOZ_CRASH(" __VA_ARGS__ ")");    \
 224       MOZ_REALLY_CRASH(__LINE__);                          \
 225     } while (false)
 226 #endif
 227
 228 /*
 229  * MOZ_CRASH_UNSAFE(explanation-string) can be used if the explanation string
 230  * cannot be a string literal (but no other processing needs to be done on it).
 231  * A regular MOZ_CRASH() is preferred wherever possible, as passing arbitrary
 232  * strings from a potentially compromised process is not without risk. If the
 233  * string being passed is the result of a printf-style function, consider using
 234  * MOZ_CRASH_UNSAFE_PRINTF instead.
 235  *
 236  * @note This macro causes data collection because crash strings are annotated
 237  * to crash-stats and are publicly visible. Firefox data stewards must do data
 238  * review on usages of this macro.
 239  */
 240 static MOZ_ALWAYS_INLINE_EVEN_DEBUG MOZ_COLD MOZ_NORETURN void MOZ_Crash(
 241     const char* aFilename, int aLine, const char* aReason) {
 242 #ifdef DEBUG
 243   MOZ_ReportCrash(aReason, aFilename, aLine);
 244 #endif
 245   MOZ_CRASH_ANNOTATE(aReason);
 246   MOZ_REALLY_CRASH(aLine);
 247 }
 248 #define MOZ_CRASH_UNSAFE(reason) MOZ_Crash(__FILE__, __LINE__, reason)
 249
 250 static const size_t sPrintfMaxArgs = 4;
 251 static const size_t sPrintfCrashReasonSize = 1024;
 252
 253 MFBT_API MOZ_COLD MOZ_NEVER_INLINE MOZ_FORMAT_PRINTF(1, 2) const
 254     char* MOZ_CrashPrintf(const char* aFormat, ...);
 255
 256 /*
 257  * MOZ_CRASH_UNSAFE_PRINTF(format, arg1 [, args]) can be used when more
 258  * information is desired than a string literal can supply. The caller provides
 259  * a printf-style format string, which must be a string literal and between
 260  * 1 and 4 additional arguments. A regular MOZ_CRASH() is preferred wherever
 261  * possible, as passing arbitrary strings to printf from a potentially
 262  * compromised process is not without risk.
 263  *
 264  * @note This macro causes data collection because crash strings are annotated
 265  * to crash-stats and are publicly visible. Firefox data stewards must do data
 266  * review on usages of this macro.
 267  */
 268 #define MOZ_CRASH_UNSAFE_PRINTF(format, ...)                                \
 269   do {                                                                      \
 270     static_assert(MOZ_ARG_COUNT(__VA_ARGS__) > 0,                           \
 271                   "Did you forget arguments to MOZ_CRASH_UNSAFE_PRINTF? "   \
 272                   "Or maybe you want MOZ_CRASH instead?");                  \
 273     static_assert(MOZ_ARG_COUNT(__VA_ARGS__) <= sPrintfMaxArgs,             \
 274                   "Only up to 4 additional arguments are allowed!");        \
 275     static_assert(sizeof(format) <= sPrintfCrashReasonSize,                 \
 276                   "The supplied format string is too long!");               \
 277     MOZ_Crash(__FILE__, __LINE__, MOZ_CrashPrintf("" format, __VA_ARGS__)); \
 278   } while (false)
 279
 280 MOZ_END_EXTERN_C
 281
 282 /*
 283  * MOZ_ASSERT(expr [, explanation-string]) asserts that |expr| must be truthy in
 284  * debug builds.  If it is, execution continues.  Otherwise, an error message
 285  * including the expression and the explanation-string (if provided) is printed,
 286  * an attempt is made to invoke any existing debugger, and execution halts.
 287  * MOZ_ASSERT is fatal: no recovery is possible.  Do not assert a condition
 288  * which can correctly be falsy.
 289  *
 290  * The optional explanation-string, if provided, must be a string literal
 291  * explaining the assertion.  It is intended for use with assertions whose
 292  * correctness or rationale is non-obvious, and for assertions where the "real"
 293  * condition being tested is best described prosaically.  Don't provide an
 294  * explanation if it's not actually helpful.
 295  *
 296  *   // No explanation needed: pointer arguments often must not be NULL.
 297  *   MOZ_ASSERT(arg);
 298  *
 299  *   // An explanation can be helpful to explain exactly how we know an
 300  *   // assertion is valid.
 301  *   MOZ_ASSERT(state == WAITING_FOR_RESPONSE,
 302  *              "given that <thingA> and <thingB>, we must have...");
 303  *
 304  *   // Or it might disambiguate multiple identical (save for their location)
 305  *   // assertions of the same expression.
 306  *   MOZ_ASSERT(getSlot(PRIMITIVE_THIS_SLOT).isUndefined(),
 307  *              "we already set [[PrimitiveThis]] for this Boolean object");
 308  *   MOZ_ASSERT(getSlot(PRIMITIVE_THIS_SLOT).isUndefined(),
 309  *              "we already set [[PrimitiveThis]] for this String object");
 310  *
 311  * MOZ_ASSERT has no effect in non-debug builds.  It is designed to catch bugs
 312  * *only* during debugging, not "in the field". If you want the latter, use
 313  * MOZ_RELEASE_ASSERT, which applies to non-debug builds as well.
 314  *
 315  * MOZ_DIAGNOSTIC_ASSERT works like MOZ_RELEASE_ASSERT in Nightly/Aurora and
 316  * MOZ_ASSERT in Beta/Release - use this when a condition is potentially rare
 317  * enough to require real user testing to hit, but is not security-sensitive.
 318  * This can cause user pain, so use it sparingly. If a MOZ_DIAGNOSTIC_ASSERT
 319  * is firing, it should promptly be converted to a MOZ_ASSERT while the failure
 320  * is being investigated, rather than letting users suffer.
 321  *
 322  * MOZ_DIAGNOSTIC_ASSERT_ENABLED is defined when MOZ_DIAGNOSTIC_ASSERT is like
 323  * MOZ_RELEASE_ASSERT rather than MOZ_ASSERT.
 324  */
 325
 326 /*
 327  * Implement MOZ_VALIDATE_ASSERT_CONDITION_TYPE, which is used to guard against
 328  * accidentally passing something unintended in lieu of an assertion condition.
 329  */
 330
 331 #ifdef __cplusplus
 332 #  include <type_traits>
 333 namespace mozilla {
 334 namespace detail {
 335
 336 template <typename T>
 337 struct AssertionConditionType {
 338   using ValueT = std::remove_reference_t<T>;
 339   static_assert(!std::is_array_v<ValueT>,
 340                 "Expected boolean assertion condition, got an array or a "
 341                 "string!");
 342   static_assert(!std::is_function_v<ValueT>,
 343                 "Expected boolean assertion condition, got a function! Did "
 344                 "you intend to call that function?");
 345   static_assert(!std::is_floating_point_v<ValueT>,
 346                 "It's often a bad idea to assert that a floating-point number "
 347                 "is nonzero, because such assertions tend to intermittently "
 348                 "fail. Shouldn't your code gracefully handle this case instead "
 349                 "of asserting? Anyway, if you really want to do that, write an "
 350                 "explicit boolean condition, like !!x or x!=0.");
 351
 352   static const bool isValid = true;
 353 };
 354
 355 }  // namespace detail
 356 }  // namespace mozilla
 357 #  define MOZ_VALIDATE_ASSERT_CONDITION_TYPE(x)                        \
 358     static_assert(                                                     \
 359         mozilla::detail::AssertionConditionType<decltype(x)>::isValid, \
 360         "invalid assertion condition")
 361 #else
 362 #  define MOZ_VALIDATE_ASSERT_CONDITION_TYPE(x)
 363 #endif
 364
 365 #if defined(DEBUG) || defined(MOZ_ASAN)
 366 #  define MOZ_REPORT_ASSERTION_FAILURE(...) \
 367     MOZ_ReportAssertionFailure(__VA_ARGS__)
 368 #else
 369 #  define MOZ_REPORT_ASSERTION_FAILURE(...) \
 370     do { /* nothing */                      \
 371     } while (false)
 372 #endif
 373
 374 /* First the single-argument form. */
 375 #define MOZ_ASSERT_HELPER1(kind, expr)                         \
 376   do {                                                         \
 377     MOZ_VALIDATE_ASSERT_CONDITION_TYPE(expr);                  \
 378     if (MOZ_UNLIKELY(!MOZ_CHECK_ASSERT_ASSIGNMENT(expr))) {    \
 379       MOZ_REPORT_ASSERTION_FAILURE(#expr, __FILE__, __LINE__); \
 380       MOZ_CRASH_ANNOTATE(kind "(" #expr ")");                  \
 381       MOZ_REALLY_CRASH(__LINE__);                              \
 382     }                                                          \
 383   } while (false)
 384 /* Now the two-argument form. */
 385 #define MOZ_ASSERT_HELPER2(kind, expr, explain)                      \
 386   do {                                                               \
 387     MOZ_VALIDATE_ASSERT_CONDITION_TYPE(expr);                        \
 388     if (MOZ_UNLIKELY(!MOZ_CHECK_ASSERT_ASSIGNMENT(expr))) {          \
 389       MOZ_REPORT_ASSERTION_FAILURE(#expr " (" explain ")", __FILE__, \
 390                                    __LINE__);                        \
 391       MOZ_CRASH_ANNOTATE(kind "(" #expr ") (" explain ")");          \
 392       MOZ_REALLY_CRASH(__LINE__);                                    \
 393     }                                                                \
 394   } while (false)
 395
 396 #define MOZ_ASSERT_GLUE(a, b) a b
 397 #define MOZ_RELEASE_ASSERT(...)                                       \
 398   MOZ_ASSERT_GLUE(                                                    \
 399       MOZ_PASTE_PREFIX_AND_ARG_COUNT(MOZ_ASSERT_HELPER, __VA_ARGS__), \
 400       ("MOZ_RELEASE_ASSERT", __VA_ARGS__))
 401
 402 #ifdef DEBUG
 403 #  define MOZ_ASSERT(...)                                               \
 404     MOZ_ASSERT_GLUE(                                                    \
 405         MOZ_PASTE_PREFIX_AND_ARG_COUNT(MOZ_ASSERT_HELPER, __VA_ARGS__), \
 406         ("MOZ_ASSERT", __VA_ARGS__))
 407 #else
 408 #  define MOZ_ASSERT(...) \
 409     do {                  \
 410     } while (false)
 411 #endif /* DEBUG */
 412
 413 #if defined(NIGHTLY_BUILD) || defined(MOZ_DEV_EDITION) || defined(DEBUG)
 414 #  define MOZ_DIAGNOSTIC_ASSERT(...)                                    \
 415     MOZ_ASSERT_GLUE(                                                    \
 416         MOZ_PASTE_PREFIX_AND_ARG_COUNT(MOZ_ASSERT_HELPER, __VA_ARGS__), \
 417         ("MOZ_DIAGNOSTIC_ASSERT", __VA_ARGS__))
 418 #  define MOZ_DIAGNOSTIC_ASSERT_ENABLED 1
 419 #else
 420 #  define MOZ_DIAGNOSTIC_ASSERT(...) \
 421     do {                             \
 422     } while (false)
 423 #endif
 424
 425 /*
 426  * MOZ_ASSERT_IF(cond1, cond2) is equivalent to MOZ_ASSERT(cond2) if cond1 is
 427  * true.
 428  *
 429  *   MOZ_ASSERT_IF(isPrime(num), num == 2 || isOdd(num));
 430  *
 431  * As with MOZ_ASSERT, MOZ_ASSERT_IF has effect only in debug builds.  It is
 432  * designed to catch bugs during debugging, not "in the field".
 433  */
 434 #ifdef DEBUG
 435 #  define MOZ_ASSERT_IF(cond, expr) \
 436     do {                            \
 437       if (cond) {                   \
 438         MOZ_ASSERT(expr);           \
 439       }                             \
 440     } while (false)
 441 #else
 442 #  define MOZ_ASSERT_IF(cond, expr) \
 443     do {                            \
 444     } while (false)
 445 #endif
 446
 447 /*
 448  * MOZ_DIAGNOSTIC_ASSERT_IF is like MOZ_ASSERT_IF, but using
 449  * MOZ_DIAGNOSTIC_ASSERT as the underlying assert.
 450  *
 451  * See the block comment for MOZ_DIAGNOSTIC_ASSERT above for more details on how
 452  * diagnostic assertions work and how to use them.
 453  */
 454 #ifdef MOZ_DIAGNOSTIC_ASSERT_ENABLED
 455 #  define MOZ_DIAGNOSTIC_ASSERT_IF(cond, expr) \
 456     do {                                       \
 457       if (cond) {                              \
 458         MOZ_DIAGNOSTIC_ASSERT(expr);           \
 459       }                                        \
 460     } while (false)
 461 #else
 462 #  define MOZ_DIAGNOSTIC_ASSERT_IF(cond, expr) \
 463     do {                                       \
 464     } while (false)
 465 #endif
 466
 467 /*
 468  * MOZ_ASSUME_UNREACHABLE_MARKER() expands to an expression which states that
 469  * it is undefined behavior for execution to reach this point.  No guarantees
 470  * are made about what will happen if this is reached at runtime.  Most code
 471  * should use MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE because it has extra
 472  * asserts.
 473  */
 474 #if defined(__clang__) || defined(__GNUC__)
 475 #  define MOZ_ASSUME_UNREACHABLE_MARKER() __builtin_unreachable()
 476 #elif defined(_MSC_VER)
 477 #  define MOZ_ASSUME_UNREACHABLE_MARKER() __assume(0)
 478 #else
 479 #  ifdef __cplusplus
 480 #    define MOZ_ASSUME_UNREACHABLE_MARKER() ::abort()
 481 #  else
 482 #    define MOZ_ASSUME_UNREACHABLE_MARKER() abort()
 483 #  endif
 484 #endif
 485
 486 /*
 487  * MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE([reason]) tells the compiler that it
 488  * can assume that the macro call cannot be reached during execution.  This lets
 489  * the compiler generate better-optimized code under some circumstances, at the
 490  * expense of the program's behavior being undefined if control reaches the
 491  * MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE.
 492  *
 493  * In Gecko, you probably should not use this macro outside of performance- or
 494  * size-critical code, because it's unsafe.  If you don't care about code size
 495  * or performance, you should probably use MOZ_ASSERT or MOZ_CRASH.
 496  *
 497  * SpiderMonkey is a different beast, and there it's acceptable to use
 498  * MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE more widely.
 499  *
 500  * Note that MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE is noreturn, so it's valid
 501  * not to return a value following a MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE
 502  * call.
 503  *
 504  * Example usage:
 505  *
 506  *   enum ValueType {
 507  *     VALUE_STRING,
 508  *     VALUE_INT,
 509  *     VALUE_FLOAT
 510  *   };
 511  *
 512  *   int ptrToInt(ValueType type, void* value) {
 513  *   {
 514  *     // We know for sure that type is either INT or FLOAT, and we want this
 515  *     // code to run as quickly as possible.
 516  *     switch (type) {
 517  *     case VALUE_INT:
 518  *       return *(int*) value;
 519  *     case VALUE_FLOAT:
 520  *       return (int) *(float*) value;
 521  *     default:
 522  *       MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE("Unexpected ValueType");
 523  *     }
 524  *   }
 525  */
 526
 527 /*
 528  * Unconditional assert in debug builds for (assumed) unreachable code paths
 529  * that have a safe return without crashing in release builds.
 530  */
 531 #define MOZ_ASSERT_UNREACHABLE(reason) \
 532   MOZ_ASSERT(false, "MOZ_ASSERT_UNREACHABLE: " reason)
 533
 534 #define MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE(reason) \
 535   do {                                                  \
 536     MOZ_ASSERT_UNREACHABLE(reason);                     \
 537     MOZ_ASSUME_UNREACHABLE_MARKER();                    \
 538   } while (false)
 539
 540 /**
 541  * MOZ_FALLTHROUGH_ASSERT is an annotation to suppress compiler warnings about
 542  * switch cases that MOZ_ASSERT(false) (or its alias MOZ_ASSERT_UNREACHABLE) in
 543  * debug builds, but intentionally fall through in release builds to handle
 544  * unexpected values.
 545  *
 546  * Why do we need MOZ_FALLTHROUGH_ASSERT in addition to [[fallthrough]]? In
 547  * release builds, the MOZ_ASSERT(false) will expand to `do { } while (false)`,
 548  * requiring a [[fallthrough]] annotation to suppress a -Wimplicit-fallthrough
 549  * warning. In debug builds, the MOZ_ASSERT(false) will expand to something like
 550  * `if (true) { MOZ_CRASH(); }` and the [[fallthrough]] annotation will cause
 551  * a -Wunreachable-code warning. The MOZ_FALLTHROUGH_ASSERT macro breaks this
 552  * warning stalemate.
 553  *
 554  * // Example before MOZ_FALLTHROUGH_ASSERT:
 555  * switch (foo) {
 556  *   default:
 557  *     // This case wants to assert in debug builds, fall through in release.
 558  *     MOZ_ASSERT(false); // -Wimplicit-fallthrough warning in release builds!
 559  *     [[fallthrough]];   // but -Wunreachable-code warning in debug builds!
 560  *   case 5:
 561  *     return 5;
 562  * }
 563  *
 564  * // Example with MOZ_FALLTHROUGH_ASSERT:
 565  * switch (foo) {
 566  *   default:
 567  *     // This case asserts in debug builds, falls through in release.
 568  *     MOZ_FALLTHROUGH_ASSERT("Unexpected foo value?!");
 569  *   case 5:
 570  *     return 5;
 571  * }
 572  */
 573 #ifdef DEBUG
 574 #  define MOZ_FALLTHROUGH_ASSERT(...) \
 575     MOZ_CRASH("MOZ_FALLTHROUGH_ASSERT: " __VA_ARGS__)
 576 #else
 577 #  define MOZ_FALLTHROUGH_ASSERT(...) [[fallthrough]]
 578 #endif
 579
 580 /*
 581  * MOZ_ALWAYS_TRUE(expr) and friends always evaluate the provided expression,
 582  * in debug builds and in release builds both.  Then, in debug builds and
 583  * Nightly and DevEdition release builds, the value of the expression is
 584  * asserted either true or false using MOZ_DIAGNOSTIC_ASSERT.
 585  */
 586 #define MOZ_ALWAYS_TRUE(expr)              \
 587   do {                                     \
 588     if (MOZ_LIKELY(expr)) {                \
 589       /* Silence [[nodiscard]]. */         \
 590     } else {                               \
 591       MOZ_DIAGNOSTIC_ASSERT(false, #expr); \
 592     }                                      \
 593   } while (false)
 594
 595 #define MOZ_ALWAYS_FALSE(expr) MOZ_ALWAYS_TRUE(!(expr))
 596 #define MOZ_ALWAYS_OK(expr) MOZ_ALWAYS_TRUE((expr).isOk())
 597 #define MOZ_ALWAYS_ERR(expr) MOZ_ALWAYS_TRUE((expr).isErr())
 598
 599 #undef MOZ_DUMP_ASSERTION_STACK
 600 #undef MOZ_CRASH_CRASHREPORT
 601
 602 #endif /* mozilla_Assertions_h */