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/log/internal/check_impl.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) ABSL_CHECK_IMPL((condition), #condition)
58 
59 // QCHECK()
60 //
61 // `QCHECK` behaves like `CHECK` but does not print a full stack trace and does
62 // not run registered error handlers (as `QFATAL`).  It is useful when the
63 // problem is definitely unrelated to program flow, e.g. when validating user
64 // input.
65 #define QCHECK(condition) ABSL_QCHECK_IMPL((condition), #condition)
66 
67 // PCHECK()
68 //
69 // `PCHECK` behaves like `CHECK` but appends a description of the current state
70 // of `errno` to the failure message.
71 //
72 // Example:
73 //
74 //   int fd = open("/var/empty/missing", O_RDONLY);
75 //   PCHECK(fd != -1) << "posix is difficult";
76 //
77 // Might produce a message like:
78 //
79 //   Check failed: fd != -1 posix is difficult: No such file or directory [2]
80 #define PCHECK(condition) ABSL_PCHECK_IMPL((condition), #condition)
81 
82 // DCHECK()
83 //
84 // `DCHECK` behaves like `CHECK` in debug mode and does nothing otherwise (as
85 // `DLOG`).  Unlike with `CHECK` (but as with `assert`), it is not safe to rely
86 // on evaluation of `condition`: when `NDEBUG` is enabled, DCHECK does not
87 // evaluate the condition.
88 #define DCHECK(condition) ABSL_DCHECK_IMPL((condition), #condition)
89 
90 // `CHECK_EQ` and friends are syntactic sugar for `CHECK(x == y)` that
91 // automatically output the expression being tested and the evaluated values on
92 // either side.
93 //
94 // Example:
95 //
96 //   int x = 3, y = 5;
97 //   CHECK_EQ(2 * x, y) << "oops!";
98 //
99 // Might produce a message like:
100 //
101 //   Check failed: 2 * x == y (6 vs. 5) oops!
102 //
103 // The values must implement the appropriate comparison operator as well as
104 // `operator<<(std::ostream&, ...)`.  Care is taken to ensure that each
105 // argument is evaluated exactly once, and that anything which is legal to pass
106 // as a function argument is legal here.  In particular, the arguments may be
107 // temporary expressions which will end up being destroyed at the end of the
108 // statement,
109 //
110 // Example:
111 //
112 //   CHECK_EQ(std::string("abc")[1], 'b');
113 //
114 // WARNING: Passing `NULL` as an argument to `CHECK_EQ` and similar macros does
115 // not compile.  Use `nullptr` instead.
116 #define CHECK_EQ(val1, val2) ABSL_CHECK_EQ_IMPL((val1), #val1, (val2), #val2)
117 #define CHECK_NE(val1, val2) ABSL_CHECK_NE_IMPL((val1), #val1, (val2), #val2)
118 #define CHECK_LE(val1, val2) ABSL_CHECK_LE_IMPL((val1), #val1, (val2), #val2)
119 #define CHECK_LT(val1, val2) ABSL_CHECK_LT_IMPL((val1), #val1, (val2), #val2)
120 #define CHECK_GE(val1, val2) ABSL_CHECK_GE_IMPL((val1), #val1, (val2), #val2)
121 #define CHECK_GT(val1, val2) ABSL_CHECK_GT_IMPL((val1), #val1, (val2), #val2)
122 #define QCHECK_EQ(val1, val2) ABSL_QCHECK_EQ_IMPL((val1), #val1, (val2), #val2)
123 #define QCHECK_NE(val1, val2) ABSL_QCHECK_NE_IMPL((val1), #val1, (val2), #val2)
124 #define QCHECK_LE(val1, val2) ABSL_QCHECK_LE_IMPL((val1), #val1, (val2), #val2)
125 #define QCHECK_LT(val1, val2) ABSL_QCHECK_LT_IMPL((val1), #val1, (val2), #val2)
126 #define QCHECK_GE(val1, val2) ABSL_QCHECK_GE_IMPL((val1), #val1, (val2), #val2)
127 #define QCHECK_GT(val1, val2) ABSL_QCHECK_GT_IMPL((val1), #val1, (val2), #val2)
128 #define DCHECK_EQ(val1, val2) ABSL_DCHECK_EQ_IMPL((val1), #val1, (val2), #val2)
129 #define DCHECK_NE(val1, val2) ABSL_DCHECK_NE_IMPL((val1), #val1, (val2), #val2)
130 #define DCHECK_LE(val1, val2) ABSL_DCHECK_LE_IMPL((val1), #val1, (val2), #val2)
131 #define DCHECK_LT(val1, val2) ABSL_DCHECK_LT_IMPL((val1), #val1, (val2), #val2)
132 #define DCHECK_GE(val1, val2) ABSL_DCHECK_GE_IMPL((val1), #val1, (val2), #val2)
133 #define DCHECK_GT(val1, val2) ABSL_DCHECK_GT_IMPL((val1), #val1, (val2), #val2)
134 
135 // `CHECK_OK` and friends validate that the provided `absl::Status` or
136 // `absl::StatusOr<T>` is OK.  If it isn't, they print a failure message that
137 // includes the actual status and terminate the program.
138 //
139 // As with all `DCHECK` variants, `DCHECK_OK` has no effect (not even
140 // evaluating its argument) if `NDEBUG` is enabled.
141 //
142 // Example:
143 //
144 //   CHECK_OK(FunctionReturnsStatus(x, y, z)) << "oops!";
145 //
146 // Might produce a message like:
147 //
148 //   Check failed: FunctionReturnsStatus(x, y, z) is OK (ABORTED: timeout) oops!
149 #define CHECK_OK(status) ABSL_CHECK_OK_IMPL((status), #status)
150 #define QCHECK_OK(status) ABSL_QCHECK_OK_IMPL((status), #status)
151 #define DCHECK_OK(status) ABSL_DCHECK_OK_IMPL((status), #status)
152 
153 // `CHECK_STREQ` and friends provide `CHECK_EQ` functionality for C strings,
154 // i.e., nul-terminated char arrays.  The `CASE` versions are case-insensitive.
155 //
156 // Example:
157 //
158 //   CHECK_STREQ(argv[0], "./skynet");
159 //
160 // Note that both arguments may be temporary strings which are destroyed by the
161 // compiler at the end of the current full expression.
162 //
163 // Example:
164 //
165 //   CHECK_STREQ(Foo().c_str(), Bar().c_str());
166 #define CHECK_STREQ(s1, s2) ABSL_CHECK_STREQ_IMPL((s1), #s1, (s2), #s2)
167 #define CHECK_STRNE(s1, s2) ABSL_CHECK_STRNE_IMPL((s1), #s1, (s2), #s2)
168 #define CHECK_STRCASEEQ(s1, s2) ABSL_CHECK_STRCASEEQ_IMPL((s1), #s1, (s2), #s2)
169 #define CHECK_STRCASENE(s1, s2) ABSL_CHECK_STRCASENE_IMPL((s1), #s1, (s2), #s2)
170 #define QCHECK_STREQ(s1, s2) ABSL_QCHECK_STREQ_IMPL((s1), #s1, (s2), #s2)
171 #define QCHECK_STRNE(s1, s2) ABSL_QCHECK_STRNE_IMPL((s1), #s1, (s2), #s2)
172 #define QCHECK_STRCASEEQ(s1, s2) \
173   ABSL_QCHECK_STRCASEEQ_IMPL((s1), #s1, (s2), #s2)
174 #define QCHECK_STRCASENE(s1, s2) \
175   ABSL_QCHECK_STRCASENE_IMPL((s1), #s1, (s2), #s2)
176 #define DCHECK_STREQ(s1, s2) ABSL_DCHECK_STREQ_IMPL((s1), #s1, (s2), #s2)
177 #define DCHECK_STRNE(s1, s2) ABSL_DCHECK_STRNE_IMPL((s1), #s1, (s2), #s2)
178 #define DCHECK_STRCASEEQ(s1, s2) \
179   ABSL_DCHECK_STRCASEEQ_IMPL((s1), #s1, (s2), #s2)
180 #define DCHECK_STRCASENE(s1, s2) \
181   ABSL_DCHECK_STRCASENE_IMPL((s1), #s1, (s2), #s2)
182 
183 #endif  // ABSL_LOG_CHECK_H_
184