|
| 1 | +//===--- Assertions.h - Assertion macros ----===// |
| 2 | +// |
| 3 | +// This source file is part of the Swift.org open source project |
| 4 | +// |
| 5 | +// Copyright (c) 2014 - 2023 Apple Inc. and the Swift project authors |
| 6 | +// Licensed under Apache License v2.0 with Runtime Library Exception |
| 7 | +// |
| 8 | +// See https://swift.org/LICENSE.txt for license information |
| 9 | +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors |
| 10 | +// |
| 11 | +//===----------------------------------------------------------------------===// |
| 12 | +// |
| 13 | +// This file provides three alternatives to the C/C++ standard `assert()` macro |
| 14 | +// |
| 15 | +//===----------------------------------------------------------------------===// |
| 16 | + |
| 17 | +#ifndef SWIFT_BASIC_ASSERTIONS_H |
| 18 | +#define SWIFT_BASIC_ASSERTIONS_H |
| 19 | + |
| 20 | +#include <stdint.h> |
| 21 | + |
| 22 | +// ================================ Mandatory Asserts ================================ |
| 23 | + |
| 24 | +// `ASSERT(expr)`: |
| 25 | +// * is always compiled into the executable and |
| 26 | +// * always checks the condition, regardless of build or runtime settings. |
| 27 | +// This should be used for most assertions, which is why it |
| 28 | +// deserves the short name. In particular, for simple checks |
| 29 | +// (e.g., validating that something is non-null), this is just as |
| 30 | +// fast as a disabled `CONDITIONAL_ASSERT`, so there's no point in |
| 31 | +// using the conditional form. |
| 32 | +// |
| 33 | +// You can globally replace `assert` with `ASSERT` in a piece of code |
| 34 | +// to have all your assertions enabled in all builds. If you do this, |
| 35 | +// please do a little profiling first, just in case you have some checks |
| 36 | +// that are more expensive than you think. You can switch those to |
| 37 | +// `CONDITIONAL_ASSERT` or `DEBUG_ASSERT` as needed. |
| 38 | + |
| 39 | +#define ASSERT(expr) \ |
| 40 | + do { \ |
| 41 | + if (!(expr)) { \ |
| 42 | + ASSERT_failure(#expr, __FILE__, __LINE__, __func__); \ |
| 43 | + } \ |
| 44 | + } while (0) |
| 45 | + |
| 46 | +// Function that reports the actual failure when it occurs. |
| 47 | +[[noreturn]] void ASSERT_failure(const char *expr, const char *file, int line, const char *func); |
| 48 | + |
| 49 | +// ================================ Conditional Asserts ================================ |
| 50 | + |
| 51 | +// `CONDITIONAL_ASSERT(expr)`: |
| 52 | +// * is always compiled into the executable, but |
| 53 | +// * only checks the condition if a runtime flag is defined. |
| 54 | +// That runtime flag is disabled by default in release builds |
| 55 | +// but can be enabled with the command-line flag `-compiler-assertions` |
| 56 | +// |
| 57 | +// Use this for asserts that are comparatively expensive to check. |
| 58 | +// |
| 59 | +// You can globally change `assert` to `CONDITIONAL_ASSERT` to make all your |
| 60 | +// assertions _optionally_ available in release builds. Anyone can then add |
| 61 | +// `-compiler-assertions` to their build flags to get more information about a |
| 62 | +// compiler problem. Before you check it in, do a little checking for |
| 63 | +// assertions that might be checked huge numbers of times (e.g., invariants |
| 64 | +// for inner loops or core utilities); those may need to become `DEBUG_ASSERT` |
| 65 | +// or else refactored to be checked more selectively. |
| 66 | +// |
| 67 | +// Over time, plan to change most of the resulting `CONDITIONAL_ASSERT` into |
| 68 | +// plain `ASSERT` to enable them by default. |
| 69 | + |
| 70 | +#define CONDITIONAL_ASSERT(expr) \ |
| 71 | + do { \ |
| 72 | + if (CONDITIONAL_ASSERT_enabled()) { \ |
| 73 | + ASSERT(expr); \ |
| 74 | + } \ |
| 75 | + } while (0) |
| 76 | + |
| 77 | +// Use `CONDITIONAL_ASSERT_enabled()` to guard complex, expensive code that |
| 78 | +// should only run when assertions are enabled. This is exactly the |
| 79 | +// same check that's used to enable `CONDITIONAL_ASSERT()` at runtime. |
| 80 | +// This is not often used -- if you are just setting a flag or updating |
| 81 | +// a counter, it's likely cheaper just to do it than to test whether or not |
| 82 | +// to do it. Only use this for relatively complex operations. |
| 83 | +// |
| 84 | +// if (CONDITIONAL_ASSERT_enabled()) { |
| 85 | +// ... stuff ... |
| 86 | +// } |
| 87 | + |
| 88 | +// Declare a callable function version of this runtime test. |
| 89 | +int CONDITIONAL_ASSERT_enabled(); |
| 90 | + |
| 91 | +// Define a macro version of this test |
| 92 | +extern int CONDITIONAL_ASSERT_Global_enable_flag; |
| 93 | +#define CONDITIONAL_ASSERT_enabled() \ |
| 94 | + (CONDITIONAL_ASSERT_Global_enable_flag != 0) |
| 95 | + |
| 96 | +// Profiling note: If you uncomment the line below to #undef the macro, then |
| 97 | +// we'll always call the function, which lets you profile assertions by |
| 98 | +// counting calls to this function. |
| 99 | + |
| 100 | +// #undef CONDITIONAL_ASSERT_enabled |
| 101 | + |
| 102 | +// ================================ Debug Asserts ================================ |
| 103 | + |
| 104 | +// `DEBUG_ASSERT(expr)`: |
| 105 | +// * is only compiled into the executable in debug or "asserts enabled" builds, and |
| 106 | +// * always performs the check (whenever it is compiled in). |
| 107 | +// |
| 108 | +// This basically makes it a synonym for the Standard C `assert(expr)`. |
| 109 | +// |
| 110 | +// You should mostly avoid this except for occasional experiments in your |
| 111 | +// local tree. It can be useful in two situations: |
| 112 | +// |
| 113 | +// * Assertions that are known to mis-fire. |
| 114 | +// Such assertions should not be `ASSERT` (since that will cause unnecessary |
| 115 | +// broken compiles) and `CONDITIONAL_ASSERT` gets enabled a lot by people who |
| 116 | +// are not compiler experts. So `DEBUG_ASSERT` is appropriate there until the |
| 117 | +// check can be fixed so it doesn't mis-fire. |
| 118 | +// |
| 119 | +// * Inner loops that can run billions of times. |
| 120 | +// For these, even the cost of testing whether `CONDITIONAL_ASSERT` is enabled |
| 121 | +// can be prohibitive. Use `DEBUG_ASSERT`, but also look for ways to refactor |
| 122 | +// so you can verify correctness without having an assertion in an inner loop. |
| 123 | +// |
| 124 | +// P.S. Please do not bulk replace `assert` with `DEBUG_ASSERT`. The whole |
| 125 | +// point of this package is to move us toward having assertions always compiled |
| 126 | +// in and always enabled. |
| 127 | +#ifdef NDEBUG |
| 128 | + #define DEBUG_ASSERT(expr) do { } while (0) |
| 129 | + #undef DEBUG_ASSERT_enabled |
| 130 | +#else |
| 131 | + #define DEBUG_ASSERT(expr) ASSERT(expr) |
| 132 | + #define DEBUG_ASSERT_enabled 1 |
| 133 | +#endif |
| 134 | + |
| 135 | +// Code that's only needed within `DEBUG_ASSERT` can be guarded as follows: |
| 136 | +// |
| 137 | +// #ifndef NDEBUG |
| 138 | +// ... code that's only needed for DEBUG_ASSERT ... |
| 139 | +// #endif |
| 140 | +// |
| 141 | +// or with the equivalent |
| 142 | +// |
| 143 | +// #ifdef DEBUG_ASSERT_enabled |
| 144 | +// ... code that's only needed for DEBUG_ASSERT ... |
| 145 | +// #endif |
| 146 | +// |
| 147 | +// For example, you may need this for variables or functions that |
| 148 | +// are only used within DEBUG_ASSERT statements. |
| 149 | + |
| 150 | +// A common case is to declare a variable or perform a simple |
| 151 | +// expression. These can be used to avoid some boilerplate: |
| 152 | +// |
| 153 | +// void doThings() { |
| 154 | +// DEBUG_ASSERT_DECL(std::vector<Things> thingsToVerify;); |
| 155 | +// while (!done) { |
| 156 | +// // ... do each thing ... |
| 157 | +// DEBUG_ASSERT_EXPR(thingsToVerify.append(item)); |
| 158 | +// } |
| 159 | +// DEBUG_ASSERT(verifyAllThe(thingsToVerify)); |
| 160 | +// } |
| 161 | + |
| 162 | +#ifdef DEBUG_ASSERT_enabled |
| 163 | + #define DEBUG_ASSERT_DECL(...) __VA_ARGS__ |
| 164 | + #define DEBUG_ASSERT_EXPR(...) do { __VA_ARGS__; } while (false) |
| 165 | +#else |
| 166 | + #define DEBUG_ASSERT_DECL(...) |
| 167 | + #define DEBUG_ASSERT_EXPR(...) do { } while (false) |
| 168 | +#endif |
| 169 | + |
| 170 | +// Older version of the same idea: |
| 171 | +#define SWIFT_ASSERT_ONLY_DECL DEBUG_ASSERT_DECL |
| 172 | +#define SWIFT_ASSERT_ONLY DEBUG_ASSERT_EXPR |
| 173 | + |
| 174 | +#endif // SWIFT_BASIC_ASSERTIONS_H |
0 commit comments