1 // Copyright 2022 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // ----------------------------------------------------------------------------- 16 // File: log/check.h 17 // ----------------------------------------------------------------------------- 18 // 19 // This header declares a family of `CHECK` macros. 20 // 21 // `CHECK` macros terminate the program with a fatal error if the specified 22 // condition is not true. 23 // 24 // Except for those whose names begin with `DCHECK`, these macros are not 25 // controlled by `NDEBUG` (cf. `assert`), so the check will be executed 26 // regardless of compilation mode. `CHECK` and friends are thus useful for 27 // confirming invariants in situations where continuing to run would be worse 28 // than terminating, e.g., due to risk of data corruption or security 29 // compromise. It is also more robust and portable to deliberately terminate 30 // at a particular place with a useful message and backtrace than to assume some 31 // ultimately unspecified and unreliable crashing behavior (such as a 32 // "segmentation fault"). 33 34 #ifndef ABSL_LOG_CHECK_H_ 35 #define ABSL_LOG_CHECK_H_ 36 37 #include "absl/base/optimization.h" 38 #include "absl/log/internal/check_op.h" // IWYU pragma: export 39 #include "absl/log/internal/conditions.h" // IWYU pragma: export 40 #include "absl/log/internal/log_message.h" // IWYU pragma: export 41 #include "absl/log/internal/strip.h" // IWYU pragma: export 42 43 // CHECK() 44 // 45 // `CHECK` terminates the program with a fatal error if `condition` is not true. 46 // 47 // The message may include additional information such as stack traces, when 48 // available. 49 // 50 // Example: 51 // 52 // CHECK(!cheese.empty()) << "Out of Cheese"; 53 // 54 // Might produce a message like: 55 // 56 // Check failed: !cheese.empty() Out of Cheese 57 #define CHECK(condition) \ 58 ABSL_LOG_INTERNAL_CONDITION_FATAL(STATELESS, \ 59 ABSL_PREDICT_FALSE(!(condition))) \ 60 ABSL_LOG_INTERNAL_CHECK(#condition).InternalStream() 61 62 // QCHECK() 63 // 64 // `QCHECK` behaves like `CHECK` but does not print a full stack trace and does 65 // not run registered error handlers (as `QFATAL`). It is useful when the 66 // problem is definitely unrelated to program flow, e.g. when validating user 67 // input. 68 #define QCHECK(condition) \ 69 ABSL_LOG_INTERNAL_CONDITION_QFATAL(STATELESS, \ 70 ABSL_PREDICT_FALSE(!(condition))) \ 71 ABSL_LOG_INTERNAL_QCHECK(#condition).InternalStream() 72 73 // PCHECK() 74 // 75 // `PCHECK` behaves like `CHECK` but appends a description of the current state 76 // of `errno` to the failure message. 77 // 78 // Example: 79 // 80 // int fd = open("/var/empty/missing", O_RDONLY); 81 // PCHECK(fd != -1) << "posix is difficult"; 82 // 83 // Might produce a message like: 84 // 85 // Check failed: fd != -1 posix is difficult: No such file or directory [2] 86 #define PCHECK(condition) CHECK(condition).WithPerror() 87 88 // DCHECK() 89 // 90 // `DCHECK` behaves like `CHECK` in debug mode and does nothing otherwise (as 91 // `DLOG`). Unlike with `CHECK` (but as with `assert`), it is not safe to rely 92 // on evaluation of `condition`: when `NDEBUG` is enabled, DCHECK does not 93 // evaluate the condition. 94 #ifndef NDEBUG 95 #define DCHECK(condition) CHECK(condition) 96 #else 97 #define DCHECK(condition) CHECK(true || (condition)) 98 #endif 99 100 // `CHECK_EQ` and friends are syntactic sugar for `CHECK(x == y)` that 101 // automatically output the expression being tested and the evaluated values on 102 // either side. 103 // 104 // Example: 105 // 106 // int x = 3, y = 5; 107 // CHECK_EQ(2 * x, y) << "oops!"; 108 // 109 // Might produce a message like: 110 // 111 // Check failed: 2 * x == y (6 vs. 5) oops! 112 // 113 // The values must implement the appropriate comparison operator as well as 114 // `operator<<(std::ostream&, ...)`. Care is taken to ensure that each 115 // argument is evaluated exactly once, and that anything which is legal to pass 116 // as a function argument is legal here. In particular, the arguments may be 117 // temporary expressions which will end up being destroyed at the end of the 118 // statement, 119 // 120 // Example: 121 // 122 // CHECK_EQ(std::string("abc")[1], 'b'); 123 // 124 // WARNING: Passing `NULL` as an argument to `CHECK_EQ` and similar macros does 125 // not compile. Use `nullptr` instead. 126 #define CHECK_EQ(val1, val2) \ 127 ABSL_LOG_INTERNAL_CHECK_OP(Check_EQ, ==, val1, val2) 128 #define CHECK_NE(val1, val2) \ 129 ABSL_LOG_INTERNAL_CHECK_OP(Check_NE, !=, val1, val2) 130 #define CHECK_LE(val1, val2) \ 131 ABSL_LOG_INTERNAL_CHECK_OP(Check_LE, <=, val1, val2) 132 #define CHECK_LT(val1, val2) ABSL_LOG_INTERNAL_CHECK_OP(Check_LT, <, val1, val2) 133 #define CHECK_GE(val1, val2) \ 134 ABSL_LOG_INTERNAL_CHECK_OP(Check_GE, >=, val1, val2) 135 #define CHECK_GT(val1, val2) ABSL_LOG_INTERNAL_CHECK_OP(Check_GT, >, val1, val2) 136 #define QCHECK_EQ(val1, val2) \ 137 ABSL_LOG_INTERNAL_QCHECK_OP(Check_EQ, ==, val1, val2) 138 #define QCHECK_NE(val1, val2) \ 139 ABSL_LOG_INTERNAL_QCHECK_OP(Check_NE, !=, val1, val2) 140 #define QCHECK_LE(val1, val2) \ 141 ABSL_LOG_INTERNAL_QCHECK_OP(Check_LE, <=, val1, val2) 142 #define QCHECK_LT(val1, val2) \ 143 ABSL_LOG_INTERNAL_QCHECK_OP(Check_LT, <, val1, val2) 144 #define QCHECK_GE(val1, val2) \ 145 ABSL_LOG_INTERNAL_QCHECK_OP(Check_GE, >=, val1, val2) 146 #define QCHECK_GT(val1, val2) \ 147 ABSL_LOG_INTERNAL_QCHECK_OP(Check_GT, >, val1, val2) 148 #ifndef NDEBUG 149 #define DCHECK_EQ(val1, val2) CHECK_EQ(val1, val2) 150 #define DCHECK_NE(val1, val2) CHECK_NE(val1, val2) 151 #define DCHECK_LE(val1, val2) CHECK_LE(val1, val2) 152 #define DCHECK_LT(val1, val2) CHECK_LT(val1, val2) 153 #define DCHECK_GE(val1, val2) CHECK_GE(val1, val2) 154 #define DCHECK_GT(val1, val2) CHECK_GT(val1, val2) 155 #else // ndef NDEBUG 156 #define DCHECK_EQ(val1, val2) ABSL_LOG_INTERNAL_DCHECK_NOP(val1, val2) 157 #define DCHECK_NE(val1, val2) ABSL_LOG_INTERNAL_DCHECK_NOP(val1, val2) 158 #define DCHECK_LE(val1, val2) ABSL_LOG_INTERNAL_DCHECK_NOP(val1, val2) 159 #define DCHECK_LT(val1, val2) ABSL_LOG_INTERNAL_DCHECK_NOP(val1, val2) 160 #define DCHECK_GE(val1, val2) ABSL_LOG_INTERNAL_DCHECK_NOP(val1, val2) 161 #define DCHECK_GT(val1, val2) ABSL_LOG_INTERNAL_DCHECK_NOP(val1, val2) 162 #endif // def NDEBUG 163 164 // `CHECK_OK` and friends validate that the provided `absl::Status` or 165 // `absl::StatusOr<T>` is OK. If it isn't, they print a failure message that 166 // includes the actual status and terminate the program. 167 // 168 // As with all `DCHECK` variants, `DCHECK_OK` has no effect (not even 169 // evaluating its argument) if `NDEBUG` is enabled. 170 // 171 // Example: 172 // 173 // CHECK_OK(FunctionReturnsStatus(x, y, z)) << "oops!"; 174 // 175 // Might produce a message like: 176 // 177 // Check failed: FunctionReturnsStatus(x, y, z) is OK (ABORTED: timeout) oops! 178 #define CHECK_OK(status) ABSL_LOG_INTERNAL_CHECK_OK(status) 179 #define QCHECK_OK(status) ABSL_LOG_INTERNAL_QCHECK_OK(status) 180 #ifndef NDEBUG 181 #define DCHECK_OK(status) ABSL_LOG_INTERNAL_CHECK_OK(status) 182 #else 183 #define DCHECK_OK(status) ABSL_LOG_INTERNAL_DCHECK_NOP(status, nullptr) 184 #endif 185 186 // `CHECK_STREQ` and friends provide `CHECK_EQ` functionality for C strings, 187 // i.e., nul-terminated char arrays. The `CASE` versions are case-insensitive. 188 // 189 // Example: 190 // 191 // CHECK_STREQ(argv[0], "./skynet"); 192 // 193 // Note that both arguments may be temporary strings which are destroyed by the 194 // compiler at the end of the current full expression. 195 // 196 // Example: 197 // 198 // CHECK_STREQ(Foo().c_str(), Bar().c_str()); 199 #define CHECK_STREQ(s1, s2) \ 200 ABSL_LOG_INTERNAL_CHECK_STROP(strcmp, ==, true, s1, s2) 201 #define CHECK_STRNE(s1, s2) \ 202 ABSL_LOG_INTERNAL_CHECK_STROP(strcmp, !=, false, s1, s2) 203 #define CHECK_STRCASEEQ(s1, s2) \ 204 ABSL_LOG_INTERNAL_CHECK_STROP(strcasecmp, ==, true, s1, s2) 205 #define CHECK_STRCASENE(s1, s2) \ 206 ABSL_LOG_INTERNAL_CHECK_STROP(strcasecmp, !=, false, s1, s2) 207 #define QCHECK_STREQ(s1, s2) \ 208 ABSL_LOG_INTERNAL_QCHECK_STROP(strcmp, ==, true, s1, s2) 209 #define QCHECK_STRNE(s1, s2) \ 210 ABSL_LOG_INTERNAL_QCHECK_STROP(strcmp, !=, false, s1, s2) 211 #define QCHECK_STRCASEEQ(s1, s2) \ 212 ABSL_LOG_INTERNAL_QCHECK_STROP(strcasecmp, ==, true, s1, s2) 213 #define QCHECK_STRCASENE(s1, s2) \ 214 ABSL_LOG_INTERNAL_QCHECK_STROP(strcasecmp, !=, false, s1, s2) 215 #ifndef NDEBUG 216 #define DCHECK_STREQ(s1, s2) CHECK_STREQ(s1, s2) 217 #define DCHECK_STRCASEEQ(s1, s2) CHECK_STRCASEEQ(s1, s2) 218 #define DCHECK_STRNE(s1, s2) CHECK_STRNE(s1, s2) 219 #define DCHECK_STRCASENE(s1, s2) CHECK_STRCASENE(s1, s2) 220 #else // ndef NDEBUG 221 #define DCHECK_STREQ(s1, s2) ABSL_LOG_INTERNAL_DCHECK_NOP(s1, s2) 222 #define DCHECK_STRCASEEQ(s1, s2) ABSL_LOG_INTERNAL_DCHECK_NOP(s1, s2) 223 #define DCHECK_STRNE(s1, s2) ABSL_LOG_INTERNAL_DCHECK_NOP(s1, s2) 224 #define DCHECK_STRCASENE(s1, s2) ABSL_LOG_INTERNAL_DCHECK_NOP(s1, s2) 225 #endif // def NDEBUG 226 227 #endif // ABSL_LOG_CHECK_H_ 228