perf: release the Python GIL around heavy TTTR/CLSM/Correlator calls

Add a reusable, exception-safe TTTRLIB_NOGIL SWIG macro (RAII
tttrlib_gil_release guard wrapping $action, preserving the project's
std::exception -> Python translation) and apply it to the heavy,
Python-object-free entry points:

  - TTTR file loading: read_file, read_records, read_hdf_file,
    read_sm_file, and the reading constructors
  - CLSMImage::fill and the filling constructor
  - Correlator::run

These run with the GIL released so other Python threads progress while a
file loads or an image fills (both OpenMP-parallelized internally);
results are only returned once the operation completes. numpy typemaps
marshal under the GIL before/after $action, so only the pure C++ core
executes GIL-free. Pda::evaluate is deliberately excluded because its
director callback would re-enter Python without the GIL.

Author: tpeulen

ext/python/CLSM.i

@@ -49,6 +49,11 @@ static int myErr = 0; // flag to save error state
 
 %shared_ptr(CLSMImage)
 
+// Release the Python GIL around the (OpenMP-parallelized) image fill, which
+// touches no Python objects. Results are only returned once the fill completes.
+TTTRLIB_NOGIL(CLSMImage::fill)      // src/CLSMImage.cpp:1394
+TTTRLIB_NOGIL(CLSMImage::CLSMImage) // filling constructor calls fill() (src/CLSMImage.cpp:641)
+
 %include "CLSMPixel.h"
 %include "CLSMLine.h"
 %include "CLSMFrame.h"

ext/python/Correlator.i

@@ -26,6 +26,10 @@
 
 %include "CorrelatorPhotonStream.h"
 %include "CorrelatorCurve.h"
+// Release the Python GIL around the heavy correlation compute (internal C++
+// vectors only; no Python objects touched).
+TTTRLIB_NOGIL(Correlator::run)      // src/Correlator.cpp:84
+
 %include "Correlator.h"
 
 %extend Correlator{

ext/python/TTTR.i

@@ -41,6 +41,15 @@
 %apply (signed char * IN_ARRAY1, int DIM1) {(signed char *routing_channels, int n_routing_channels)} 
 %apply (signed char * IN_ARRAY1, int DIM1) {(signed char *event_types, int n_event_types)} 
 
+// Release the Python GIL around heavy, Python-object-free file I/O so other
+// threads can run while a file is loaded. numpy typemaps marshal under the GIL
+// before/after $action; only the C++ read executes GIL-free.
+TTTRLIB_NOGIL(TTTR::read_file)      // src/TTTR.cpp:494 — pure C file I/O
+TTTRLIB_NOGIL(TTTR::read_records)   // all overloads, src/TTTR.cpp:796+
+TTTRLIB_NOGIL(TTTR::read_hdf_file)  // src/TTTR.cpp:282
+TTTRLIB_NOGIL(TTTR::read_sm_file)   // src/TTTR.cpp:392
+TTTRLIB_NOGIL(TTTR::TTTR)           // reading constructors call read_file()
+
 %include "TTTR.h" 
 
 %extend TTTR{%pythoncode "./ext/python/TTTR.py"}

ext/python/tttrlib.i

@@ -25,6 +25,36 @@ from __future__ import annotations
 #include <assert.h>
 %}
 
+%{
+// RAII: release the Python GIL for the scope's lifetime and re-acquire it on
+// destruction — including during C++ exception unwinding, so the catch handlers
+// in TTTRLIB_NOGIL (which call the Python C-API via SWIG_exception) run with the
+// GIL held.
+struct tttrlib_gil_release {
+    PyThreadState *_save;
+    tttrlib_gil_release()  { _save = PyEval_SaveThread(); }
+    ~tttrlib_gil_release() { PyEval_RestoreThread(_save); }
+};
+%}
+
+// Release the GIL around a heavy, Python-object-free method while preserving the
+// project's standard std::exception -> Python exception translation (see the
+// global %exception in MicrotimeLinearization.i). Apply before the header %include.
+%define TTTRLIB_NOGIL(Method)
+%exception Method {
+    try {
+        tttrlib_gil_release _gil_guard;
+        $action
+    } catch (const std::invalid_argument& e) {
+        SWIG_exception(SWIG_ValueError, e.what());
+    } catch (const std::exception& e) {
+        SWIG_exception(SWIG_RuntimeError, e.what());
+    } catch (...) {
+        SWIG_exception(SWIG_UnknownError, "Unknown exception");
+    }
+}
+%enddef
+
 // Keep SWIG output quiet by default (runtime verbosity is controlled via TTTRLIB_VERBOSE).
 // Warning 302: Identifier redefined (ignored) (Renamed from 'pair< std::shared_ptr< TTTR >,std::shared_ptr< TTTR > >'),
 // Warning 389: operator[] ignored (consider using %extend)