neuronapi: add nrn_object_new_nothrow for error-reporting construction (#3831)

nrn_object_new calls hoc_newobj1, which throws a C++ exception on a
constructor error (bad arguments, a failing INITIAL, ...). That is unsafe
for a non-C++ caller (ctypes, MATLAB) where the exception would cross the
FFI boundary. nrn_object_new_nothrow catches the error and reports it via a
return code + error buffer, the constructor counterpart of
nrn_function_call_nothrow / nrn_method_call_nothrow. Construction runs under
a new OcJump::newobj_throw_on_exception helper that restores the interpreter
stack on failure, mirroring execute_throw_on_exception.

Author: ec1dev

docs/capi.rst

@@ -973,6 +973,29 @@ Functions, objects, and the stack
         :c:func:`nrn_object_new`,
         :c:func:`nrn_object_ref`
 
+.. c:function:: int nrn_object_new_nothrow(Symbol* sym, int narg, Object** result, char* error_msg, size_t error_msg_size)
+
+    Create a new object, reporting a constructor error instead of throwing.
+
+    :param sym: Symbol representing the object class/type.
+    :param narg: Number of constructor arguments on the stack.
+    :param result: Set to the new object on success, or ``NULL`` on error.
+    :param error_msg: Buffer filled with a message on error (may be ``NULL``).
+    :param error_msg_size: Size of ``error_msg``.
+    :returns: 0 on success, nonzero if the HOC constructor errored.
+
+    Like :c:func:`nrn_object_new`, but a constructor error (bad arguments, a
+    failing ``INITIAL``, etc.) is caught and reported rather than thrown as a
+    C++ exception, so a non-C++ caller (ctypes, MATLAB, ...) does not have an
+    exception cross the call boundary. This is the constructor counterpart of
+    :c:func:`nrn_function_call_nothrow` and :c:func:`nrn_method_call_nothrow`.
+    The interpreter stack is restored if construction fails.
+
+    .. seealso::
+
+        :c:func:`nrn_object_new`,
+        :c:func:`nrn_function_call_nothrow`
+
 .. c:function:: Symbol* nrn_method_symbol(const Object* obj, const char* name)
 
     Get a method symbol from an object by name.

src/nrniv/neuronapi.cpp

@@ -394,6 +394,43 @@ Object* nrn_object_new_wrap(Symbol* sym, void* cpp_object) {
     return hoc_new_object(sym, cpp_object);
 }
 
+int nrn_object_new_nothrow(Symbol* sym,
+                           int narg,
+                           Object** result,
+                           char* error_msg,
+                           size_t error_msg_size) {
+    // Like nrn_object_new, but a HOC constructor error (bad arguments, a failing
+    // INITIAL, etc.) is caught and reported instead of thrown, so a non-C++
+    // caller (ctypes, MATLAB, ...) does not have a C++ exception propagate
+    // across the FFI boundary. On success returns 0 with *result set; on error
+    // returns nonzero with *result NULL and error_msg populated.
+    if (error_msg && error_msg_size > 0) {
+        error_msg[0] = '\0';
+    }
+    if (result) {
+        *result = nullptr;
+    }
+    try {
+        Object* obj = OcJump::newobj_throw_on_exception(sym, narg);
+        if (result) {
+            *result = obj;
+        }
+        return 0;
+    } catch (const std::exception& e) {
+        if (error_msg && error_msg_size > 0) {
+            strncpy(error_msg, e.what(), error_msg_size - 1);
+            error_msg[error_msg_size - 1] = '\0';
+        }
+        return 1;
+    } catch (...) {
+        if (error_msg && error_msg_size > 0) {
+            strncpy(error_msg, "Unknown exception occurred", error_msg_size - 1);
+            error_msg[error_msg_size - 1] = '\0';
+        }
+        return 1;
+    }
+}
+
 Symbol* nrn_method_symbol(const Object* obj, char const* const name) {
     return hoc_table_lookup(name, obj->ctemplate->symtable);
 }

src/nrniv/neuronapi.h

@@ -96,6 +96,11 @@ nrn_stack_types_t nrn_stack_type(void);
 char const* nrn_stack_type_name(nrn_stack_types_t id);
 Object* nrn_object_new(Symbol* sym, int narg);
 Object* nrn_object_new_wrap(Symbol* sym, void* cpp_object);
+int nrn_object_new_nothrow(Symbol* sym,
+                           int narg,
+                           Object** result,
+                           char* error_msg,
+                           size_t error_msg_size);
 Symbol* nrn_method_symbol(const Object* obj, const char* name);
 // TODO: the next two functions throw exceptions in C++; need a version that
 //       returns a bool success indicator instead (this is actually the

src/nrniv/ocjump.cpp

@@ -154,6 +154,22 @@ void OcJump::execute_throw_on_exception(Symbol* sym, int narg) {
     }
 }
 
+extern Object* hoc_newobj1(Symbol*, int);
+
+Object* OcJump::newobj_throw_on_exception(Symbol* sym, int narg) {
+    // Construct an object, restoring interpreter state (including the stack) if
+    // the HOC constructor errors, so a caller can catch the exception without
+    // leaving the stack dirty. Same pattern as execute_throw_on_exception.
+    saved_state before{};
+    try_catch_depth_increment tell_children_we_will_catch{};
+    try {
+        return hoc_newobj1(sym, narg);
+    } catch (...) {
+        before.restore();
+        throw;
+    }
+}
+
 void* OcJump::fpycall(void* (*f)(void*, void*), void* a, void* b) {
     saved_state before{};
     try_catch_depth_increment tell_children_we_will_catch{};

src/nrniv/ocjump.h

@@ -43,4 +43,5 @@ struct OcJump {
     static void* fpycall(void* (*) (void*, void*), void*, void*);
     static void execute_throw_on_exception(Symbol* sym, int narg);
     static void execute_throw_on_exception(Object* obj, Symbol* sym, int narg);
+    static Object* newobj_throw_on_exception(Symbol* sym, int narg);
 };

test/api/CMakeLists.txt

@@ -4,6 +4,7 @@ foreach(
   hh_sim.cpp
   netcon.cpp
   node_index.cpp
+  object_new_nothrow.cpp
   object_new_wrap.cpp
   segment_diam.cpp
   sections.cpp

test/api/object_new_nothrow.cpp

@@ -0,0 +1,60 @@
+// NOTE: this assumes neuronapi.h is on your CPLUS_INCLUDE_PATH
+// Exercises nrn_object_new_nothrow, which constructs an object like
+// nrn_object_new but reports a HOC constructor error through a return code and
+// error buffer instead of letting a C++ exception cross the call boundary.
+#include <array>
+#include <iostream>
+#include "neuronapi.h"
+
+using std::cerr;
+using std::endl;
+
+extern "C" void modl_reg(){/* No modl_reg */};
+
+static bool check(bool cond, const char* msg) {
+    if (!cond) {
+        cerr << "FAIL: " << msg << endl;
+    }
+    return cond;
+}
+
+int main(void) {
+    static std::array<const char*, 4> argv = {"object_new_nothrow", "-nogui", "-nopython", nullptr};
+    nrn_init(3, argv.data());
+
+    bool ok = true;
+    char err[256];
+
+    // Success path: a Vector(3) constructs, returns 0, and fills *result.
+    Object* v = nullptr;
+    nrn_double_push(3);
+    int rc = nrn_object_new_nothrow(nrn_symbol("Vector"), 1, &v, err, sizeof(err));
+    ok &= check(rc == 0, "successful construction returns 0");
+    ok &= check(v != nullptr, "successful construction sets *result");
+    ok &= check(v != nullptr && nrn_vector_capacity(v) == 3, "constructed the requested Vector(3)");
+    ok &= check(err[0] == '\0', "error buffer stays empty on success");
+
+    // Failure path: a template whose init calls execerror. nrn_object_new would
+    // throw; nrn_object_new_nothrow must catch it.
+    nrn_hoc_call("begintemplate Boom\nproc init() { execerror(\"boom\", \"\") }\nendtemplate Boom");
+    Object* b = reinterpret_cast<Object*>(0x1);  // sentinel; must be nulled
+    rc = nrn_object_new_nothrow(nrn_symbol("Boom"), 0, &b, err, sizeof(err));
+    ok &= check(rc != 0, "a failing constructor returns nonzero");
+    ok &= check(b == nullptr, "*result is NULL after a failed construction");
+    ok &= check(err[0] != '\0', "error buffer is populated on failure");
+
+    // A failed construction must not corrupt the stack: a value pushed after it
+    // pops back cleanly.
+    nrn_double_push(42.0);
+    ok &= check(nrn_double_pop() == 42.0, "stack is intact after a failed construction");
+
+    // A NULL error buffer is tolerated on both paths.
+    Object* v2 = nullptr;
+    rc = nrn_object_new_nothrow(nrn_symbol("Vector"), 0, &v2, nullptr, 0);
+    ok &= check(rc == 0 && v2 != nullptr, "NULL error buffer tolerated on success");
+    Object* b2 = nullptr;
+    rc = nrn_object_new_nothrow(nrn_symbol("Boom"), 0, &b2, nullptr, 0);
+    ok &= check(rc != 0 && b2 == nullptr, "NULL error buffer tolerated on failure");
+
+    return ok ? 0 : 1;
+}