Improve: Print stack-traces in test singal-handlers

Author: ashvardanian

.github/workflows/prerelease.yml

@@ -9,6 +9,7 @@ on:
 env:
   GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
   PYTHONUTF8: 1
+  PYTHONFAULTHANDLER: 1
   PYTHON_VERSION: 3.11
   DOTNET_VERSION: 8.0.x
   NODE_VERSION: 20

c/CMakeLists.txt

@@ -6,6 +6,10 @@ if (USEARCH_BUILD_TEST_C)
     include(CTest)
     enable_testing()
     add_test(NAME test_c COMMAND test_c)
+
+    # Export the dynamic symbol table so `backtrace_symbols_fd` can resolve
+    # function names when the in-test crash handler fires.
+    set_target_properties(test_c PROPERTIES ENABLE_EXPORTS ON)
 endif ()
 
 # This article discusses a better way to allow building either static or shared libraries:

c/test.c

@@ -1,10 +1,91 @@
+/**
+ *  @file       test.c
+ *  @author     Ash Vardanian
+ *  @brief      Unit tests for the pure-C ABI of USearch (`usearch.h`).
+ *  @date       June 25, 2023
+ *
+ *  Exercises the lifecycle of `usearch_index_t` through the public C surface:
+ *  index creation with every supported metric and scalar kind, `add` / `get` /
+ *  `find` / `remove`, on-disk `save` / `load` / `view`, and error propagation
+ *  via `usearch_error_t`. The harness is intentionally dependency-free so it
+ *  can run in the same matrix as the C++ tests and on cross-compilation
+ *  targets where only the C runtime is available.
+ *
+ *  On startup we install a signal handler (see `install_crash_handlers`) that
+ *  prints a native back-trace before re-raising, so CI logs pinpoint the
+ *  faulting frame instead of stopping at a bare exit code.
+ */
 #include <errno.h>
-#include <stdio.h> // `remove`
+#include <signal.h> // `signal`, `raise`, `SIGSEGV`
+#include <stdio.h>  // `remove`
 #include <stdlib.h>
+#include <string.h> // `memset`
 #include <sys/stat.h>
 
+/* Back-trace support for the C test harness. The `signal` API is standard C;
+ * the back-trace itself is taken via an OS-specific facility since C has no
+ * standard stack-introspection API. On Windows, `dbghelp.h` references types
+ * (e.g. `PSTR`) that are only defined after `windows.h`, so the two headers
+ * are separated by a blank line to keep clang-format from re-sorting them
+ * into a single alphabetized block. */
+#if defined(_WIN32)
+#include <windows.h>
+
+#include <dbghelp.h>
+#pragma comment(lib, "Dbghelp.lib")
+#elif defined(__unix__) || defined(__APPLE__)
+#include <execinfo.h>
+#include <unistd.h>
+#endif
+
 #include "usearch.h"
 
+static void usearch_write_backtrace(int signal_number) {
+    fprintf(stderr, "\n[usearch] Fatal signal %d. Back-trace:\n", signal_number);
+#if defined(_WIN32)
+    enum { backtrace_depth_limit = 64 };
+    void* backtrace_frames[backtrace_depth_limit];
+    USHORT backtrace_depth = CaptureStackBackTrace(0, backtrace_depth_limit, backtrace_frames, NULL);
+    HANDLE current_process = GetCurrentProcess();
+    SymInitialize(current_process, NULL, TRUE);
+
+    unsigned char symbol_info_buffer[sizeof(SYMBOL_INFO) + 256 * sizeof(char)];
+    SYMBOL_INFO* symbol_info = (SYMBOL_INFO*)symbol_info_buffer;
+    symbol_info->MaxNameLen = 255;
+    symbol_info->SizeOfStruct = sizeof(SYMBOL_INFO);
+
+    for (USHORT frame_index = 0; frame_index < backtrace_depth; ++frame_index) {
+        if (SymFromAddr(current_process, (DWORD64)backtrace_frames[frame_index], 0, symbol_info))
+            fprintf(stderr, "  #%2u %s + 0x%llx\n", (unsigned)frame_index, symbol_info->Name,
+                    (unsigned long long)((DWORD64)backtrace_frames[frame_index] - symbol_info->Address));
+        else
+            fprintf(stderr, "  #%2u %p\n", (unsigned)frame_index, backtrace_frames[frame_index]);
+    }
+#elif defined(__unix__) || defined(__APPLE__)
+    enum { backtrace_depth_limit = 64 };
+    void* backtrace_frames[backtrace_depth_limit];
+    int backtrace_depth = backtrace(backtrace_frames, backtrace_depth_limit);
+    backtrace_symbols_fd(backtrace_frames, backtrace_depth, STDERR_FILENO);
+#else
+    (void)signal_number;
+    fprintf(stderr, "  <back-trace unavailable on this platform>\n");
+#endif
+    fflush(stderr);
+}
+
+static void usearch_crash_handler(int signal_number) {
+    usearch_write_backtrace(signal_number);
+    /* Restore the default disposition and re-raise so the shell / CI sees the true exit status. */
+    signal(signal_number, SIG_DFL);
+    raise(signal_number);
+}
+
+static void install_crash_handlers(void) {
+    int const fatal_signals[] = {SIGSEGV, SIGABRT, SIGILL, SIGFPE};
+    for (unsigned signal_index = 0; signal_index < sizeof(fatal_signals) / sizeof(fatal_signals[0]); ++signal_index)
+        signal(fatal_signals[signal_index], &usearch_crash_handler);
+}
+
 void expect(bool must_be_true, char const* message) {
     if (must_be_true)
         return;
@@ -368,6 +449,7 @@ void test_view(size_t const collection_size, size_t const dimensions) {
 }
 
 int main(int argc, char const* argv[]) {
+    install_crash_handlers();
     printf("Running tests...\n");
     printf("USearch version: %s\n", usearch_version());
 

cpp/CMakeLists.txt

@@ -7,6 +7,10 @@ if (USEARCH_BUILD_TEST_CPP)
 
     target_include_directories(test_cpp PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/../stringzilla/include)
 
+    # Export the dynamic symbol table so `backtrace_symbols` / `std::stacktrace`
+    # can resolve function names when the in-test crash handler fires.
+    set_target_properties(test_cpp PROPERTIES ENABLE_EXPORTS ON)
+
     if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
         target_compile_options(test_cpp PRIVATE -Wno-vla -Wno-unused-function -Wno-cast-function-type)
     endif ()

cpp/test.cpp

@@ -12,14 +12,45 @@
  *      - 128-bit `uuid_t` keys and `enum slot64_t : std::uint64_t` make most sense for
  *        for database users, implementing portable, concurrent systems.
  */
+#include <cassert> // `assert`
+#include <cmath>   // `std::abs`
+#include <csignal> // `std::signal`, `SIGSEGV`, ...
+#include <cstdio>  // `std::fprintf`
+#include <cstdlib> // `std::_Exit`
+
 #include <algorithm>     // `std::shuffle`
-#include <cassert>       // `assert`
-#include <cmath>         // `std::abs`
 #include <random>        // `std::default_random_engine`
 #include <stdexcept>     // `std::terminate`
 #include <unordered_map> // `std::unordered_map`
 #include <vector>        // `std::vector`
 
+// Back-trace support. Prefer the C++23 `<stacktrace>` library when the
+// toolchain + stdlib expose it (`__cpp_lib_stacktrace`); otherwise fall back
+// to the OS-native facility so that unit-test crashes in CI log something
+// useful beyond a bare exit code.
+#if defined(__has_include)
+#if __has_include(<stacktrace>)
+#include <stacktrace>
+#endif
+#endif
+#if defined(__cpp_lib_stacktrace) && __cpp_lib_stacktrace >= 202011L
+#define USEARCH_HAS_STD_STACKTRACE 1
+#else
+#define USEARCH_HAS_STD_STACKTRACE 0
+#if defined(_WIN32)
+// `windows.h` must precede `dbghelp.h` — the latter uses `PSTR` and friends
+// that are only defined after `windows.h`. The blank line keeps clang-format
+// from re-sorting the two headers into a single alphabetized block.
+#include <windows.h>
+
+#include <dbghelp.h>
+#pragma comment(lib, "Dbghelp.lib")
+#else
+#include <execinfo.h>
+#include <unistd.h>
+#endif
+#endif
+
 #define SZ_USE_X86_AVX512 0            // Sanitizers hate AVX512
 #include <stringzilla/stringzilla.hpp> // Levenshtein distance implementation
 
@@ -1179,7 +1210,63 @@ void test_isolate() {
     }
 }
 
+static void usearch_write_backtrace(int signal_number) {
+    std::fprintf(stderr, "\n[usearch] Fatal signal %d. Back-trace:\n", signal_number);
+#if USEARCH_HAS_STD_STACKTRACE
+    // C++23 `std::stacktrace` covers every platform the library can reach.
+    auto const current_trace = std::stacktrace::current();
+    std::size_t frame_index = 0;
+    for (auto const& frame : current_trace) {
+        std::fprintf(stderr, "  #%2zu %s\n", frame_index, std::to_string(frame).c_str());
+        ++frame_index;
+    }
+#elif defined(_WIN32)
+    // Fallback for MSVC stdlibs without `<stacktrace>`: DbgHelp API.
+    constexpr USHORT backtrace_depth_limit = 64;
+    void* backtrace_frames[backtrace_depth_limit];
+    USHORT backtrace_depth = CaptureStackBackTrace(0, backtrace_depth_limit, backtrace_frames, nullptr);
+    HANDLE current_process = GetCurrentProcess();
+    SymInitialize(current_process, nullptr, TRUE);
+
+    unsigned char symbol_info_buffer[sizeof(SYMBOL_INFO) + 256 * sizeof(char)];
+    SYMBOL_INFO* symbol_info = reinterpret_cast<SYMBOL_INFO*>(symbol_info_buffer);
+    symbol_info->MaxNameLen = 255;
+    symbol_info->SizeOfStruct = sizeof(SYMBOL_INFO);
+
+    for (USHORT frame_index = 0; frame_index < backtrace_depth; ++frame_index) {
+        if (SymFromAddr(current_process, reinterpret_cast<DWORD64>(backtrace_frames[frame_index]), 0, symbol_info))
+            std::fprintf(stderr, "  #%2u %s + 0x%llx\n", static_cast<unsigned>(frame_index), symbol_info->Name,
+                         static_cast<unsigned long long>(reinterpret_cast<DWORD64>(backtrace_frames[frame_index]) -
+                                                         symbol_info->Address));
+        else
+            std::fprintf(stderr, "  #%2u %p\n", static_cast<unsigned>(frame_index), backtrace_frames[frame_index]);
+    }
+#else
+    // Fallback for POSIX stdlibs without `<stacktrace>`: `<execinfo.h>`.
+    constexpr int backtrace_depth_limit = 64;
+    void* backtrace_frames[backtrace_depth_limit];
+    int const backtrace_depth = backtrace(backtrace_frames, backtrace_depth_limit);
+    backtrace_symbols_fd(backtrace_frames, backtrace_depth, STDERR_FILENO);
+#endif
+    std::fflush(stderr);
+}
+
+static void usearch_crash_handler(int signal_number) {
+    usearch_write_backtrace(signal_number);
+    // Restore the default disposition and re-raise so the shell / CI sees the true exit status.
+    std::signal(signal_number, SIG_DFL);
+    std::raise(signal_number);
+}
+
+static void install_crash_handlers() {
+    int const fatal_signals[] = {SIGSEGV, SIGABRT, SIGILL, SIGFPE};
+    for (int signal_number : fatal_signals)
+        std::signal(signal_number, &usearch_crash_handler);
+}
+
 int main(int, char**) {
+    install_crash_handlers();
+
     std::printf("Hardware acceleration compiled: %s\n", hardware_acceleration_compiled());
     std::printf("Hardware acceleration available: %s\n", hardware_acceleration_available());