diff options
Diffstat (limited to 'include/zircon/assert.h')
| -rw-r--r-- | include/zircon/assert.h | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/include/zircon/assert.h b/include/zircon/assert.h new file mode 100644 index 0000000..47f8c4d --- /dev/null +++ b/include/zircon/assert.h @@ -0,0 +1,246 @@ +// Copyright 2016 The Fuchsia Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +#ifndef LIB_ZIRCON_ASSERT_ZIRCON_ASSERT_H_ +#define LIB_ZIRCON_ASSERT_ZIRCON_ASSERT_H_ + +// For a description of which asserts are enabled at which debug levels, see the documentation for +// GN build argument |assert_level|. + +#ifdef _KERNEL +#include <assert.h> +#define ZX_PANIC(args...) PANIC(args) +#define ZX_ASSERT(args...) ASSERT(args) +#define ZX_ASSERT_MSG(args...) ASSERT_MSG(args) +#define ZX_DEBUG_ASSERT(args...) DEBUG_ASSERT(args) +#define ZX_DEBUG_ASSERT_MSG(args...) DEBUG_ASSERT_MSG(args) +#define ZX_DEBUG_ASSERT_COND(args...) DEBUG_ASSERT_COND(args) +#define ZX_DEBUG_ASSERT_MSG_COND(args...) DEBUG_ASSERT_MSG_COND(args) +#define ZX_DEBUG_ASSERT_IMPLEMENTED DEBUG_ASSERT_IMPLEMENTED + +#else // #ifdef _KERNEL + +#include <zircon/compiler.h> + +__BEGIN_CDECLS +// NOLINTNEXTLINE(bugprone-reserved-identifier) +void __zx_panic(const char* format, ...) __NO_RETURN __PRINTFLIKE(1, 2); +__END_CDECLS + +#define ZX_PANIC(fmt, ...) __zx_panic((fmt), ##__VA_ARGS__) + +// Conditionally implement ZX_DEBUG_ASSERT based on ZX_ASSERT_LEVEL. +// +// ZX_DEBUG_ASSERT_IMPLEMENTED is intended to be used to conditionalize code +// that is logically part of a debug assert. It's useful for performing complex +// consistency checks that are difficult to work into a ZX_DEBUG_ASSERT +// statement. +#ifdef ZX_ASSERT_LEVEL +#define ZX_DEBUG_ASSERT_IMPLEMENTED (ZX_ASSERT_LEVEL > 1) +#else +#define ZX_DEBUG_ASSERT_IMPLEMENTED 0 +#endif + +// Notes about the C++ and C versions of the assert macros. +// +// The C++ versions of these macros follow a very specific form for testing the +// assert predicate `x`. Specifically, the test of the predicate is _always_ +// written simply as `if (x)`. Not: +// +// 1) `if (!x)` // or +// 2) `if ((x))` // or +// 3) `if (unlikely(!(x))) // or +// 4) `if (ZX_DEBUG_ASSERT_ENABLED && unlikely(!(x))) // or, anything else. +// +// It is *always* just `if (x)`. There is a method to this madness. The +// primary reason for this is to catch mistakes of the following form: +// +// ZX_DEBUG_ASSERT(my_bool_variable = false); +// ZX_ASSERT(my_int_variable = 5); +// +// Both of these are examples of a pattern where a code author meant to use +// comparison (`==`), but accidentally used assignment (`=`), meaning that the +// first of these examples is always going to fire, while the second will never +// fire. Both of them will have a side effect of mutating their variable, but a +// ZX_DEBUG_ASSERT's mutation will drop out of a release build. +// +// :: Accidental Assignment Protection :: +// +// This is all very bad, and _should_ be caught by the -Wparentheses warning, +// when enabled (which it usually is). Unfortunately, surrounding an assignment +// operation in a set of `()` will suppress the warning. Pretty much any other +// form of the predicate test ends up requiring that we add in an extra pair of +// `()`. This also includes wrapping the predicate in things like `unlikely(x)` +// and `likely(x)`. So, we have to restrict ourselves strictly to testing with +// `if (x)` in order to get the accidental assignment protection we desire. +// +// :: Temporary Variable Latching :: +// +// A surprise advantage to taking this approach is that it allows us (in C++) to +// more easily write predicates which involve latching to a temporary variable. +// Consider a case where we want to debug assert something about a value +// returned by a function which is expensive to call. We could write: +// +// DEBUG_ASSERT_MSG(Expensive() == 5, +// "Expensive() returned a non-five value (%u)", +// Expensive()); +// +// But now we are calling the expensive function twice. We could also say: +// +// [[maybe_unused]] const uint32_t e = Expensive(); +// ZX_DEBUG_ASSERT_MSG(e, "Expensive() returned a non-five value (%u)", e); +// +// but it takes a couple of lines, we have to add in a [[maybe_unused]] +// annotation, and we may still be forced to evaluate Expensive if the compiler +// cannot tell that it is guaranteed to have no side effects. +// +// With the new only-`if (x)` form of testing the predicate, however, we can do +// better. Now, we can write: +// +// ZX_DEBUG_ASSERT_MSG(const uint32_t e = Expensive(); e == 5, +// "Expensive() returned a non-five value (%u)", e); +// +// We still get our protection against accidental assignment, we are guaranteed +// to evaluate Expensive exactly once in a debug build, and zero times in a +// release build. +// +// :: WARNING - C code does not get these benefits :: +// +// To write in this style, but also preserve the likely/unlikely hinting +// benefits, we are forced to use C++'s standardized attributes `[[likely]]` and +// `[[unlikely]]``. These are not available in C, which has to use the old +// compiler attribute macros, which always end up introducing `()`, and +// suppressing the accidental assignment protection. Right now, there is no +// good way around this, and as long as we are building C code using this +// header, we will need to maintain a version of these macros which do not offer +// the same level of protection. +// +#ifdef __cplusplus + +// Only use the [[likely]] attribute if we are sure the compiler is going to +// understand it. +#if defined(__has_cpp_attribute) && (__has_cpp_attribute(likely) >= 201803L) +// NOLINTNEXTLINE(bugprone-reserved-identifier) +#define _ZIRCON_ASSERT_ATTRIBUTE_LIKELY [[likely]] +#else +// NOLINTNEXTLINE(bugprone-reserved-identifier) +#define _ZIRCON_ASSERT_ATTRIBUTE_LIKELY +#endif + +// Assert that |x| is true, else panic. +// +// ZX_ASSERT is always enabled and |x| will be evaluated regardless of any build arguments. +#define ZX_ASSERT(x) \ + do { \ + if (x) \ + _ZIRCON_ASSERT_ATTRIBUTE_LIKELY { break; } \ + else { /* NOLINT(readability-else-after-return) */ \ + ZX_PANIC("ASSERT FAILED at (%s:%d): %s", __FILE__, __LINE__, #x); \ + } \ + } while (0) + +// Assert that |x| is true, else panic with the given message. +// +// ZX_ASSERT_MSG is always enabled and |x| will be evaluated regardless of any build arguments. +#define ZX_ASSERT_MSG(x, msg, msgargs...) \ + do { \ + if (x) \ + _ZIRCON_ASSERT_ATTRIBUTE_LIKELY { break; } \ + else { \ + ZX_PANIC("ASSERT FAILED at (%s:%d): %s" msg, __FILE__, __LINE__, #x, ##msgargs); \ + } \ + } while (0) + +// Assert that |x| is true, else panic. +// +// Depending on build arguments, ZX_DEBUG_ASSERT may or may not be enabled. When disabled, |x| will +// not be evaluated. +#define ZX_DEBUG_ASSERT(x) \ + do { \ + if (ZX_DEBUG_ASSERT_IMPLEMENTED) { \ + if (x) \ + _ZIRCON_ASSERT_ATTRIBUTE_LIKELY { break; } \ + else { \ + ZX_PANIC("DEBUG ASSERT FAILED at (%s:%d): %s", __FILE__, __LINE__, #x); \ + } \ + } \ + } while (0) + +// Assert that |x| is true, else panic with the given message. +// +// Depending on build arguments, ZX_DEBUG_ASSERT_MSG may or may not be enabled. When disabled, |x| +// will not be evaluated. +#define ZX_DEBUG_ASSERT_MSG(x, msg, msgargs...) \ + do { \ + if (ZX_DEBUG_ASSERT_IMPLEMENTED) { \ + if (x) \ + _ZIRCON_ASSERT_ATTRIBUTE_LIKELY { break; } \ + else { \ + ZX_PANIC("DEBUG ASSERT FAILED at (%s:%d): %s" msg, __FILE__, __LINE__, #x, ##msgargs); \ + } \ + } \ + } while (0) + +#else // #ifdef __cplusplus + +// Assert that |x| is true, else panic. +// +// ZX_ASSERT is always enabled and |x| will be evaluated regardless of any build arguments. +#define ZX_ASSERT(x) \ + do { \ + if (unlikely(!(x))) { \ + ZX_PANIC("ASSERT FAILED at (%s:%d): %s", __FILE__, __LINE__, #x); \ + } \ + } while (0) + +// Assert that |x| is true, else panic with the given message. +// +// ZX_ASSERT_MSG is always enabled and |x| will be evaluated regardless of any build arguments. +#define ZX_ASSERT_MSG(x, msg, msgargs...) \ + do { \ + if (unlikely(!(x))) { \ + ZX_PANIC("ASSERT FAILED at (%s:%d): %s" msg, __FILE__, __LINE__, #x, ##msgargs); \ + } \ + } while (0) + +// Assert that |x| is true, else panic. +// +// Depending on build arguments, ZX_DEBUG_ASSERT may or may not be enabled. When disabled, |x| will +// not be evaluated. +#define ZX_DEBUG_ASSERT(x) \ + do { \ + if (ZX_DEBUG_ASSERT_IMPLEMENTED && unlikely(!(x))) { \ + ZX_PANIC("DEBUG ASSERT FAILED at (%s:%d): %s", __FILE__, __LINE__, #x); \ + } \ + } while (0) + +// Assert that |x| is true, else panic with the given message. +// +// Depending on build arguments, ZX_DEBUG_ASSERT_MSG may or may not be enabled. When disabled, |x| +// will not be evaluated. +#define ZX_DEBUG_ASSERT_MSG(x, msg, msgargs...) \ + do { \ + if (ZX_DEBUG_ASSERT_IMPLEMENTED && unlikely(!(x))) { \ + ZX_PANIC("DEBUG ASSERT FAILED at (%s:%d): %s" msg, __FILE__, __LINE__, #x, ##msgargs); \ + } \ + } while (0) + +#endif // #ifdef __cplusplus + // +// implement _COND versions of ZX_DEBUG_ASSERT which only emit the body if +// ZX_DEBUG_ASSERT_IMPLEMENTED is set +#if ZX_DEBUG_ASSERT_IMPLEMENTED +#define ZX_DEBUG_ASSERT_COND(x) ZX_DEBUG_ASSERT(x) +#define ZX_DEBUG_ASSERT_MSG_COND(x, msg, msgargs...) ZX_DEBUG_ASSERT_MSG(x, msg, msgargs) +#else +#define ZX_DEBUG_ASSERT_COND(x) \ + do { \ + } while (0) +#define ZX_DEBUG_ASSERT_MSG_COND(x, msg, msgargs...) \ + do { \ + } while (0) +#endif + +#endif // #ifdef _KERNEL +#endif // LIB_ZIRCON_ASSERT_ZIRCON_ASSERT_H_ |