libcruft-util/debug.hpp
Danny Robson 4116442e40 debug: don't rely on format for output
debug is relied upon by a great deal of other units so it's very
difficult to include other popular headers like format.hpp without
triggering cyclic dependencies.
2018-05-10 12:44:03 +10:00

631 lines
24 KiB
C++

/*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Copyright 2010-2017 Danny Robson <danny@nerdcruft.net>
*/
#pragma once
//#include "maths.hpp" // XXX: See notes at the end of file for maths.hpp inclusion
#include <cmath>
#include <algorithm>
#include <stdexcept>
#include <string>
#include <thread>
#include <iosfwd>
#include <sstream>
///////////////////////////////////////////////////////////////////////////////
// it is fractionally easier to define a constexpr variable which can be used
// in constexpr-if to enable/disable some codepaths rather than deal with
// macros in some scenarios. eg, templates are complicated enough without
// (more) macros.
#if !defined(NDEBUG)
constexpr bool debug_enabled = true;
constexpr bool assertions_enabled = true;
#else
constexpr bool debug_enabled = false;
constexpr bool assertions_enabled = false;
#endif
///----------------------------------------------------------------------------
/// enable some code only if assertions are enabled
///
/// explicitly does not use constexpr if to remove the code as some paths may
/// refer to variables which do not always exist, and current compiler
/// implementations are a little picky here.
#ifndef NDEBUG
#include <iostream>
#define DEBUG_ONLY(X) do { X; } while (0)
#else
#define DEBUG_ONLY(X) do { ; } while (0)
#endif
//#define DEBUG_ONLY(X) do { if constexpr (debug_enabled) { X } } while (0)
///////////////////////////////////////////////////////////////////////////////
#define EXIT_XSUCCESS 0
#define EXIT_XSKIP 77
#define EXIT_XHARD_ERROR 99
///////////////////////////////////////////////////////////////////////////////
#define TRACE { \
DEBUG_ONLY ( \
std::cerr << "tid: " << std::this_thread::get_id () \
<< "; " << __FILE__ \
<< ":" << __func__ \
<< ":" << __LINE__ \
<< '\n'; \
); \
}
#define WARN(C) do { \
DEBUG_ONLY ( \
if (C) { \
std::cerr << __FILE__ \
<< ":" << __func__ \
<< ":" << __LINE__ \
<< ", " << #C \
<< '\n'; \
} \
); \
} while (0)
#define WARN_RETURN(CONDITION,VALUE) do { \
if (const auto& __warn_return = (CONDITION); !!__warn_return) { \
if constexpr (debug_enabled) { \
std::cerr << __FILE__ << ':' \
<< __LINE__ << ':' \
<< __PRETTY_FUNCTION__ << "; " \
<< #CONDITION << '\n'; \
breakpoint (); \
} \
\
return (VALUE); \
} \
} while (0)
#define RETURN_UNLESS(VALUE,CONDITION) do { \
if (const auto &__return_unless = (CONDITION); !__return_unless) { \
if constexpr (debug_enabled) { \
std::cerr << __FILE__ << ':' \
<< __LINE__ << ':' \
<< __PRETTY_FUNCTION__ << "; " \
<< #CONDITION << '\n'; \
breakpoint (); \
} \
\
return (VALUE); \
} \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK(C) do { \
DEBUG_ONLY ( \
if (!(C)) \
panic (#C); \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define SCOPED_SANITY(A) \
::util::debug::scoped_sanity PASTE(__scoped_sanity_checker,__LINE__) ((A)); \
(void)PASTE(__scoped_sanity_checker,__LINE__);
///////////////////////////////////////////////////////////////////////////////
#define CHECK_SANITY(A) CHECK(::util::debug::is_valid ((A)))
///////////////////////////////////////////////////////////////////////////////
#define CHECK_EQ(A,B) do { \
DEBUG_ONLY ( \
const auto &__a = (A); \
const auto &__b = (B); \
\
if (!::util::almost_equal (__a, __b)) { \
std::cerr << "expected equality\n" \
"__a: " #A " is " << __a << "\n" \
"__b: " #B " is " << __b << "\n"; \
} \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_LT(A,B) do { \
DEBUG_ONLY ( \
const auto &__a = (A); \
const auto &__b = (B); \
\
if (__a >= __b) { \
std::cerr << "expected less than\n" \
"__a: " << #A << " is " << __a << "\n" \
"__b: " << #B << " is " << __b << "\n"; \
}; \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_LE(A,B) do { \
DEBUG_ONLY ( \
const auto &__a = (A); \
const auto &__b = (B); \
\
if (__a > __b) { \
std::cerr << "expected less than or equal\n" \
"__a: " << #A << " is " << __a << "\n" \
"__b: " << #B << " is " << __b << "\n"; \
} \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_GT(A,B) do { \
DEBUG_ONLY ( \
const auto &__a = (A); \
const auto &__b = (B); \
\
if (__a <= __b) { \
std::cerr << "expected greater than\n" \
"__a: " << #A << " is " << __a << "\n" \
"__b: " << #B << " is " << __b << "\n"; \
} \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_GE(A,B) do { \
DEBUG_ONLY ( \
const auto &__a = (A); \
const auto &__b = (B); \
\
if (__a < __b) { \
std::cerr << "expected greater or equal\n" \
"__a: " << #A << " is " << __a << "\n" \
"__b: " << #B << " is " << __b << "\n"; \
}; \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_LIMIT(V,L,H) do { \
DEBUG_ONLY ( \
const auto &__v = (V); \
const auto &__l = (L); \
const auto &__h = (H); \
\
if (__v < __l || __v > __h) { \
std::cerr << "expected limit\n" \
"__l: " << #L << " is " << +__l << "\n" \
"__h: " << #H << " is " << +__h << "\n" \
"__v: " << #V << " is " << +__v << "\n"; \
}; \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_NEQ(A,B) do { \
DEBUG_ONLY( \
const auto &__a = (A); \
const auto &__b = (B); \
\
if (::util::almost_equal (__a, __b)) { \
std::cerr << "expected inequality\n" \
"__a: " << #A << " is " << __a << "\n" \
"__b: " << #B << " is " << __b << "\n"; \
}; \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_ZERO(A) do { \
DEBUG_ONLY ( \
const auto &__a = (A); \
\
if (!::util::almost_zero (__a)) { \
std::cerr << "expected zero\n" \
"__a: " << #A << " is " << __a << "\n"; \
}; \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_NEZ(A) do { \
DEBUG_ONLY ( \
const auto &__a = (A); \
\
if (::util::exactly_zero (__a)) \
std::cerr << "expected non-zero\n" \
"__a: " << #A << " is " << __a << '\n'; \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_MOD(V,M) do { \
DEBUG_ONLY ( \
const auto &__check_mod_v = (V); \
const auto &__check_mod_m = (M); \
\
if (!::util::exactly_zero (__check_mod_v % __check_mod_m)) \
std::cerr << "expected zero modulus\n" \
"__v: " << #V << " is " << __check_mod_v << "\n" \
"__m: " << #M << " is " << __check_mod_m << "\n"; \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#if defined(ENABLE_DEBUGGING)
#define CHECK_ENUM(C, ...) do { \
const auto &__c = (C); \
const auto &__e = { __VA_ARGS__ }; \
\
if (std::find (std::cbegin (__e), \
std::cend (__e), \
__c) == std::end (__e)) { \
std::cerr << "expect enum\n" \
"__c: " << #C << " is " << __c << '\n'; \
} \
} while (0)
#else
#define CHECK_ENUM(C,...)
#endif
#if !defined(NDEBUG)
#define CHECK_FINITE(V) do { \
const auto &__v = (V); \
if (!std::isfinite (__v)) { \
std::cerr << "expected finite value\n" \
"__v: " << #V << " is " << __v << '\n'; \
} \
} while (0)
#else
#define CHECK_FINITE(V,...)
#endif
///////////////////////////////////////////////////////////////////////////////
#define CHECK_THROWS(E,C) do { \
DEBUG_ONLY ( \
bool caught = false; \
\
try \
{ C; } \
catch (E const&) \
{ caught = true; } \
\
if (!caught) \
std::cerr << "expected exception: " << #E << '\n' \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
#define CHECK_NOTHROW(C) do { \
DEBUG_ONLY ( \
try { \
C; \
} catch (const std::exception &e) { \
std::cerr << "unexpected exception: " << e.what () << '\n'; \
} catch (...) { \
std::cerr << "unexpected exception: unknown\n"; \
} \
); \
} while (0)
///////////////////////////////////////////////////////////////////////////////
/// make the compiler think a particular variable may now be aliased somewhere.
///
/// useful for preventing optimisations eliding a variable.
///
/// stolen from Chandler Carruth's 2015 talk: "Tuning C++".
namespace util::debug {
template <class T>
inline T*
escape (T *t)
{
asm volatile ("": : "g"(t): "memory");
return t;
}
template <class T>
inline const T*
escape (const T *t)
{
asm volatile ("": : "g"(t): "memory");
return t;
}
template <class T>
inline const T&
escape (const T &t)
{
return *escape (&t);
}
template <class T>
inline T&
escape (T &t)
{
return *escape (&t);
}
template <typename T, typename ...Args>
inline void
escape (T t, Args ...args)
{
escape (t);
escape (args...);
}
}
///////////////////////////////////////////////////////////////////////////////
/// force the compiler to conceptually dirty the global memory space.
///
/// stolen from Chandler Carruth's 2015 talk: "Tuning C++".
namespace util::debug {
inline void
clobber (void)
{
asm volatile ("": : : "memory");
}
}
void breakpoint (void);
///////////////////////////////////////////////////////////////////////////////
namespace util::debug::detail {
void
panic [[noreturn]] (const char *msg);
void not_implemented [[noreturn]] (const char *msg);
void unreachable [[noreturn]] (const char *msg);
}
constexpr void
panic [[noreturn]] (const char *msg)
{
! msg
? panic (msg)
: util::debug::detail::panic (msg);
}
inline void
panic [[noreturn]] (const std::string &msg)
{
panic (msg.c_str ());
}
///////////////////////////////////////////////////////////////////////////////
// not_implemented/unreachable/panic must be callable from constexpr contexts.
// but they rely on functions that aren't constexpr to perform the controlled
// abort.
//
// we can work around this in the same way assert does by using a conditional
// that hides an extern function that actually does the work. as we can't
// utilise external state this has to be the message variable which will
// assume isn't ever null.
//
// to avoid warnings about a return from a noreturn function we recurse into
// ourself in the alternate case. this branch shouldn't ever be taken, but if
// it is we were planning on crashing anyway...
///////////////////////////////////////////////////////////////////////////////
constexpr void
not_implemented [[noreturn]] (const char *msg)
{
! msg
? not_implemented (msg)
: util::debug::detail::not_implemented (msg);
}
constexpr void
not_implemented [[noreturn]] (void)
{
not_implemented ("operation not implemented");
}
constexpr void unimplemented [[noreturn]] (void) { not_implemented (); }
constexpr void unimplemented [[noreturn]] (const char *msg) { not_implemented (msg); }
///////////////////////////////////////////////////////////////////////////////
constexpr void
unreachable [[noreturn]] (const char *msg)
{
! msg
? unreachable (msg)
: util::debug::detail::unreachable (msg);
}
constexpr void
unreachable [[noreturn]] (void)
{
unreachable ("unreachable code executed");
}
///////////////////////////////////////////////////////////////////////////////
/// report a fatal error induced by an unhandled value, especially in switch
/// statements. will almost invariably abort the application.
namespace util::debug::detail {
template <typename T>
void
unhandled [[noreturn]] (T &&t) noexcept
{
std::ostringstream os;
os << "unhandled value: " << t << '\n';
::panic (os.str ());
}
}
template <typename T>
constexpr void
unhandled [[noreturn]] (T &&t) noexcept
{
util::debug::detail::unhandled (std::forward<T> (t));
}
///////////////////////////////////////////////////////////////////////////////
void warn (void);
void warn (const std::string&);
void warn (const char *);
///////////////////////////////////////////////////////////////////////////////
void await_debugger (void);
void prepare_debugger (void);
void force_console (void);
///////////////////////////////////////////////////////////////////////////////
void enable_fpe (void);
void disable_fpe (void);
///////////////////////////////////////////////////////////////////////////////
namespace util::debug {
void init (void);
///////////////////////////////////////////////////////////////////////////
// returns true if an instance of type `T' appears to be in a valid state.
//
// written as a struct rather than a function so that behaviour may be
// arbitrarily specialised. all users are free to specialise this struct
// with an user types.
//
// all specialisations must be safe to call on arbitrary data without
// exceptions or faults as this mechanism is used to control some
// debugging paths which themselves are the configuration points for
// throwing/logging/etc behaviour.
template <typename T>
struct validator {
static bool is_valid (const T&) noexcept;
};
//-------------------------------------------------------------------------
template <typename T>
bool is_valid (const T &t) noexcept
{
return validator<T>::is_valid (t);
}
//-------------------------------------------------------------------------
// forwarding validator from a pointer type to a reference type.
//
// null pointers are assumed to be invalid
template <typename T>
struct validator<T*> {
static bool is_valid (const T *val) noexcept
{
return val && ::util::debug::is_valid (*val);
}
};
///////////////////////////////////////////////////////////////////////////
// asserts that an instance of type `T' is in a valid state.
//
// behaviour will be controlled by NDEBUG and other assertion machinery and
// so may be optimised out entirely in optimised builds.
template <typename T>
void sanity (const T &t)
{
(void)t;
CHECK (is_valid (t));
}
//-------------------------------------------------------------------------
template <
template<typename...> class T,
typename ...Args
>
void sanity (const T<Args...> &t)
{
(void)t;
CHECK (is_valid (t));
}
template <typename ValueT>
class scoped_sanity {
public:
scoped_sanity (ValueT &_value):
m_value (_value)
{
sanity (m_value);
}
~scoped_sanity ()
{
sanity (m_value);
}
private:
const ValueT& m_value;
};
};
///////////////////////////////////////////////////////////////////////////////
// XXX: maths needs to be included so that CHECK_EQ/NEQ can call almost_equal,
// but maths.hpp might be using CHECK_ macros so we must include maths.hpp
// after we define the CHECK_ macros so the preprocessor can resolve them.
#include "maths.hpp"