feat: universal set() and field-change callback refinements

Universal set() — PR 2:
- trigger() falls back to scanOnce() when SCAN != 'I/O Intr', so
  set() publishes immediately regardless of what the SCAN field shows.
  scanIoRequest return value is now checked; scanOnce fires only when
  scanIoRequest did not queue the record (never both on the same cycle).
- iocInit() accepts auto_reset_scan=True: after forwarding a SCAN write
  to Python, the C hook resets SCAN to 'I/O Intr' so the record stays
  on the I/O Intr scan list — eliminating periodic-scan contention.

Callback refinements — building on PR 1:
- on_field_change() now accepts a list of field names (multi-field
  subscription with one callback).
- log_puts=False added to iocInit() to suppress the built-in CA put
  logger without disabling field-change callbacks.
- remove_field_callback(field, cb) de-registers one callback.
- clear_field_callbacks(field=None) removes all callbacks for a field
  or all callbacks on the record.
- record.field_callbacks  read-only dict view of registered callbacks.
- C double-registration guard added: FieldWriteHook can only be
  installed once even if iocInit() is called multiple times.

Tests: 25 dedicated tests (test_universal_set.py 16, test_callback_refinements.py 9).
Full suite at this point: 363 passed, 16 skipped, 0 failures.

Author: BoredDadDev

softioc/device_core.py

@@ -170,8 +170,10 @@ def on_field_change(self, field, callback):
 
         Args:
             field: EPICS field name (e.g. ``"SCAN"``, ``"VAL"``,
-                ``"DISA"``).  Use ``"*"`` to receive notifications for
-                **every** field write on this record.
+                ``"DISA"``), a list of field names
+                (e.g. ``["SCAN", "DRVH", "DRVL"]``), or ``"*"`` to
+                receive notifications for **every** field write on this
+                record.
             callback: ``callback(record_name, field_name, value_string)``
                 called after each matching write.  *value_string* is the
                 new value formatted by EPICS as a ``DBR_STRING``.
@@ -186,6 +188,10 @@ def on_field_change(self, field, callback):
             and internal ``record.set()`` calls bypass asTrapWrite and
             will **not** trigger callbacks.
         '''
+        if isinstance(field, (list, tuple)):
+            for f in field:
+                self.on_field_change(f, callback)
+            return
         field = field.upper() if field != "*" else "*"
         self.__field_callbacks.setdefault(field, []).append(callback)
 
@@ -200,6 +206,48 @@ def field_callbacks(self):
         '''
         return {k: list(v) for k, v in self.__field_callbacks.items()}
 
+    def remove_field_callback(self, field, callback):
+        '''Remove a specific *callback* previously registered for *field*.
+
+        Args:
+            field: Field name (e.g. ``"SCAN"``) or ``"*"``.
+            callback: The exact callable that was passed to
+                :meth:`on_field_change`.
+
+        Raises:
+            ValueError: If *callback* is not registered for *field*.
+        '''
+        field = field.upper() if field != "*" else "*"
+        try:
+            self.__field_callbacks[field].remove(callback)
+        except (KeyError, ValueError):
+            raise ValueError(
+                f"Callback not registered for field {field!r}")
+        # Clean up empty lists to keep the dict tidy.
+        if not self.__field_callbacks[field]:
+            del self.__field_callbacks[field]
+
+    def clear_field_callbacks(self, field=None):
+        '''Remove all field-change callbacks, or all for a single *field*.
+
+        Args:
+            field: If ``None`` (default), remove **all** callbacks on
+                this record.  Otherwise, remove only those registered for
+                the given field name (or ``"*"``).
+
+        Raises:
+            KeyError: If *field* is given but has no registered callbacks.
+        '''
+        if field is None:
+            self.__field_callbacks.clear()
+        else:
+            field = field.upper() if field != "*" else "*"
+            try:
+                del self.__field_callbacks[field]
+            except KeyError:
+                raise KeyError(
+                    f"No callbacks registered for field {field!r}")
+
     def _get_field_callbacks(self, field):
         '''Return the list of callbacks for *field*, including wildcards.
 
@@ -234,9 +282,39 @@ def process_severity(self, record, severity, alarm):
             record.NSTA = alarm
 
     def trigger(self):
-        '''Call this to trigger processing for records with I/O Intr scan.'''
+        '''Trigger immediate record processing.
+
+        Uses scanIoRequest for I/O Intr records (fast path).
+        Falls back to scanOnce for records on any other SCAN setting.
+
+        Only one path fires per call: scanIoRequest returns non-zero
+        when the record is on the I/O Intr scan list, so scanOnce is
+        skipped.  When the record has been moved to a different scan
+        list scanIoRequest returns zero and scanOnce takes over.
+
+        Known limitation — periodic SCAN and double processing:
+
+        When SCAN is set to a periodic rate (e.g. "1 second"), the
+        EPICS scan thread calls dbProcess on its own schedule, and
+        set() also calls scanOnce → dbProcess.  The record is
+        processed by both paths.  dbScanLock serialises access and
+        recGblCheckDeadband prevents duplicate monitors when the
+        value has not changed, so this is harmless in practice but
+        does result in extra processing cycles.
+
+        To avoid this, use ``iocInit(auto_reset_scan=True)``.
+        The C hook resets SCAN back to I/O Intr after forwarding
+        the requested rate to the Python callback, so the record
+        stays on the I/O Intr scan list and scanIoRequest remains
+        the only processing path.  Passive writes are exempt from
+        the reset (they are a deliberate "stop updating" command).
+        '''
+        queued = False
         if self.__ioscanpvt:
-            imports.scanIoRequest(self.__ioscanpvt)
+            queued = imports.scanIoRequest(self.__ioscanpvt)
+        if not queued and hasattr(self, '_record') \
+                and self._record is not None:
+            imports.scan_once(self._record.record.value)
 
 
 

softioc/extension.c

@@ -6,6 +6,8 @@
 #define db_accessHFORdb_accessC     // Needed to get correct DBF_ values
 #include <dbAccess.h>
 #include <dbFldTypes.h>
+#include <dbScan.h>
+#include <menuScan.h>
 #include <callback.h>
 #include <dbStaticLib.h>
 #include <asTrapWrite.h>
@@ -269,15 +271,24 @@ void EpicsPvPutHook(struct asTrapWriteMessage *pmessage, int after)
 }
 
 
+/* Guard against double-registration of EpicsPvPutHook: asTrapWrite
+ * maintains a linked list of listeners, and registering the same function
+ * pointer twice would cause double printf output per write. */
+static int epics_pv_put_hook_installed = 0;
+
 static PyObject *install_pv_logging(PyObject *self, PyObject *args)
 {
     const char *acf_file;
+    int log_puts = 1;  /* default: register the printf hook (backward compat) */
 
-    if (!PyArg_ParseTuple(args, "s", &acf_file))
+    if (!PyArg_ParseTuple(args, "s|p", &acf_file, &log_puts))
         return NULL;
 
     asSetFilename(acf_file);
-    asTrapWriteRegisterListener(EpicsPvPutHook);
+    if (log_puts && !epics_pv_put_hook_installed) {
+        asTrapWriteRegisterListener(EpicsPvPutHook);
+        epics_pv_put_hook_installed = 1;
+    }
     Py_RETURN_NONE;
 }
 
@@ -297,6 +308,12 @@ static PyObject *install_pv_logging(PyObject *self, PyObject *args)
 /* Python callable: callback(channel_name: str, value_str: str) */
 static PyObject *py_field_write_callback = NULL;
 
+/* When non-zero, FieldWriteHook resets SCAN back to I/O Intr after
+ * forwarding the notification to Python — unless Passive was requested.
+ * This eliminates periodic-scan contention: SCAN acts as a latched
+ * command that Python reads and then the record returns to I/O Intr. */
+static int auto_reset_scan = 0;
+
 static void FieldWriteHook(struct asTrapWriteMessage *pmessage, int after)
 {
     if (!after || !py_field_write_callback || py_field_write_callback == Py_None)
@@ -325,12 +342,30 @@ static void FieldWriteHook(struct asTrapWriteMessage *pmessage, int after)
     if (PyErr_Occurred())
         PyErr_Print();
     PyGILState_Release(gstate);
+
+    /* Auto-reset SCAN to I/O Intr after forwarding the notification,
+     * unless the client set Passive (meaning "stop updating"). */
+    if (auto_reset_scan) {
+        const char *dot = strrchr(channel_name, '.');
+        if (dot && strcmp(dot + 1, "SCAN") == 0
+                && strcmp(value_str, "Passive") != 0) {
+            epicsEnum16 io_intr = menuScanI_O_Intr;
+            dbScanLock(pchan->addr.precord);
+            dbPut(&pchan->addr, DBR_ENUM, &io_intr, 1);
+            dbScanUnlock(pchan->addr.precord);
+        }
+    }
 }
 
+/* Guard against double-registration of FieldWriteHook — same rationale
+ * as epics_pv_put_hook_installed above. */
+static int field_write_hook_installed = 0;
+
 static PyObject *register_field_write_listener(PyObject *self, PyObject *args)
 {
     PyObject *callback;
-    if (!PyArg_ParseTuple(args, "O", &callback))
+    int reset_scan = 0;
+    if (!PyArg_ParseTuple(args, "O|p", &callback, &reset_scan))
         return NULL;
     if (!PyCallable_Check(callback)) {
         PyErr_SetString(PyExc_TypeError, "Argument must be callable");
@@ -339,7 +374,11 @@ static PyObject *register_field_write_listener(PyObject *self, PyObject *args)
     Py_XDECREF(py_field_write_callback);
     Py_INCREF(callback);
     py_field_write_callback = callback;
-    asTrapWriteRegisterListener(FieldWriteHook);
+    auto_reset_scan = reset_scan;
+    if (!field_write_hook_installed) {
+        asTrapWriteRegisterListener(FieldWriteHook);
+        field_write_hook_installed = 1;
+    }
     Py_RETURN_NONE;
 }
 
@@ -383,6 +422,26 @@ static PyObject *signal_processing_complete(PyObject *self, PyObject *args)
 }
 
 
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/* CLS extension: scanOnce wrapper.
+ *
+ * Queues immediate record processing via the EPICS Base scanOnce() API,
+ * which works regardless of the record's current SCAN setting.
+ */
+
+static PyObject *scan_once(PyObject *self, PyObject *args)
+{
+    Py_ssize_t record_ptr;
+    if (!PyArg_ParseTuple(args, "n", &record_ptr))
+        return NULL;
+    dbCommon *precord = (dbCommon *)record_ptr;
+    Py_BEGIN_ALLOW_THREADS
+    scanOnce(precord);
+    Py_END_ALLOW_THREADS
+    Py_RETURN_NONE;
+}
+
+
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 /* Initialisation. */
 
@@ -403,6 +462,8 @@ static struct PyMethodDef softioc_methods[] = {
      "Create a CALLBACK structure inside a PyCapsule"},
     {"register_field_write_listener",  register_field_write_listener, METH_VARARGS,
      "Register a Python callable for all CA/PVA field writes (CLS extension)"},
+    {"scan_once",  scan_once, METH_VARARGS,
+     "Queue immediate record processing via scanOnce() (CLS extension)"},
     {NULL, NULL, 0, NULL}        /* Sentinel */
 };
 

softioc/field_monitor.py

@@ -61,11 +61,17 @@ def _dispatch_field_write(channel_name, value_str):
             )
 
 
-def install_field_monitor():
+def install_field_monitor(auto_reset_scan=False):
     """Register :func:`_dispatch_field_write` with the C extension.
 
     Must be called **after** ``iocInit()`` and after the access-security
     file (containing the ``TRAPWRITE`` rule) has been loaded — both of
     which are handled automatically by :func:`softioc.iocInit`.
+
+    Args:
+        auto_reset_scan: If True, the C layer resets SCAN back to
+            "I/O Intr" after every non-Passive SCAN write, eliminating
+            periodic-scan contention.  Default False.
     """
-    imports.register_field_write_listener(_dispatch_field_write)
+    imports.register_field_write_listener(
+        _dispatch_field_write, auto_reset_scan=auto_reset_scan)

softioc/imports.py

@@ -30,15 +30,38 @@ def db_get_field(name, dbr_type, pbuffer, length):
     '''Get field where pbuffer is void* pointer. Returns None.'''
     return _extension.db_get_field(name, dbr_type, pbuffer, length)
 
-def install_pv_logging(acf_file):
-    '''Install pv logging'''
-    _extension.install_pv_logging(acf_file)
+def install_pv_logging(acf_file, log_puts=True):
+    '''Load access security file and optionally install caput printf logging.
 
-def register_field_write_listener(callback):
+    The ACF file must contain a TRAPWRITE rule for asTrapWrite listeners
+    (including CLS field-write callbacks) to fire.
+
+    Args:
+        acf_file: Path to the access security configuration file.
+        log_puts: If True (default), register the EpicsPvPutHook that
+            prints caput operations to stdout.  Set to False to load the
+            ACF without the printf overhead.
+    '''
+    _extension.install_pv_logging(acf_file, log_puts)
+
+def register_field_write_listener(callback, auto_reset_scan=False):
     '''CLS extension: register a Python callable for all CA/PVA field writes.
     callback(channel_name: str, value_str: str) is called after each write.
+
+    Args:
+        callback: Python callable receiving (channel_name, value_string).
+        auto_reset_scan: If True, the C layer resets SCAN back to
+            "I/O Intr" after every non-Passive SCAN write, eliminating
+            periodic-scan contention.  Default False.
+    '''
+    _extension.register_field_write_listener(callback, auto_reset_scan)
+
+def scan_once(record):
+    '''CLS extension: queue immediate record processing via scanOnce().
+    Works regardless of the record's current SCAN setting.
+    record is the integer address of the dbCommon pointer.
     '''
-    _extension.register_field_write_listener(callback)
+    _extension.scan_once(record)
 
 def create_callback_capsule():
     return _extension.create_callback_capsule()
@@ -89,7 +112,7 @@ def from_param(cls, value):
 
 scanIoRequest = dbCore.scanIoRequest
 scanIoRequest.argtypes = (IOSCANPVT,)
-scanIoRequest.restype = None
+scanIoRequest.restype = c_uint
 
 dbLoadDatabase = dbCore.dbLoadDatabase
 dbLoadDatabase.argtypes = (auto_encode, auto_encode, auto_encode)

softioc/softioc.py

@@ -21,7 +21,8 @@ def epicsAtPyExit():
     imports.epicsExitCallAtExits()
 
 
-def iocInit(dispatcher=None, enable_pva=True):
+def iocInit(dispatcher=None, enable_pva=True, log_puts=True,
+            auto_reset_scan=False):
     '''This must be called exactly once after loading all EPICS database files.
     After this point the EPICS IOC is running and serving PVs.
 
@@ -30,6 +31,13 @@ def iocInit(dispatcher=None, enable_pva=True):
             be called in response to caput on a record. If not supplied uses
             ``cothread`` as the dispatcher.
         enable_pva: Specify whether to enable the PV Access Server in this IOC.
+        log_puts: If True (default), register the caput printf logger that
+            prints every CA/PVA put to stdout.  Set to False to disable the
+            printf output while still loading the access-security file needed
+            for field-change callbacks.
+        auto_reset_scan: If True, the C layer resets SCAN back to "I/O Intr"
+            after every non-Passive SCAN write, making SCAN a latched command.
+            Default False.
 
     See Also:
         `softioc.asyncio_dispatcher` is a dispatcher for `asyncio` applications
@@ -47,19 +55,21 @@ def iocInit(dispatcher=None, enable_pva=True):
         imports.registerRecordDeviceDriver(pdbbase)
 
     # CLS extension: ensure access security is configured before iocInit.
-    # Importing pvlog triggers asSetFilename(access.acf) and registers
-    # the original caput print-logging hook — we preserve that behavior.
     # The TRAPWRITE rule in access.acf is required for asTrapWrite
     # listeners (including our field-write callbacks) to fire.
-    from . import pvlog  # noqa: F401  — side-effect import sets ACF
+    # The log_puts flag controls whether the printf caput logger is
+    # registered — defaults to True for backward compatibility.
+    _acf_file = os.path.join(
+        os.path.dirname(__file__), 'access.acf')
+    imports.install_pv_logging(_acf_file, log_puts=log_puts)
 
     imports.iocInit()
     autosave.start_autosave_thread()
 
     # CLS extension: register the Python-level field-write dispatcher now
     # that the IOC is running and access security is active.
     from .field_monitor import install_field_monitor
-    install_field_monitor()
+    install_field_monitor(auto_reset_scan=auto_reset_scan)
 
 
 def safeEpicsExit(code=0):