1 /*
2 * Copyright 2006 The WebRTC Project Authors. All rights reserved.
3 *
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
9 */
10
11 #ifndef WEBRTC_BASE_CHECKS_H_
12 #define WEBRTC_BASE_CHECKS_H_
13
14 #include <sstream>
15 #include <string>
16
17 #include "webrtc/typedefs.h"
18
19 // The macros here print a message to stderr and abort under various
20 // conditions. All will accept additional stream messages. For example:
21 // RTC_DCHECK_EQ(foo, bar) << "I'm printed when foo != bar.";
22 //
23 // - RTC_CHECK(x) is an assertion that x is always true, and that if it isn't,
24 // it's better to terminate the process than to continue. During development,
25 // the reason that it's better to terminate might simply be that the error
26 // handling code isn't in place yet; in production, the reason might be that
27 // the author of the code truly believes that x will always be true, but that
28 // she recognizes that if she is wrong, abrupt and unpleasant process
29 // termination is still better than carrying on with the assumption violated.
30 //
31 // RTC_CHECK always evaluates its argument, so it's OK for x to have side
32 // effects.
33 //
34 // - RTC_DCHECK(x) is the same as RTC_CHECK(x)---an assertion that x is always
35 // true---except that x will only be evaluated in debug builds; in production
36 // builds, x is simply assumed to be true. This is useful if evaluating x is
37 // expensive and the expected cost of failing to detect the violated
38 // assumption is acceptable. You should not handle cases where a production
39 // build fails to spot a violated condition, even those that would result in
40 // crashes. If the code needs to cope with the error, make it cope, but don't
41 // call RTC_DCHECK; if the condition really can't occur, but you'd sleep
42 // better at night knowing that the process will suicide instead of carrying
43 // on in case you were wrong, use RTC_CHECK instead of RTC_DCHECK.
44 //
45 // RTC_DCHECK only evaluates its argument in debug builds, so if x has visible
46 // side effects, you need to write e.g.
47 // bool w = x; RTC_DCHECK(w);
48 //
49 // - RTC_CHECK_EQ, _NE, _GT, ..., and RTC_DCHECK_EQ, _NE, _GT, ... are
50 // specialized variants of RTC_CHECK and RTC_DCHECK that print prettier
51 // messages if the condition doesn't hold. Prefer them to raw RTC_CHECK and
52 // RTC_DCHECK.
53 //
54 // - FATAL() aborts unconditionally.
55 //
56 // TODO(ajm): Ideally, checks.h would be combined with logging.h, but
57 // consolidation with system_wrappers/logging.h should happen first.
58
59 namespace rtc {
60
61 // Helper macro which avoids evaluating the arguments to a stream if
62 // the condition doesn't hold.
63 #define RTC_LAZY_STREAM(stream, condition) \
64 !(condition) ? static_cast<void>(0) : rtc::FatalMessageVoidify() & (stream)
65
66 // The actual stream used isn't important. We reference condition in the code
67 // but don't evaluate it; this is to avoid "unused variable" warnings (we do so
68 // in a particularly convoluted way with an extra ?: because that appears to be
69 // the simplest construct that keeps Visual Studio from complaining about
70 // condition being unused).
71 #define RTC_EAT_STREAM_PARAMETERS(condition) \
72 (true ? true : !(condition)) \
73 ? static_cast<void>(0) \
74 : rtc::FatalMessageVoidify() & rtc::FatalMessage("", 0).stream()
75
76 // RTC_CHECK dies with a fatal error if condition is not true. It is *not*
77 // controlled by NDEBUG, so the check will be executed regardless of
78 // compilation mode.
79 //
80 // We make sure RTC_CHECK et al. always evaluates their arguments, as
81 // doing RTC_CHECK(FunctionWithSideEffect()) is a common idiom.
82 #define RTC_CHECK(condition) \
83 RTC_LAZY_STREAM(rtc::FatalMessage(__FILE__, __LINE__).stream(), \
84 !(condition)) \
85 << "Check failed: " #condition << std::endl << "# "
86
87 // Helper macro for binary operators.
88 // Don't use this macro directly in your code, use RTC_CHECK_EQ et al below.
89 //
90 // TODO(akalin): Rewrite this so that constructs like if (...)
91 // RTC_CHECK_EQ(...) else { ... } work properly.
92 #define RTC_CHECK_OP(name, op, val1, val2) \
93 if (std::string* _result = \
94 rtc::Check##name##Impl((val1), (val2), #val1 " " #op " " #val2)) \
95 rtc::FatalMessage(__FILE__, __LINE__, _result).stream()
96
97 // Build the error message string. This is separate from the "Impl"
98 // function template because it is not performance critical and so can
99 // be out of line, while the "Impl" code should be inline. Caller
100 // takes ownership of the returned string.
101 template<class t1, class t2>
MakeCheckOpString(const t1 & v1,const t2 & v2,const char * names)102 std::string* MakeCheckOpString(const t1& v1, const t2& v2, const char* names) {
103 std::ostringstream ss;
104 ss << names << " (" << v1 << " vs. " << v2 << ")";
105 std::string* msg = new std::string(ss.str());
106 return msg;
107 }
108
109 // MSVC doesn't like complex extern templates and DLLs.
110 #if !defined(COMPILER_MSVC)
111 // Commonly used instantiations of MakeCheckOpString<>. Explicitly instantiated
112 // in logging.cc.
113 extern template std::string* MakeCheckOpString<int, int>(
114 const int&, const int&, const char* names);
115 extern template
116 std::string* MakeCheckOpString<unsigned long, unsigned long>(
117 const unsigned long&, const unsigned long&, const char* names);
118 extern template
119 std::string* MakeCheckOpString<unsigned long, unsigned int>(
120 const unsigned long&, const unsigned int&, const char* names);
121 extern template
122 std::string* MakeCheckOpString<unsigned int, unsigned long>(
123 const unsigned int&, const unsigned long&, const char* names);
124 extern template
125 std::string* MakeCheckOpString<std::string, std::string>(
126 const std::string&, const std::string&, const char* name);
127 #endif
128
129 // Helper functions for RTC_CHECK_OP macro.
130 // The (int, int) specialization works around the issue that the compiler
131 // will not instantiate the template version of the function on values of
132 // unnamed enum type - see comment below.
133 #define DEFINE_RTC_CHECK_OP_IMPL(name, op) \
134 template <class t1, class t2> \
135 inline std::string* Check##name##Impl(const t1& v1, const t2& v2, \
136 const char* names) { \
137 if (v1 op v2) \
138 return NULL; \
139 else \
140 return rtc::MakeCheckOpString(v1, v2, names); \
141 } \
142 inline std::string* Check##name##Impl(int v1, int v2, const char* names) { \
143 if (v1 op v2) \
144 return NULL; \
145 else \
146 return rtc::MakeCheckOpString(v1, v2, names); \
147 }
148 DEFINE_RTC_CHECK_OP_IMPL(EQ, ==)
149 DEFINE_RTC_CHECK_OP_IMPL(NE, !=)
150 DEFINE_RTC_CHECK_OP_IMPL(LE, <=)
151 DEFINE_RTC_CHECK_OP_IMPL(LT, < )
152 DEFINE_RTC_CHECK_OP_IMPL(GE, >=)
153 DEFINE_RTC_CHECK_OP_IMPL(GT, > )
154 #undef DEFINE_RTC_CHECK_OP_IMPL
155
156 #define RTC_CHECK_EQ(val1, val2) RTC_CHECK_OP(EQ, ==, val1, val2)
157 #define RTC_CHECK_NE(val1, val2) RTC_CHECK_OP(NE, !=, val1, val2)
158 #define RTC_CHECK_LE(val1, val2) RTC_CHECK_OP(LE, <=, val1, val2)
159 #define RTC_CHECK_LT(val1, val2) RTC_CHECK_OP(LT, < , val1, val2)
160 #define RTC_CHECK_GE(val1, val2) RTC_CHECK_OP(GE, >=, val1, val2)
161 #define RTC_CHECK_GT(val1, val2) RTC_CHECK_OP(GT, > , val1, val2)
162
163 // The RTC_DCHECK macro is equivalent to RTC_CHECK except that it only generates
164 // code in debug builds. It does reference the condition parameter in all cases,
165 // though, so callers won't risk getting warnings about unused variables.
166 #if (!defined(NDEBUG) || defined(DCHECK_ALWAYS_ON))
167 #define RTC_DCHECK_IS_ON 1
168 #define RTC_DCHECK(condition) RTC_CHECK(condition)
169 #define RTC_DCHECK_EQ(v1, v2) RTC_CHECK_EQ(v1, v2)
170 #define RTC_DCHECK_NE(v1, v2) RTC_CHECK_NE(v1, v2)
171 #define RTC_DCHECK_LE(v1, v2) RTC_CHECK_LE(v1, v2)
172 #define RTC_DCHECK_LT(v1, v2) RTC_CHECK_LT(v1, v2)
173 #define RTC_DCHECK_GE(v1, v2) RTC_CHECK_GE(v1, v2)
174 #define RTC_DCHECK_GT(v1, v2) RTC_CHECK_GT(v1, v2)
175 #else
176 #define RTC_DCHECK_IS_ON 0
177 #define RTC_DCHECK(condition) RTC_EAT_STREAM_PARAMETERS(condition)
178 #define RTC_DCHECK_EQ(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) == (v2))
179 #define RTC_DCHECK_NE(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) != (v2))
180 #define RTC_DCHECK_LE(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) <= (v2))
181 #define RTC_DCHECK_LT(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) < (v2))
182 #define RTC_DCHECK_GE(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) >= (v2))
183 #define RTC_DCHECK_GT(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) > (v2))
184 #endif
185
186 // This is identical to LogMessageVoidify but in name.
187 class FatalMessageVoidify {
188 public:
FatalMessageVoidify()189 FatalMessageVoidify() { }
190 // This has to be an operator with a precedence lower than << but
191 // higher than ?:
192 void operator&(std::ostream&) { }
193 };
194
195 #define RTC_UNREACHABLE_CODE_HIT false
196 #define RTC_NOTREACHED() RTC_DCHECK(RTC_UNREACHABLE_CODE_HIT)
197
198 #define FATAL() rtc::FatalMessage(__FILE__, __LINE__).stream()
199 // TODO(ajm): Consider adding RTC_NOTIMPLEMENTED macro when
200 // base/logging.h and system_wrappers/logging.h are consolidated such that we
201 // can match the Chromium behavior.
202
203 // Like a stripped-down LogMessage from logging.h, except that it aborts.
204 class FatalMessage {
205 public:
206 FatalMessage(const char* file, int line);
207 // Used for RTC_CHECK_EQ(), etc. Takes ownership of the given string.
208 FatalMessage(const char* file, int line, std::string* result);
209 NO_RETURN ~FatalMessage();
210
stream()211 std::ostream& stream() { return stream_; }
212
213 private:
214 void Init(const char* file, int line);
215
216 std::ostringstream stream_;
217 };
218
219 // Performs the integer division a/b and returns the result. CHECKs that the
220 // remainder is zero.
221 template <typename T>
CheckedDivExact(T a,T b)222 inline T CheckedDivExact(T a, T b) {
223 RTC_CHECK_EQ(a % b, static_cast<T>(0));
224 return a / b;
225 }
226
227 } // namespace rtc
228
229 #endif // WEBRTC_BASE_CHECKS_H_
230