neuronapi: add nrn_object_ptr_push for writable objref arguments (#3823)

* neuronapi: add nrn_object_ref_push for writable objref arguments

* address review: rename nrn_object_ref_push -> nrn_object_ptr_push

Per McDougal's #3823 review: in this API 'ref' means reference counting
(nrn_object_ref/unref); a function that pushes a pointer is named 'ptr'
(cf. nrn_double_ptr_push). Renames the function and its test, and notes on
nrn_object_push that assigning to a non-objref arg is a HOC error.

* neuronapi: reword 'cell' to 'slot' in nrn_object_ptr_push docs

Per review: 'cell' collides with its NEURON meaning (a neuron). Use
'slot' for the Object* storage location in the docs and the matching
source comment.

Author: ec1dev

docs/capi.rst

@@ -924,7 +924,42 @@ Functions, objects, and the stack
 
     **Usage Pattern:**
 
-    Used when passing objects as arguments to functions or methods.
+    Used when passing objects as arguments to functions or methods. The callee
+    receives the object by value; if the callee's argument was not declared as
+    an ``objref`` and it tries to assign to it (``$oN = ...``), HOC raises an
+    error. To pass an object reference a callee can assign back into, use
+    :c:func:`nrn_object_ptr_push`.
+
+.. c:function:: void nrn_object_ptr_push(Object** obj_ref)
+
+    Push a writable object-reference slot onto the stack.
+
+    :param obj_ref: Address of the caller's ``Object*`` slot.
+
+    Unlike :c:func:`nrn_object_push`, which pushes an object by value, this
+    pushes the *slot* holding the object. When the callee assigns to the
+    matching ``$oN`` argument, the assignment writes back through the slot and
+    updates ``*obj_ref`` in place. This is the out-parameter form used by the
+    ``h.ref(obj)`` idiom, where a function returns a value by storing it in a
+    caller-supplied object reference. ("ptr", as in :c:func:`nrn_double_ptr_push`,
+    is the pushed-pointer naming; the "ref" in :c:func:`nrn_object_ref` is
+    reference counting.)
+
+    **Usage Pattern:**
+
+    .. code-block:: c
+
+        // proc setit() { $o1 = new Vector(3) }
+        Object* slot = nullptr;
+        nrn_object_ptr_push(&slot);
+        nrn_function_call(nrn_symbol("setit"), 1);
+        // slot now points to the newly created Vector; unref when done.
+        nrn_object_unref(slot);
+
+    .. seealso::
+
+        :c:func:`nrn_object_push`,
+        :c:func:`nrn_object_unref`
 
 .. c:function:: Object* nrn_object_pop(void)
 

src/nrniv/neuronapi.cpp

@@ -377,6 +377,17 @@ void nrn_object_push(Object* obj) {
     hoc_push_object(obj);
 }
 
+void nrn_object_ptr_push(Object** obj_ref) {
+    // Push a writable object-reference slot (the out-parameter form of
+    // nrn_object_push). When a callee assigns to the corresponding $oN arg,
+    // hoc assigns through this slot, updating *obj_ref in place. Unlike
+    // nrn_object_push, which pushes an object by value, this exposes the
+    // h.ref(obj) idiom (a callee that writes back into the caller's objref).
+    // Named for the pointer it pushes (cf. nrn_double_ptr_push); the "ref" in
+    // nrn_object_ref/unref is reference counting, a different concept.
+    hoc_pushobj(obj_ref);
+}
+
 Object* nrn_object_pop(void) {
     // NOTE: the returned object should be unref'd when no longer needed
     Object** obptr = hoc_objpop();

src/nrniv/neuronapi.h

@@ -95,6 +95,7 @@ char** nrn_str_pop(void);
 void nrn_int_push(int i);
 int nrn_int_pop(void);
 void nrn_object_push(Object* obj);
+void nrn_object_ptr_push(Object** obj_ref);
 Object* nrn_object_pop(void);
 nrn_stack_types_t nrn_stack_type(void);
 char const* nrn_stack_type_name(nrn_stack_types_t id);

test/api/CMakeLists.txt

@@ -6,6 +6,7 @@ foreach(
   node_index.cpp
   object_new_nothrow.cpp
   object_new_wrap.cpp
+  object_ptr_push.cpp
   segment_diam.cpp
   sections.cpp
   symbol_object_string.cpp

test/api/object_ptr_push.cpp

@@ -0,0 +1,49 @@
+// NOTE: this assumes neuronapi.h is on your CPLUS_INCLUDE_PATH
+// Exercises nrn_object_ptr_push, which pushes a writable object-reference cell
+// (an Object**) rather than an object by value. This is the out-parameter form
+// behind the h.ref(obj) idiom: a callee that assigns to its $oN arg writes back
+// through the cell. nrn_object_push (by value) cannot express this.
+#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_ptr_push", "-nogui", "-nopython", nullptr};
+    nrn_init(3, argv.data());
+
+    bool ok = true;
+
+    // A proc whose sole job is to write a fresh Vector back into its objref arg.
+    nrn_hoc_call("proc make3() { $o1 = new Vector(3) }");
+    // And one that reads the passed object's size into the built-in hoc_ac_.
+    nrn_hoc_call("proc readsize() { hoc_ac_ = $o1.size() }");
+
+    // Write-back: push the address of an empty cell, call make3, and confirm the
+    // cell was populated. A by-value push could not update `slot` here.
+    Object* slot = nullptr;
+    nrn_object_ptr_push(&slot);
+    nrn_function_call(nrn_symbol("make3"), 1);
+    ok &= check(slot != nullptr, "objref cell was written back by the callee");
+    ok &= check(nrn_vector_capacity(slot) == 3, "written-back Vector has capacity 3");
+
+    // Read direction: push the now-populated cell and have HOC read $o1.size().
+    nrn_object_ptr_push(&slot);
+    nrn_function_call(nrn_symbol("readsize"), 1);
+    double* ac = nrn_symbol_dataptr(nrn_symbol("hoc_ac_"));
+    ok &= check(ac != nullptr && *ac == 3.0, "HOC read the pushed object's size through the cell");
+
+    nrn_object_unref(slot);
+    return ok ? 0 : 1;
+}