replaced invalidQuESTInputError with setInputErrorHandler

The benefits include:
- better portability between compilers; no macro guards!
- better symmetry with existing debug API (mostly setters)
- enables runtime re-routing of errors (so it can be unit tested!)
- resolves problem when multiple translation units both define the previous weak-symbol function (like when deprecated tests are compiled alongside v4 tests)
- more standard!

Author: TysonRayJones

examples/CMakeLists.txt

@@ -5,4 +5,5 @@ add_subdirectory(matrices)
 add_subdirectory(numbers)
 add_subdirectory(paulis)
 add_subdirectory(reporters)
-add_subdirectory(superoperators)
+add_subdirectory(superoperators)
+add_subdirectory(debug)

examples/debug/CMakeLists.txt

@@ -0,0 +1,41 @@
+# @author Tyson Jones (by duplicating files from...)
+# @author Oliver Brown
+# @author Erich Essmann
+
+
+# C example
+
+add_executable(debug_c_errorhandling
+  errorhandling.c
+)
+
+target_link_libraries(debug_c_errorhandling PUBLIC QuEST)
+
+install(TARGETS debug_c_errorhandling
+  RUNTIME
+  DESTINATION ${CMAKE_INSTALL_BINDIR}/examples/debug
+)
+set_target_properties(debug_c_errorhandling 
+  PROPERTIES 
+    INSTALL_RPATH "${CMAKE_INSTALL_FULL_LIBDIR}"
+    OUTPUT_NAME "c_errorhandling"
+)
+
+
+# C++ example
+
+add_executable(debug_cpp_errorhandling
+  errorhandling.cpp
+)
+
+target_link_libraries(debug_cpp_errorhandling PUBLIC QuEST)
+
+install(TARGETS debug_cpp_errorhandling
+  RUNTIME
+  DESTINATION ${CMAKE_INSTALL_BINDIR}/examples/debug
+)
+set_target_properties(debug_cpp_errorhandling 
+  PROPERTIES 
+    INSTALL_RPATH "${CMAKE_INSTALL_FULL_LIBDIR}"
+    OUTPUT_NAME "cpp_errorhandling"
+)

examples/debug/errorhandling.c

@@ -0,0 +1,27 @@
+/** @file
+ * Examples of setting the invalid error input handler in C11,
+ * overriding the default behaviour of immediately exiting.
+ * 
+ * @author Tyson Jones
+*/
+
+#include "quest.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+
+void myErrorHandler(const char* errFunc, const char* errMsg) {
+    printf("Ruh-roh, Raggy! Function '%s' has reported '%s'.\n", errFunc, errMsg);
+    printf("We will now be very good children and exit immediately!\n");
+    exit(0);
+}
+
+
+int main() {
+    initQuESTEnv();
+    setInputErrorHandler(myErrorHandler);
+
+    Qureg qureg = createQureg(-123);
+
+    finalizeQuESTEnv();
+}

examples/debug/errorhandling.cpp

@@ -0,0 +1,68 @@
+/** @file
+ * Examples of setting the invalid error input handler in C++14,
+ * overriding the default behaviour of immediately exiting.
+ * 
+ * @author Tyson Jones
+*/
+
+#include "quest.h"
+#include <iostream>
+#include <stdexcept>
+#include <stdlib.h>
+
+
+void myErrorHandlerA(const char* errFunc, const char* errMsg) {
+
+    std::string func(errFunc);
+    std::string msg(errMsg);
+
+    std::cout 
+        << "an error?? in the '" << errFunc << "' function?? with message '" << msg << "'! "
+        << "how queer!! ive never seen such a thing - i must throw an exception post-haste!!!"
+        << std::endl
+        << std::endl;
+
+    // exception forces control-flow out of QuEST env, safely back to user.
+    // without this, control-flow would return to the QuEST backend and likely
+    // cause internal integrity checks to fail, or segmentation faults
+    throw std::runtime_error(std::string(errFunc) + ": " + std::string(errMsg));
+}
+
+
+void myErrorHandlerB(const char* errFunc, const char* errMsg) {
+
+    std::string func(errFunc);
+    std::string msg(errMsg);
+
+    std::cout 
+        << "Function '" << func << "' threw '" << msg << "'." 
+        << std::endl
+        << "We will now exit completely. Good day!" 
+        << std::endl
+        << std::endl;
+
+    exit(0);
+}
+
+
+int main() {
+    initQuESTEnv();
+
+    setInputErrorHandler(myErrorHandlerA);
+
+    try {
+        Qureg qureg = createQureg(-123);
+    } catch (std::runtime_error& e) {
+        std::cout 
+            << "Error caught! Function aborted, but execution continues." 
+            << std::endl
+            << std::endl;
+    }
+
+    setInputErrorHandler(myErrorHandlerB);
+    initQuESTEnv(); // illegal to recall
+    
+    std::cout << "this will never be reached, because myErrorHandlerB exits!" << std::endl;
+
+    finalizeQuESTEnv();
+}

quest/include/debug.h

@@ -44,7 +44,7 @@ int getNumSeeds();
  */
 
 /// @notdoced
-void invalidQuESTInputError(const char* msg, const char* func);
+void setInputErrorHandler(void (*callback)(const char* func, const char* msg));
 
 /// @notdoced
 void setValidationOn();

quest/src/api/debug.cpp

@@ -64,6 +64,11 @@ void getSeeds(unsigned* seeds) {
  * VALIDATION
  */
 
+void setInputErrorHandler(void (*callback)(const char*, const char*)) {
+    validate_envIsInit(__func__);
+
+    validateconfig_setErrorHandler(callback);
+}
 
 void setValidationOn() {
     validate_envIsInit(__func__);

quest/src/core/validation.cpp

@@ -1044,9 +1044,8 @@ namespace report {
 /*
  * INVALID INPUT RESPONSE BEHAVIOUR
  */
-extern "C" {
-// default C/C++ compatible error response is to simply exit in fail state
-void default_invalidQuESTInputError(const char* msg, const char* func) {
+
+void default_inputErrorHandler(const char* func, const char* msg) {
 
     // safe to call even before MPI has been setup, and ignores user-set trailing newlines
     print(string("")
@@ -1062,26 +1061,16 @@ void default_invalidQuESTInputError(const char* msg, const char* func) {
     if (comm_isInit())
         comm_end();
 
+    // simply exit, interrupting any other process (potentially leaking)
     exit(EXIT_FAILURE);
 }
 
-// enable default error response to be user-overriden as a weak symbol (even in C, and on Windows)
-
-    // Always declare invalidQuESTInputError so the compiler sees it:
-    void invalidQuESTInputError(const char* msg, const char* func);
+void (*global_inputErrorHandler)(const char*, const char*) = default_inputErrorHandler;
 
-    #ifndef _WIN32
-        #pragma weak invalidQuESTInputError
-        void invalidQuESTInputError(const char* msg, const char* func) {
-            default_invalidQuESTInputError(msg, func);
-        }
-    #elif defined(_WIN64)
-        #pragma comment(linker, "/alternatename:invalidQuESTInputError=default_invalidQuESTInputError")   
-    #else
-        #pragma comment(linker, "/alternatename:_invalidQuESTInputError=_default_invalidQuESTInputError")
-    #endif
+void validateconfig_setErrorHandler(void (*callback)(const char*, const char*)) {
 
-} // end C++ de-mangler
+    global_inputErrorHandler = callback;
+}
 
 
 
@@ -1217,8 +1206,9 @@ void assertThat(bool valid, string msg, const char* func) {
     // uniform between nodes (assuming user's do not hack in rank-specific
     // arguments to the API!)
 
+    // invoke the potentially user-overriden error function
     if (!valid)
-        invalidQuESTInputError(msg.c_str(), func);
+        global_inputErrorHandler(func, msg.c_str());
 }
 void assertThat(bool valid, string msg, tokenSubs vars, const char* func) {
 

quest/src/core/validation.hpp

@@ -31,6 +31,14 @@ const int validate_STRUCT_PROPERTY_UNKNOWN_FLAG = -1;
 
 
 
+/*
+ * VALIDATION ERROR HANDLER
+ */
+
+void validateconfig_setErrorHandler(void (*callback)(const char* func, const char* msg));
+
+
+
 /*
  * VALIDATION TOGGLE
  */

tests/deprecated/test_main.cpp

@@ -27,15 +27,16 @@
 #include <stdexcept>
 
 
-/* Redefinition of QuEST_validation's invalidQuESTInputError function, called when a 
- * user passes an incorrect parameter (e.g. a negative qubit index). This is 
- * redefined here to, in lieu of printing and exiting, throw a C++ exception
- * which can be caught (and hence unit tested for) by Catch2
+
+/*
+ * recast QuEST errors into exceptions which Catch2 can intercept
  */
- extern "C" void invalidQuESTInputError(const char* errMsg, const char* errFunc) {
-  
-    throw std::runtime_error(errMsg);
- }
+
+/// @private 
+extern "C" void validationErrorHandler(const char* errFunc, const char* errMsg) {
+
+  throw std::runtime_error(std::string(errFunc) + ": " + std::string(errMsg));
+}
 
 
 /** Explicit declaration of main to create (destroy) the QuESTEnv before (after)
@@ -44,6 +45,7 @@
 int main(int argc, char* argv[]) {
 
   initQuESTEnv();
+  setInputErrorHandler(validationErrorHandler);
   setRandomTestStateSeeds();
 
   int result = Catch::Session().run( argc, argv );

tests/main.cpp

@@ -56,11 +56,11 @@
 
 
 /*
- * recast QuEST errors into exceptions which Catch can intercept
+ * recast QuEST errors into exceptions which Catch2 can intercept
  */
 
 /// @private 
-extern "C" void invalidQuESTInputError(const char* errMsg, const char* errFunc) {
+extern "C" void validationErrorHandler(const char* errFunc, const char* errMsg) {
 
     throw std::runtime_error(std::string(errFunc) + ": " + std::string(errMsg));
 }
@@ -117,6 +117,7 @@ int main(int argc, char* argv[]) {
     // prepare QuEST before anything else, since many
     // testing utility functions repurpose QuEST ones
     initQuESTEnv();
+    setInputErrorHandler(validationErrorHandler);
 
     // ensure RNG consensus among all nodes
     setRandomTestStateSeeds();