libcruft-util/debug.hpp

/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * 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) \
::cruft::debug::scoped_sanity PASTE(__scoped_sanity_checker,__LINE__) ((A)); \
(void)PASTE(__scoped_sanity_checker,__LINE__);


///////////////////////////////////////////////////////////////////////////////
#define CHECK_SANITY(A,...) CHECK(::cruft::debug::is_valid ((A) __VA_OPT__(,) __VA_ARGS__))


///////////////////////////////////////////////////////////////////////////////
#define CHECK_EQ(A,B) do {                                  \
    DEBUG_ONLY (                                            \
        const auto &__a = (A);                              \
        const auto &__b = (B);                              \
                                                            \
        if (!::cruft::almost_equal (__a, __b)) {             \
            std::cerr << "expected equality\n"              \
                         "__a: " #A " is " << __a << "\n"   \
                         "__b: " #B " is " << __b << "\n";  \
            breakpoint ();                                  \
        }                                                   \
    );                                                      \
} 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";   \
            breakpoint ();                                          \
        };                                                          \
    );                                                              \
} 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";    \
            breakpoint ();                                          \
        }                                                           \
    );                                                              \
} 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";   \
            breakpoint ();                                          \
        }                                                           \
    );                                                              \
} 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";   \
            breakpoint ();                                          \
        };                                                          \
    );                                                              \
} 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";  \
            breakpoint ();                                          \
        };                                                          \
    );                                                              \
} while (0)

///////////////////////////////////////////////////////////////////////////////
#define CHECK_NEQ(A,B) do {                                         \
    DEBUG_ONLY(                                                     \
        const auto &__a = (A);                                      \
        const auto &__b = (B);                                      \
                                                                    \
        if (::cruft::almost_equal (__a, __b)) {                      \
            std::cerr << "expected inequality\n"                    \
                          "__a: " << #A << " is " << __a << "\n"    \
                          "__b: " << #B << " is " << __b << "\n";   \
            breakpoint ();                                          \
        };                                                          \
    );                                                              \
} while (0)


///////////////////////////////////////////////////////////////////////////////
#define CHECK_ZERO(A) do {                                          \
    DEBUG_ONLY (                                                    \
        const auto &__a = (A);                                      \
                                                                    \
        if (!::cruft::almost_zero (__a)) {                           \
            std::cerr << "expected zero\n"                          \
                          "__a: " << #A << " is " << __a << "\n";   \
            breakpoint ();                                          \
        };                                                          \
    );                                                              \
} while (0)


///////////////////////////////////////////////////////////////////////////////
#define CHECK_NEZ(A) do {                                           \
    DEBUG_ONLY (                                                    \
        const auto &__a = (A);                                      \
                                                                    \
        if (::cruft::exactly_zero (__a))  {                          \
            std::cerr << "expected non-zero\n"                      \
                          "__a: " << #A << " is " << __a << '\n';   \
            breakpoint ();                                          \
        }                                                           \
    );                                                              \
} while (0)


///////////////////////////////////////////////////////////////////////////////
#define CHECK_MOD(V,M) do {                                                 \
    DEBUG_ONLY (                                                            \
        const auto &__check_mod_v = (V);                                    \
        const auto &__check_mod_m = (M);                                    \
                                                                            \
        if (!::cruft::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"; \
            breakpoint ();                                                  \
        }                                                                   \
    );                                                                      \
} 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';    \
        breakpoint ();                                          \
    }                                                           \
} 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';   \
            breakpoint ();                                          \
        }                                                           \
    } 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'   \
            breakpoint ();                                      \
        }                                                       \
    );                                                          \
} while (0)


///////////////////////////////////////////////////////////////////////////////
#define CHECK_NOTHROW(C) do {                                           \
    DEBUG_ONLY (                                                        \
        try {                                                           \
            C;                                                          \
        } catch (const std::exception &e) {                             \
            std::cerr << "unexpected exception: " << e.what () << '\n'; \
            breakpoint ();                                              \
        } catch (...) {                                                 \
            std::cerr << "unexpected exception: unknown\n";             \
            breakpoint ();                                              \
        }                                                               \
    );                                                                  \
} 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 cruft::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 cruft::debug {
    inline void
    clobber (void)
    {
        asm volatile ("": : : "memory");
    }
}


void breakpoint (void);


///////////////////////////////////////////////////////////////////////////////
// We define an identity macro for panic so that TCL and GCC don't decide to
// fuck us over by redefine the symbol.
//
// Apparently this can't be taken care of via a '-Dpanic=panic' argument,
// because it just ignores it for reasons I can't figure out.
#ifdef panic
#undef panic
#endif

#define panic panic


//-----------------------------------------------------------------------------
namespace cruft::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)
    : cruft::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)
    : cruft::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)
    : cruft::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 cruft::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
{
    cruft::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 cruft::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
    // partially 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.
    //
    // ArgsT is an optional set of auxiliary values that are required to
    // validate the target value.
    template <typename T, typename ...ArgsT>
    struct validator {
        static bool is_valid (T const&, ArgsT const&...) noexcept;
    };


    //-------------------------------------------------------------------------
    template <typename T, typename ...ArgsT>
    bool is_valid (const T &t, const ArgsT &...args) noexcept
    {
        return validator<T,ArgsT...>::is_valid (t, args...);
    }


    //-------------------------------------------------------------------------
    // forwarding validator from a pointer type to a reference type.
    //
    // null pointers are assumed to be invalid
    template <typename T, typename ...ArgsT>
    struct validator<T*,ArgsT...> {
        static bool is_valid (const T *val, ArgsT const &...args) noexcept
        {
            return val && ::cruft::debug::is_valid (*val, args...);
        }
    };


    ///////////////////////////////////////////////////////////////////////////
    // 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"