Release v1.8.8: Add gspy.error() for fatal error signaling

Author: jasonGtg

GSPy.cpp

@@ -7,57 +7,71 @@
 
 extern "C" void GSPy(int methodID, int* status, double* inargs, double* outargs)
 {
-    // Initialize the logger once using the new ConfigManager
-    static bool logger_initialized = false;
-    if (!logger_initialized) {
-        std::string log_filename = GetLogFilename();
-        int log_level = GetLogLevel(); // Get from config file
-        InitLogger(log_filename, static_cast<LogLevel>(log_level));
-        SetLogLevelFromInt(log_level); // Apply log level atomically
-        logger_initialized = true;
-    }
+    try {
+        // Initialize the logger once using the new ConfigManager
+        static bool logger_initialized = false;
+        if (!logger_initialized) {
+            std::string log_filename = GetLogFilename();
+            int log_level = GetLogLevel(); // Get from config file
+            InitLogger(log_filename, static_cast<LogLevel>(log_level));
+            SetLogLevelFromInt(log_level); // Apply log level atomically
+            logger_initialized = true;
+        }
 
-    LogDebug("GSPy called with MethodID: " + std::to_string(methodID));
+        LogDebug("GSPy called with MethodID: " + std::to_string(methodID));
 
-    *status = 0;
-    std::string errorMessage;
+        *status = 0;
+        std::string errorMessage;
 
-    switch (methodID)
-    {
-    case 0: // Initialize
-        if (!InitializePython(errorMessage)) {
-            SendErrorToGoldSim(errorMessage, status, outargs);
-        }
-        break;
+        switch (methodID)
+        {
+        case 0: // Initialize
+            if (!InitializePython(errorMessage)) {
+                SendErrorToGoldSim(errorMessage, status, outargs);
+            }
+            break;
 
-    case 1: // Calculate
-        ExecuteCalculation(inargs, outargs, errorMessage);
-        if (!errorMessage.empty()) {
-            SendErrorToGoldSim(errorMessage, status, outargs);
-        }
-        break;
-
-    case 2: // Report Version
-        LogInfo("Reporting version to GoldSim: " + std::string(GSPY_VERSION));
-        outargs[0] = GSPY_VERSION_DOUBLE;
-        break;
-
-    case 3: // Report Arguments
-        // We need to initialize to read the config to get argument counts
-        if (!InitializePython(errorMessage)) {
-            SendErrorToGoldSim(errorMessage, status, outargs);
-            return;
-        }
-        outargs[0] = static_cast<double>(GetNumberOfInputs());
-        outargs[1] = static_cast<double>(GetNumberOfOutputs());
-        break;
+        case 1: // Calculate
+            ExecuteCalculation(inargs, outargs, errorMessage);
+            if (!errorMessage.empty()) {
+                LogDebug("Sending error to GoldSim: " + errorMessage);
+                SendErrorToGoldSim(errorMessage, status, outargs);
+                LogDebug("Error sent to GoldSim successfully");
+            }
+            break;
 
-    case 99: // Cleanup
-        FinalizePython();
-        break;
+        case 2: // Report Version
+            LogInfo("Reporting version to GoldSim: " + std::string(GSPY_VERSION));
+            outargs[0] = GSPY_VERSION_DOUBLE;
+            break;
 
-    default:
-        *status = 1;
-        break;
+        case 3: // Report Arguments
+            // We need to initialize to read the config to get argument counts
+            if (!InitializePython(errorMessage)) {
+                SendErrorToGoldSim(errorMessage, status, outargs);
+                return;
+            }
+            outargs[0] = static_cast<double>(GetNumberOfInputs());
+            outargs[1] = static_cast<double>(GetNumberOfOutputs());
+            break;
+
+        case 99: // Cleanup
+            FinalizePython();
+            break;
+
+        default:
+            *status = 1;
+            break;
+        }
+    }
+    catch (const std::exception& e) {
+        LogError(std::string("C++ exception caught in GSPy: ") + e.what());
+        std::string errorMsg = std::string("C++ exception: ") + e.what();
+        SendErrorToGoldSim(errorMsg, status, outargs);
+    }
+    catch (...) {
+        LogError("Unknown C++ exception caught in GSPy");
+        std::string errorMsg = "Unknown C++ exception in GSPy";
+        SendErrorToGoldSim(errorMsg, status, outargs);
     }
 }

GSPy.h

@@ -4,7 +4,7 @@
 // Version information
 #define GSPY_VERSION_MAJOR 1
 #define GSPY_VERSION_MINOR 8
-#define GSPY_VERSION_PATCH 7
+#define GSPY_VERSION_PATCH 8
 
 // Automatically generate version string and double from components
 #define STRINGIFY(x) #x

GSPy_Error.cpp

@@ -1,4 +1,5 @@
 #include "GSPy_Error.h"
+#include "Logger.h"
 #include <cstring> // For strncpy_s
 
 // The static buffer now lives here, dedicated to our error messenger.
@@ -7,14 +8,16 @@ static char errorMessageBuffer[256];
 // The function's implementation is moved here.
 void SendErrorToGoldSim(const std::string& message, int* status, double* outargs)
 {
-    // Copy the message into our static buffer, ensuring it's null-terminated.
-    strncpy_s(errorMessageBuffer, message.c_str(), sizeof(errorMessageBuffer) - 1);
-    errorMessageBuffer[sizeof(errorMessageBuffer) - 1] = '\0'; // Ensure null termination
-
-    // Tell GoldSim a fatal error with a message has occurred.
-        * status = -1;
-
-    // GoldSim expects the first output argument to be a pointer to the message.
-        uintptr_t* pAddr = (uintptr_t*)outargs;
-    *pAddr = (uintptr_t)errorMessageBuffer;
+    // For 64-bit DLLs running in separate process space, pointer-based error
+    // messages don't work. Instead, we just set the status to indicate failure.
+    // The error message is logged, and GoldSim will show a generic error.
+    
+    // Log the full error message
+    LogError("Fatal error to report to GoldSim: " + message);
+    
+    // Tell GoldSim a fatal error occurred
+    // Use status = 1 for generic failure (not -1 which expects a pointer)
+    *status = 1;
+    
+    LogDebug("Status set to: " + std::to_string(*status));
 }

PythonManager.cpp

@@ -34,6 +34,9 @@ static PyObject* pFunc = nullptr;
 // Python-Callable Logging Function
 // =================================================================
 
+// Global pointer to store error message for GoldSim (static - internal use only)
+static std::string* g_python_error_message = nullptr;
+
 // Python-callable logging function (static - internal use only)
 static PyObject* PythonLog(PyObject* self, PyObject* args) {
     const char* message;
@@ -66,9 +69,40 @@ static PyObject* PythonLog(PyObject* self, PyObject* args) {
     Py_RETURN_NONE;
 }
 
+// Python-callable error function that signals a fatal error to GoldSim
+// NOTE: For 64-bit DLLs running in separate process space, we cannot pass
+// pointers to GoldSim. Instead, we raise a Python exception that C++ will catch.
+static PyObject* PythonError(PyObject* self, PyObject* args) {
+    const char* message;
+    
+    // Parse arguments: message (required)
+    if (!PyArg_ParseTuple(args, "s", &message)) {
+        return nullptr;
+    }
+    
+    // Log the error
+    LogError(std::string(message));
+    
+    // Store the error message for GoldSim
+    if (g_python_error_message == nullptr) {
+        g_python_error_message = new std::string(message);
+    } else {
+        *g_python_error_message = message;
+    }
+    
+    LogDebug("gspy.error() called, message stored: " + std::string(message));
+    
+    // Raise a Python RuntimeError with the message
+    // This will cause PyObject_CallObject to return NULL, triggering our error handling
+    PyErr_SetString(PyExc_RuntimeError, message);
+    
+    return nullptr;  // Return NULL to indicate an exception occurred
+}
+
 // Method definition for the gspy module
 static PyMethodDef GSPyMethods[] = {
     {"log", PythonLog, METH_VARARGS, "Write a message to the GSPy log file"},
+    {"error", PythonError, METH_VARARGS, "Signal a fatal error to GoldSim and terminate the simulation"},
     {nullptr, nullptr, 0, nullptr} // Sentinel
 };
 
@@ -360,6 +394,12 @@ void FinalizePython() {
     Py_XDECREF(pFunc);
     Py_XDECREF(pModule);
 
+    // Clean up the error message pointer
+    if (g_python_error_message != nullptr) {
+        delete g_python_error_message;
+        g_python_error_message = nullptr;
+    }
+
     if (Py_IsInitialized()) {
         // LOGGING: Confirm that we are shutting down the interpreter.
         LogInfo("Shutting down Python interpreter.");
@@ -448,6 +488,33 @@ void ExecuteCalculation(double* inargs, double* outargs, std::string& errorMessa
     PyObject* pResultTuple = PyObject_CallObject(pFunc, pArgs);
     Py_DECREF(pArgs);
 
+    // 2.5. Check if Python raised an exception (including from gspy.error())
+    if (pResultTuple == nullptr) {
+        // Python exception occurred
+        if (g_python_error_message != nullptr && !g_python_error_message->empty()) {
+            // gspy.error() was called - use the stored message
+            errorMessage = "GSPy Error: " + *g_python_error_message;
+            LogDebug("Python signaled fatal error via gspy.error(): " + *g_python_error_message);
+            g_python_error_message->clear();
+        } else {
+            // Some other Python exception - get the error details
+            PyErr_Print();
+            errorMessage = "Python exception occurred (see log for details)";
+            LogError(errorMessage);
+        }
+        return;
+    }
+
+    // 2.6. Check if gspy.error() was called but Python still returned successfully
+    // (This shouldn't happen with the new implementation, but keep as safety check)
+    if (g_python_error_message != nullptr && !g_python_error_message->empty()) {
+        errorMessage = "GSPy Error: " + *g_python_error_message;
+        LogDebug("Python signaled fatal error: " + errorMessage);
+        g_python_error_message->clear();
+        Py_DECREF(pResultTuple);
+        return;
+    }
+
     // 3. Delegate result processing
     if (!MarshalOutputsToCpp(pResultTuple, config["outputs"], outargs, errorMessage)) {
         // MarshalOutputsToCpp handles its own error logging and Py_DECREF

docs/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.8] - 2025-11-18
+
+### Added
+- **Fatal Error Signaling:** New `gspy.error()` function allows Python code to signal critical errors and stop GoldSim simulations
+  * **Function:** `gspy.error(message)` - Signals a fatal error and terminates the simulation
+  * **Use Case:** Critical errors where results would be invalid (division by zero, missing required data, invalid configuration)
+  * **Behavior:** Raises Python RuntimeError, C++ catches it, logs detailed error, sets status = 1, simulation stops
+  * **Error Details:** Full error message and Python traceback written to log file
+  * **GoldSim Display:** Shows "Error in external function. Return code 1." (generic message due to process separation)
+  * **Architecture Note:** 32-bit GoldSim / 64-bit DLL run in separate processes, preventing direct error message passing
+
+### Enhanced
+- **Error Handling Documentation:** Comprehensive documentation for both error handling approaches
+  * `docs/Using_gspy_error.md` - Quick start guide with examples
+  * `docs/Error_Handling_Best_Practices.md` - Complete guide with use cases and patterns
+  * `docs/Error_Handling_Quick_Reference.md` - Quick reference card
+  * `docs/Slide_Updates_Error_Handling.md` - Updated presentation content
+  * `docs/CHANGELOG_Error_Handling.md` - Detailed version history and migration guide
+  * `examples/Error Handling Demo/` - Working demonstration with test cases
+
+### Improved
+- **Exception Handling:** Added comprehensive try-catch blocks in main GSPy function
+  * Catches and logs C++ exceptions with detailed error messages
+  * Prevents crashes and provides better error diagnostics
+  * Ensures clean error reporting to GoldSim
+
+- **Python Exception Detection:** Enhanced ExecuteCalculation to properly handle Python exceptions
+  * Detects when Python raises exceptions (including from gspy.error())
+  * Retrieves stored error messages for detailed logging
+  * Provides fallback error handling for unexpected exceptions
+
+### Technical Details
+- **Implementation:** 
+  * Added `PythonError()` function that raises Python RuntimeError
+  * Added global error message storage (`g_python_error_message`)
+  * Modified `ExecuteCalculation()` to detect Python exceptions and retrieve stored messages
+  * Updated `SendErrorToGoldSim()` to use status = 1 (compatible with separate process architecture)
+  * Added exception handling wrapper in main `GSPy()` function
+  * Added cleanup in `FinalizePython()` for error message pointer
+
+- **Error Handling Flow:**
+  1. Python calls `gspy.error(message)`
+  2. Message stored in C++ and Python RuntimeError raised
+  3. C++ detects NULL return from Python
+  4. C++ retrieves stored message and logs it
+  5. C++ sets status = 1 (failure)
+  6. GoldSim detects failure and stops simulation
+  7. User checks log file for detailed error information
+
+- **Process Architecture:** Solution accounts for 32-bit GoldSim / 64-bit DLL separate process requirement
+  * Memory pointers cannot be shared across process boundaries
+  * Error messages written to log file instead of passed via pointers
+  * This is the correct approach for the 32-bit/64-bit architecture
+
+### Comparison: Error Handling Approaches
+
+| Approach | Function | Simulation | GoldSim Message | Details Location |
+|----------|----------|------------|-----------------|------------------|
+| **Graceful Degradation** | `gspy.log()` only | Continues | None | Log file |
+| **Fatal Error** | `gspy.error()` | **Stops** | "Return code 1" | Log file |
+
+### Migration Guide
+- **No breaking changes** - Existing code continues to work unchanged
+- **Optional enhancement** - Add `gspy.error()` for critical error handling
+- **Recommended pattern:**
+  ```python
+  try:
+      result = calculate(args)
+      return (result,)
+  except ValueError as e:
+      # Recoverable - use graceful degradation
+      gspy.log(f"Warning: {e}", 1)
+      return (default_value,)
+  except Exception as e:
+      # Critical - stop simulation
+      gspy.log(traceback.format_exc(), 0)
+      gspy.error(f"Fatal: {e}")
+      return (0.0,)
+  ```
+
 ## [1.8.7] - 2025-11-15
 
 ### Fixed