debug.hpp

Go to the documentation of this file.

#pragma once
 
#include <atomic>
#include <cstdlib>
#include <iostream>
#include <string>
 
namespace trlc {
namespace platform {
 
//==============================================================================
// Forward Declarations and Type Definitions
//==============================================================================
 
using AssertionHandler = void (*)(const char* expression,
                                  const char* file,
                                  int line,
                                  const char* function);
 
// Forward declaration of the default assertion handler
void defaultAssertionHandler(const char* expression,
                             const char* file,
                             int line,
                             const char* function) noexcept;
 
//==============================================================================
// Debug Mode Detection Functions
//==============================================================================
 
constexpr bool isDebugBuild() noexcept {
#ifdef NDEBUG
    return false;
#else
    return true;
#endif
}
 
constexpr bool isReleaseBuild() noexcept {
    return !isDebugBuild();
}
 
constexpr bool hasDebugInfo() noexcept {
    // In debug builds, debug info is usually available
    if (isDebugBuild()) {
        return true;
    }
 
    // Some compilers provide debug info even in release builds
#if defined(__GNUC__) || defined(__clang__)
    // GCC/Clang: Check for common debug flags
    // Note: This is compile-time approximation, actual availability
    // depends on command-line flags like -g
    return isDebugBuild();
#elif defined(_MSC_VER)
    // MSVC: Debug info can be enabled independently of release/debug
    // We conservatively assume it's available in debug builds only
    return isDebugBuild();
#else
    // Unknown compiler: Conservative assumption
    return isDebugBuild();
#endif
}
 
//==============================================================================
// Debug Utilities Class
//==============================================================================
 
class DebugUtils {
public:
    //--------------------------------------------------------------------------
    // Assertion Management
    //--------------------------------------------------------------------------
 
    static void setAssertionHandler(AssertionHandler handler) noexcept {
        if (handler == nullptr) {
            handler = defaultAssertionHandler;
        }
        _assertion_handler.store(handler, std::memory_order_release);
    }
 
    static AssertionHandler getAssertionHandler() noexcept {
        return _assertion_handler.load(std::memory_order_acquire);
    }
 
    //--------------------------------------------------------------------------
    // Debug Break Utilities
    //--------------------------------------------------------------------------
 
    static void debugBreak() noexcept {
#if defined(_WIN32) || defined(_WIN64)
    // Windows: Use __debugbreak() intrinsic
    #if defined(_MSC_VER)
        __debugbreak();
    #elif defined(__GNUC__) || defined(__clang__)
        // MinGW or Clang on Windows
        __builtin_trap();
    #else
        // Unknown compiler on Windows
        std::abort();
    #endif
#elif defined(__i386__) || defined(__x86_64__)
    // x86/x64: Use int3 instruction
    #if defined(__GNUC__) || defined(__clang__)
        __asm__ volatile("int3");
    #else
        // Fallback for unknown compiler
        std::abort();
    #endif
#elif defined(__aarch64__) || defined(__arm__)
    // ARM: Use builtin trap or BKPT instruction
    #if defined(__GNUC__) || defined(__clang__)
        __builtin_trap();
    #else
        std::abort();
    #endif
#else
    // Unknown architecture: Use generic trap or abort
    #if defined(__GNUC__) || defined(__clang__)
        __builtin_trap();
    #else
        std::abort();
    #endif
#endif
    }
 
    [[noreturn]] static void unreachable() noexcept {
        if constexpr (isDebugBuild()) {
            // In debug builds, make unreachable code obvious
            defaultAssertionHandler("unreachable code reached", __FILE__, __LINE__, __func__);
        }
 
        // Hint to compiler that this is unreachable
#if defined(__GNUC__) || defined(__clang__)
        __builtin_unreachable();
#elif defined(_MSC_VER)
        __assume(false);
#else
        // Fallback: abort the program
        std::abort();
#endif
    }
 
    [[noreturn]] static void abort(const char* message = nullptr) noexcept {
        if (message != nullptr) {
            std::cerr << "Program terminated: " << message << std::endl;
        } else {
            std::cerr << "Program terminated by DebugUtils::abort()" << std::endl;
        }
 
        // In debug builds, trigger a breakpoint first
        if constexpr (isDebugBuild()) {
            debugBreak();
        }
 
        std::abort();
    }
 
    //--------------------------------------------------------------------------
    // Stack Trace Support
    //--------------------------------------------------------------------------
 
    static bool canCaptureStackTrace() noexcept {
        // Platform-specific stack trace support detection
#if defined(_WIN32) && defined(_MSC_VER)
        // Windows with MSVC: StackWalk64 API available
        return true;
#elif defined(__GNUC__) || defined(__clang__)
    // GCC/Clang: Check for backtrace support
    #if defined(__GLIBC__) || defined(__APPLE__) || defined(__FreeBSD__)
        return true;  // backtrace() available
    #else
        return false;  // No backtrace support
    #endif
#else
        return false;  // Unknown platform/compiler
#endif
    }
 
    static void printStackTrace() noexcept {
        if (!canCaptureStackTrace()) {
            std::cerr << "Stack trace not available on this platform" << std::endl;
            return;
        }
 
        // Platform-specific stack trace implementation
#if defined(_WIN32) && defined(_MSC_VER)
        printStackTraceWindows();
#elif defined(__GNUC__) || defined(__clang__)
    #if defined(__GLIBC__) || defined(__APPLE__) || defined(__FreeBSD__)
        printStackTraceUnix();
    #else
        std::cerr << "Stack trace not implemented for this Unix variant" << std::endl;
    #endif
#else
        std::cerr << "Stack trace not implemented for this platform" << std::endl;
#endif
    }
 
private:
    //--------------------------------------------------------------------------
    // Private Members and Helper Functions
    //--------------------------------------------------------------------------
 
    static std::atomic<AssertionHandler> _assertion_handler;
 
#if defined(_WIN32) && defined(_MSC_VER)
    static void printStackTraceWindows() noexcept {
        // Implementation would use StackWalk64 API
        // For brevity, we just print a placeholder message
        std::cerr << "Windows stack trace would be printed here" << std::endl;
        std::cerr << "(StackWalk64 implementation not included in this example)" << std::endl;
    }
#endif
 
#if defined(__GNUC__) || defined(__clang__)
    #if defined(__GLIBC__) || defined(__APPLE__) || defined(__FreeBSD__)
    static void printStackTraceUnix() noexcept {
        // Implementation would use backtrace() and backtrace_symbols()
        // For brevity, we just print a placeholder message
        std::cerr << "Unix stack trace would be printed here" << std::endl;
        std::cerr << "(backtrace() implementation not included in this example)" << std::endl;
    }
    #endif
#endif
};
 
// Initialize the atomic assertion handler with the default (inline to avoid ODR issues)
inline std::atomic<AssertionHandler> DebugUtils::_assertion_handler{defaultAssertionHandler};
 
//==============================================================================
// Default Assertion Handler
//==============================================================================
 
inline void defaultAssertionHandler(const char* expression,
                                    const char* file,
                                    int line,
                                    const char* function) noexcept {
    std::cerr << "\n" << std::string(60, '=') << "\n";
    std::cerr << "ASSERTION FAILED\n";
    std::cerr << std::string(60, '=') << "\n";
    std::cerr << "Expression: " << expression << "\n";
    std::cerr << "File:       " << file << "\n";
    std::cerr << "Line:       " << line << "\n";
    std::cerr << "Function:   " << function << "\n";
    std::cerr << std::string(60, '=') << "\n";
 
    // Print stack trace if available
    if (DebugUtils::canCaptureStackTrace()) {
        std::cerr << "\nStack trace:\n";
        DebugUtils::printStackTrace();
        std::cerr << "\n";
    }
 
    std::cerr << "Program will now terminate.\n" << std::endl;
 
    // Trigger debugger break in debug builds
    if constexpr (isDebugBuild()) {
        DebugUtils::debugBreak();
    }
 
    std::abort();
}
 
}  // namespace platform
}  // namespace trlc
 
//==============================================================================
// Debug Macros
//==============================================================================
 
#ifdef NDEBUG
    #define TRLC_DEBUG_BUILD 0
#else
    #define TRLC_DEBUG_BUILD 1
#endif
 
#if TRLC_DEBUG_BUILD
    #define TRLC_ASSERT(expr)                                        \
        ((expr) ? void(0)                                            \
                : trlc::platform::DebugUtils::getAssertionHandler()( \
                      #expr, __FILE__, __LINE__, __func__))
#else
    #define TRLC_ASSERT(expr) ((void)0)
#endif
 
#if TRLC_DEBUG_BUILD
    #define TRLC_DEBUG_ONLY(code) code
#else
    #define TRLC_DEBUG_ONLY(code) ((void)0)
#endif
 
#ifdef TRLC_UNREACHABLE
    #undef TRLC_UNREACHABLE
#endif
#define TRLC_UNREACHABLE() trlc::platform::DebugUtils::unreachable()
 
#define TRLC_ABORT(msg) trlc::platform::DebugUtils::abort(msg)
 
#if defined(_MSC_VER)
   // Microsoft Visual C++: Use intrinsic
    #define TRLC_DEBUG_BREAK() __debugbreak()
#elif defined(__GNUC__) || defined(__clang__)
   // GCC or Clang: Use platform-specific inline assembly or builtin
    #if defined(__i386__) || defined(__x86_64__)
   // x86/x64: Use int3 instruction
        #define TRLC_DEBUG_BREAK() __asm__ volatile("int3")
    #else
   // Other architectures: Use compiler builtin
        #define TRLC_DEBUG_BREAK() __builtin_trap()
    #endif
#else
   // Unknown compiler: Fall back to DebugUtils implementation
    #define TRLC_DEBUG_BREAK() trlc::platform::DebugUtils::debugBreak()
#endif
 
//==============================================================================
// Compile-Time Validation
//==============================================================================
 
// Verify that debug detection works correctly
static_assert(trlc::platform::isDebugBuild() == !trlc::platform::isReleaseBuild(),
              "Debug and release build detection must be mutually exclusive");
 
// Verify that the debug build macro is consistent
#if TRLC_DEBUG_BUILD
static_assert(trlc::platform::isDebugBuild(),
              "TRLC_DEBUG_BUILD macro should match isDebugBuild() function");
#else
static_assert(trlc::platform::isReleaseBuild(),
              "TRLC_DEBUG_BUILD macro should match build detection functions");
#endif
 
// Verify that the assertion handler type is correctly defined
static_assert(std::is_same_v<trlc::platform::AssertionHandler,
                             void (*)(const char*, const char*, int, const char*)>,
              "AssertionHandler type signature must match specification");
 
//==============================================================================
// Documentation Examples and Usage Notes
//==============================================================================
 
/*
Example Usage:
 
1. Basic assertion:
   TRLC_ASSERT(ptr != nullptr);
   TRLC_ASSERT(index < size);
 
2. Custom assertion handler:
   trlc::platform::DebugUtils::setAssertionHandler(
       [](const char* expr, const char* file, int line, const char* func) {
           // Custom logging or error handling
           myLogger.error("Assertion failed: {} at {}:{} in {}",
                         expr, file, line, func);
           throw std::runtime_error("Assertion failed");
       }
   );
 
3. Debug-only code:
   TRLC_DEBUG_ONLY(
       auto start_time = std::chrono::high_resolution_clock::now();
   );
 
   // ... some operation ...
 
   TRLC_DEBUG_ONLY(
       auto end_time = std::chrono::high_resolution_clock::now();
       std::cout << "Operation took: "
                 << std::chrono::duration_cast<std::chrono::milliseconds>(
                        end_time - start_time).count() << "ms" << std::endl;
   );
 
4. Unreachable code marking:
   enum class State { A, B, C };
 
   std::string toString(State s) {
       switch (s) {
           case State::A: return "A";
           case State::B: return "B";
           case State::C: return "C";
       }
       TRLC_UNREACHABLE();  // Should never reach here
   }
 
5. Controlled termination:
   if (!initialize_critical_resource()) {
       TRLC_ABORT("Failed to initialize critical resource");
   }
 
Thread Safety:
- All DebugUtils static methods are thread-safe
- The assertion handler can be safely changed from any thread
- Multiple threads can safely call assertion-related functions
 
Performance:
- Zero overhead in release builds (macros expand to nothing)
- Minimal overhead in debug builds
- Assertion handler lookup uses atomic operations
- Stack trace capture is expensive but only used on failures
*/