Add safe GIL helpers and per-interpreter event loop storage

- Add gil_acquire()/gil_release() helpers that check PyGILState_Check()
  before calling PyGILState_Ensure() to avoid double-acquisition
- Add per-interpreter event loop storage using PyCapsule in module attr
- Store event loop in both global C var and Python module for fast
  access and sub-interpreter support
- Use safe GIL helpers in nif_set_python_event_loop()

Author: benoitc

c_src/py_event_loop.c

@@ -62,11 +62,117 @@ ERL_NIF_TERM ATOM_CANCEL_TIMER;
 ERL_NIF_TERM ATOM_EVENT_LOOP;
 ERL_NIF_TERM ATOM_DISPATCH;
 
+/* ============================================================================
+ * Per-Interpreter Event Loop Storage
+ * ============================================================================
+ *
+ * Event loop references are stored as module attributes in py_event_loop,
+ * using PyCapsule for safe C pointer storage. This approach:
+ *
+ * - Works uniformly for main interpreter and sub-interpreters
+ * - Each interpreter has its own py_event_loop module with its own attribute
+ * - Thread-safe for free-threading (Python 3.13+)
+ * - Uses gil_acquire()/gil_release() for safe GIL management
+ *
+ * Flow:
+ *   NIF set_python_event_loop() -> stores capsule in py_event_loop._loop
+ *   Python _is_initialized() -> checks if _loop attribute exists and is valid
+ *   Python operations -> retrieve loop from py_event_loop._loop
+ */
+
+/** @brief Name for the PyCapsule storing event loop pointer */
+static const char *EVENT_LOOP_CAPSULE_NAME = "erlang_python.event_loop";
+
+/** @brief Module attribute name for storing the event loop */
+static const char *EVENT_LOOP_ATTR_NAME = "_loop";
+
+/**
+ * Get the py_event_loop module for the current interpreter.
+ * MUST be called with GIL held.
+ * Returns borrowed reference.
+ */
+static PyObject *get_event_loop_module(void) {
+    PyObject *modules = PyImport_GetModuleDict();
+    if (modules == NULL) {
+        return NULL;
+    }
+    return PyDict_GetItemString(modules, "py_event_loop");
+}
+
+/**
+ * Get the event loop for the current Python interpreter.
+ * MUST be called with GIL held.
+ * Retrieves from py_event_loop._loop module attribute.
+ *
+ * @return Event loop pointer or NULL if not set
+ */
+static erlang_event_loop_t *get_interpreter_event_loop(void) {
+    PyObject *module = get_event_loop_module();
+    if (module == NULL) {
+        return NULL;
+    }
+
+    PyObject *capsule = PyObject_GetAttrString(module, EVENT_LOOP_ATTR_NAME);
+    if (capsule == NULL) {
+        PyErr_Clear();  /* Attribute doesn't exist */
+        return NULL;
+    }
+
+    if (!PyCapsule_IsValid(capsule, EVENT_LOOP_CAPSULE_NAME)) {
+        Py_DECREF(capsule);
+        return NULL;
+    }
+
+    erlang_event_loop_t *loop = (erlang_event_loop_t *)PyCapsule_GetPointer(
+        capsule, EVENT_LOOP_CAPSULE_NAME);
+    Py_DECREF(capsule);
+
+    return loop;
+}
+
+/**
+ * Set the event loop for the current interpreter.
+ * MUST be called with GIL held.
+ * Stores as py_event_loop._loop module attribute.
+ *
+ * @param loop Event loop to set
+ * @return 0 on success, -1 on error
+ */
+static int set_interpreter_event_loop(erlang_event_loop_t *loop) {
+    PyObject *module = get_event_loop_module();
+    if (module == NULL) {
+        return -1;
+    }
+
+    if (loop == NULL) {
+        /* Clear the event loop attribute */
+        if (PyObject_SetAttrString(module, EVENT_LOOP_ATTR_NAME, Py_None) < 0) {
+            PyErr_Clear();
+        }
+        return 0;
+    }
+
+    PyObject *capsule = PyCapsule_New(loop, EVENT_LOOP_CAPSULE_NAME, NULL);
+    if (capsule == NULL) {
+        return -1;
+    }
+
+    int result = PyObject_SetAttrString(module, EVENT_LOOP_ATTR_NAME, capsule);
+    Py_DECREF(capsule);
+
+    if (result < 0) {
+        PyErr_Clear();
+        return -1;
+    }
+
+    return 0;
+}
+
 /* ============================================================================
  * Resource Callbacks
  * ============================================================================ */
 
-/* Forward declaration of global Python event loop pointer (defined later in file) */
+/* Global Python event loop pointer - kept for fast access from C code */
 static erlang_event_loop_t *g_python_event_loop;
 
 /* Forward declaration */
@@ -2089,29 +2195,48 @@ ERL_NIF_TERM nif_set_udp_broadcast(ErlNifEnv *env, int argc,
 /**
  * Initialize the global Python event loop.
  * Called from Erlang when setting up the event loop for Python use.
+ * This function expects to be called when the GIL is held (during py_init).
  */
 int py_event_loop_init_python(ErlNifEnv *env, erlang_event_loop_t *loop) {
     (void)env;
     g_python_event_loop = loop;
+
+    /* Store in per-interpreter storage if GIL is held */
+    if (PyGILState_Check()) {
+        set_interpreter_event_loop(loop);
+    }
+
     return 0;
 }
 
 /**
  * NIF to set the global Python event loop.
  * Called from Erlang: py_nif:set_python_event_loop(LoopRef)
+ *
+ * Stores the event loop both in the global C variable (for fast access)
+ * and in the Python module attribute (for sub-interpreter support).
  */
 ERL_NIF_TERM nif_set_python_event_loop(ErlNifEnv *env, int argc,
                                         const ERL_NIF_TERM argv[]) {
     (void)argc;
-    (void)env;
 
     erlang_event_loop_t *loop;
     if (!enif_get_resource(env, argv[0], EVENT_LOOP_RESOURCE_TYPE, (void **)&loop)) {
         return make_error(env, "invalid_event_loop");
     }
 
+    /* Set global C variable for fast access */
     g_python_event_loop = loop;
 
+    /* Also store in Python module for sub-interpreter support */
+    gil_guard_t guard = gil_acquire();
+    int result = set_interpreter_event_loop(loop);
+    gil_release(guard);
+
+    if (result < 0) {
+        return make_error(env, "failed_to_set_event_loop");
+    }
+
     return ATOM_OK;
 }
 
@@ -2703,6 +2828,11 @@ int create_default_event_loop(ErlNifEnv *env) {
     /* Set as global Python event loop */
     g_python_event_loop = loop;
 
+    /* Store in per-interpreter storage if GIL is held */
+    if (PyGILState_Check()) {
+        set_interpreter_event_loop(loop);
+    }
+
     /* Keep a reference to prevent garbage collection */
     /* Note: This loop will be replaced when py_event_loop:init runs */
 

c_src/py_nif.h

@@ -1303,4 +1303,74 @@ static PyObject *thread_worker_call(const char *func_name, size_t func_name_len,
 
 /** @} */
 
+/* ============================================================================
+ * Safe GIL/Thread State Acquisition
+ * ============================================================================
+ *
+ * These helpers provide safe GIL acquisition that works across:
+ * - Python 3.9-3.11 (standard GIL)
+ * - Python 3.12-3.13 (stricter thread state checks)
+ * - Python 3.13t free-threaded (no GIL, but thread attachment required)
+ *
+ * The pattern follows PyO3's Python::attach() approach:
+ * 1. Check if already attached via PyGILState_Check()
+ * 2. If not, use PyGILState_Ensure() to attach
+ * 3. Track whether we acquired so we release correctly
+ *
+ * Per Python docs, PyGILState_Ensure/Release work in free-threaded builds
+ * to manage thread attachment even without a GIL.
+ */
+
+/**
+ * @defgroup gil_helpers Safe GIL/Thread State Helpers
+ * @brief Thread-safe GIL acquisition for Python 3.12+ compatibility
+ * @{
+ */
+
+/**
+ * @brief Guard structure for safe GIL acquisition/release
+ */
+typedef struct {
+    PyGILState_STATE gstate;  /**< GIL state from PyGILState_Ensure */
+    int acquired;             /**< 1 if we acquired, 0 if already held */
+} gil_guard_t;
+
+/**
+ * @brief Safely acquire the GIL/attach to Python runtime.
+ *
+ * This function is reentrant - if the current thread already holds the GIL
+ * (or is attached in free-threaded builds), it returns immediately without
+ * double-acquiring.
+ *
+ * @return Guard structure that must be passed to gil_release()
+ */
+static inline gil_guard_t gil_acquire(void) {
+    gil_guard_t guard = {.gstate = PyGILState_UNLOCKED, .acquired = 0};
+
+    /* Check if already attached to Python runtime */
+    if (PyGILState_Check()) {
+        return guard;
+    }
+
+    /* Attach to Python runtime (acquires GIL in GIL-enabled builds) */
+    guard.gstate = PyGILState_Ensure();
+    guard.acquired = 1;
+    return guard;
+}
+
+/**
+ * @brief Release the GIL/detach from Python runtime.
+ *
+ * Only releases if we actually acquired in gil_acquire().
+ *
+ * @param guard The guard structure returned by gil_acquire()
+ */
+static inline void gil_release(gil_guard_t guard) {
+    if (guard.acquired) {
+        PyGILState_Release(guard.gstate);
+    }
+}
+
+/** @} */
+
 #endif /* PY_NIF_H */