UT_Assert.h

Go to the documentation of this file.

// UT_Assert.h
//
// Custom portable UT_ASSERT macro
//

#ifndef UT_ASSERT_H_INCLUDED
#define UT_ASSERT_H_INCLUDED

#include "UT_API.h"

#define UT_ASSERT_LEVEL_NONE        0
#define UT_ASSERT_LEVEL_NORMAL      1
#define UT_ASSERT_LEVEL_PARANOID    2
#define UT_ASSERT_LEVEL_SLOW        3

#ifndef UT_ASSERT_LEVEL
    #define UT_ASSERT_LEVEL UT_ASSERT_LEVEL_NONE
#endif

// Generates an assertion. Returns TRUE if we should ignore further asserts.
UT_API void UT_Assert( const char *file, int linenum, const char *function,
               const char *condition, const char *reason, int &ignoreflag);

// Similar to UT_Assert() but using a variadic format string for the reason.
UT_API void UT_AssertFormat( const char *file, int linenum,
               const char *function, const char *condition, int &ignoreflag,
               const char *reason_fmt...);

// Return true if the assert dialog is open and we are waiting for the
// user to choose a response in the dialog.
UT_API bool UTisWaitingForAssertResponse();

// Methods to temporarily disable interactive asserts in specific dangerous
// situations.
UT_API void UTdisableInteractiveAssertsOn();
UT_API void UTdisableInteractiveAssertsOff();

using UT_TraceCallback = void (*)();

/// Set additional tracing callback when an assertion fails and a stack trace
/// is requested. The previous callback is returned.
UT_API UT_TraceCallback
UTassertSetExtraTraceCallback(UT_TraceCallback callback);

/// Assertions triggered within the lifetime of UT_AssertExceptionScope
/// variables will cause UT_AssertException to be thrown instead of the usual
/// handling. By default, this is only done when interactive asserts are
/// disabled. This class is intended for testing purposes only.
class UT_API UT_AssertExceptionScope
{
public:
    UT_AssertExceptionScope(bool when_interactive = true);
    ~UT_AssertExceptionScope();

    UT_AssertExceptionScope(const UT_AssertExceptionScope &) = delete;
    UT_AssertExceptionScope &operator=(const UT_AssertExceptionScope &) = delete;
private:
    bool myEnabled;
};

// Exception class thrown when assertions are triggered within an
// UT_AssertExceptionScope
class UT_API UT_AssertException
{
public:
    UT_AssertException(const char *what);
    ~UT_AssertException();

    UT_AssertException(const UT_AssertException &);
    UT_AssertException &operator=(const UT_AssertException &);

    const char *what() const noexcept { return myWhat; }

private:
    char *myWhat; // using C string to avoid pulling in UT_String*.h
};


#if defined(__GNUC__)
#   define UT_ASSERT_FUNC __PRETTY_FUNCTION__
#elif defined(_MSC_VER)
#   define UT_ASSERT_FUNC __FUNCSIG__
#elif defined(__FUNCTION__)
#   define UT_ASSERT_FUNC __FUNCTION__ "()"
#else
#   define UT_ASSERT_FUNC ((char *)0)
#endif

#if (UT_ASSERT_LEVEL > UT_ASSERT_LEVEL_NONE)
    #ifdef UT_INTERNAL_ASSERT
        #error UT_INTERNAL_UT_ASSERT is already defined!
    #endif
    #define UT_INTERNAL_ASSERT(ZZ, ...) \
            ((ZZ) ? void(0) :               \
             [&]() {                        \
                static int ignore = 0;      \
                if( !ignore )               \
                    UT_AssertFormat( __FILE__, __LINE__, UT_ASSERT_FUNC, \
                                     #ZZ, ignore, __VA_ARGS__); \
             }())
    #define UT_INTERNAL_VERIFY(ZZ, ...) \
            do {                        \
                static int ignore = 0;  \
                /* always run ZZ */     \
                if( !(ZZ) && !ignore )  \
                    UT_AssertFormat( __FILE__, __LINE__, UT_ASSERT_FUNC, \
                                     #ZZ, ignore, __VA_ARGS__); \
            } while (false)

    #define UT_INTERNAL_VERIFY_RETURN(ZZ, RV, ...) \
            if (!(ZZ))                  \
            {                           \
                static int ignore = 0;  \
                if (!ignore)            \
                    UT_AssertFormat( __FILE__, __LINE__, UT_ASSERT_FUNC, \
                                     #ZZ, ignore, __VA_ARGS__); \
                return RV;              \
            }
#endif

#ifdef UT_ASSERT_SLOW
    #error UT_ASSERT_SLOW is already defined!
#endif
#ifdef UT_ASSERT_P
    #error UT_ASSERT_P is already defined!
#endif
#ifdef UT_ASSERT
    #error UT_ASSERT is already defined!
#endif
#ifdef UT_ASSERT_MSG_SLOW
    #error UT_ASSERT_MSG_SLOW is already defined!
#endif
#ifdef UT_ASSERT_MSG_P
    #error UT_ASSERT_MSG_P is already defined!
#endif
#ifdef UT_ASSERT_MSG
    #error UT_ASSERT_MSG is already defined!
#endif

// do these in descending order:
#if (UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_SLOW)
    #define UT_ASSERT_SLOW(ZZ)          UT_INTERNAL_ASSERT(ZZ, 0)
    #define UT_ASSERT_P(ZZ)             UT_INTERNAL_ASSERT(ZZ, 0)
    #define UT_ASSERT(ZZ)               UT_INTERNAL_ASSERT(ZZ, 0)
    #define UT_ASSERT_MSG_SLOW(ZZ, ...) UT_INTERNAL_ASSERT(ZZ, __VA_ARGS__)
    #define UT_ASSERT_MSG_P(ZZ, ...)    UT_INTERNAL_ASSERT(ZZ, __VA_ARGS__)
    #define UT_ASSERT_MSG(ZZ, ...)      UT_INTERNAL_ASSERT(ZZ, __VA_ARGS__)
#elif (UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_PARANOID)
    #define UT_ASSERT_SLOW(ZZ)          ((void)0)
    #define UT_ASSERT_P(ZZ)             UT_INTERNAL_ASSERT(ZZ, 0)
    #define UT_ASSERT(ZZ)               UT_INTERNAL_ASSERT(ZZ, 0)
    #define UT_ASSERT_MSG_SLOW(ZZ, ...) ((void)0)
    #define UT_ASSERT_MSG_P(ZZ, ...)    UT_INTERNAL_ASSERT(ZZ, __VA_ARGS__)
    #define UT_ASSERT_MSG(ZZ, ...)      UT_INTERNAL_ASSERT(ZZ, __VA_ARGS__)
#elif (UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_NORMAL)
    #define UT_ASSERT_SLOW(ZZ)          ((void)0)
    #define UT_ASSERT_P(ZZ)             ((void)0)
    #define UT_ASSERT(ZZ)               UT_INTERNAL_ASSERT(ZZ, 0)
    #define UT_ASSERT_MSG_SLOW(ZZ, ...) ((void)0)
    #define UT_ASSERT_MSG_P(ZZ, ...)    ((void)0)
    #define UT_ASSERT_MSG(ZZ, ...)      UT_INTERNAL_ASSERT(ZZ, __VA_ARGS__)
#else // if (UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_NONE)
    #define UT_ASSERT_SLOW(ZZ)          ((void)0)
    #define UT_ASSERT_P(ZZ)             ((void)0)
    #define UT_ASSERT(ZZ)               ((void)0)
    #define UT_ASSERT_MSG_SLOW(ZZ, ...) ((void)0)
    #define UT_ASSERT_MSG_P(ZZ, ...)    ((void)0)
    #define UT_ASSERT_MSG(ZZ, ...)      ((void)0)
#endif

#include <SYS/SYS_StaticAssert.h>
#define UT_ASSERT_COMPILETIME(expr) SYS_STATIC_ASSERT(expr)

// This macro allows you to enable a block of code only
// when UT_ASSERT is enabled. This will help clean up
// "unreferenced variables" in the case where you have variables that
// are only referenced in asserts.

#if UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_NORMAL
#define UT_IF_ASSERT(ZZ) ZZ
#define UT_IFNOT_ASSERT(ZZ)
#else
#define UT_IF_ASSERT(ZZ)
#define UT_IFNOT_ASSERT(ZZ) ZZ
#endif

#if UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_PARANOID
#define UT_IF_ASSERT_P(ZZ) ZZ
#define UT_IFNOT_ASSERT_P(ZZ)
#else
#define UT_IF_ASSERT_P(ZZ)
#define UT_IFNOT_ASSERT_P(ZZ) ZZ
#endif

#if UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_SLOW
#define UT_IF_ASSERT_SLOW(ZZ) ZZ
#define UT_IFNOT_ASSERT_SLOW(ZZ)
#else
#define UT_IF_ASSERT_SLOW(ZZ)
#define UT_IFNOT_ASSERT_SLOW(ZZ) ZZ
#endif

// When asserts are enabled, UT_VERIFY() will trigger an assert if the expr
// is false. When asserts are disabled, the expr is still evaluated.
#if UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_NORMAL
    #define UT_VERIFY(expr)             UT_INTERNAL_VERIFY(expr, 0)
    #define UT_VERIFY_MSG(expr, ...)    UT_INTERNAL_VERIFY(expr, __VA_ARGS__)
    #define UT_VERIFY_RETURN(ZZ, RV)    UT_INTERNAL_VERIFY_RETURN(ZZ, RV, 0)
    #define UT_VERIFY_RETURN_VOID(ZZ)   UT_INTERNAL_VERIFY_RETURN(ZZ, , 0)
    #define UT_VERIFY_RETURN_MSG(ZZ, RV, ...)   UT_INTERNAL_VERIFY_RETURN(ZZ, RV, __VA_ARGS__)
    #define UT_VERIFY_RETURN_VOID_MSG(ZZ, ...)  UT_INTERNAL_VERIFY_RETURN(ZZ, ,__VA_ARGS__)
#else
    #define UT_VERIFY(expr)             ((void)(expr))
    #define UT_VERIFY_MSG(expr, ...)    ((void)(expr))
    #define UT_VERIFY_RETURN(ZZ, RV)    if (!(ZZ)) { return RV; }
    #define UT_VERIFY_RETURN_VOID(ZZ)   if (!(ZZ)) { return; }
    #define UT_VERIFY_RETURN_MSG(ZZ, RV, ...)   if (!(ZZ)) { return RV; }
    #define UT_VERIFY_RETURN_VOID_MSG(ZZ, ...)  if (!(ZZ)) { return; }
#endif
#if UT_ASSERT_LEVEL >= UT_ASSERT_LEVEL_PARANOID
    #define UT_VERIFY_P(expr)   UT_INTERNAL_VERIFY(expr, 0)
#else
    #define UT_VERIFY_P(expr)   ((void)(expr))
#endif

enum UT_AssertResponse
{
    UT_ASSERT_RESPONSE_DEBUG,
    UT_ASSERT_RESPONSE_IGNORE,
    UT_ASSERT_RESPONSE_IGNORE_ALL,
    UT_ASSERT_RESPONSE_TRACE,
    UT_ASSERT_RESPONSE_ERROR
};

/// UTverify_cast performs a static_cast, but when paranoid assertions are
/// enabled it will also perform a dynamic cast to verify the cast is valid.
/// UT_ASSERT_P() is used instead of UT_ASSERT() to avoid overhead in normal
/// development builds.
#include <SYS/SYS_Inline.h>
template <typename TO_T, typename FROM_T>
SYS_FORCE_INLINE TO_T
UTverify_cast(FROM_T from)
{
    UT_ASSERT_P(dynamic_cast<TO_T>(from) == from && "Invalid static cast");
    return static_cast<TO_T>(from);
}

/// UTsubclassResponsibility raises an assertion indicating that a subclass has
/// not implemented an inherited method.  This should only be called from a
/// base class method that is not expected to run.
UT_API void UTsubclassResponsibility(const char *classname, const char *member); 

#endif // UT_ASSERT_H_INCLUDED