Add No-GIL Safe Mode with atomic state machine

- Add atomic runtime state machine (UNINIT->INITING->RUNNING->SHUTTING_DOWN->STOPPED)
- Convert volatile flags to _Atomic for thread safety
- Add NIF guards to reject work when not RUNNING
- Fix destructor memory corruption for OWN_GIL subinterpreters
- Add enif_keep_resource/release for ctx in suspended states
- Add debug counters NIF for runtime diagnostics
- Add CI sanitizer builds (ASan, TSan, UBSan)

Author: benoitc

.github/workflows/ci.yml

@@ -186,6 +186,82 @@ jobs:
           '
     continue-on-error: true  # Free-threading is experimental
 
+  # Sanitizer builds for detecting memory issues and race conditions
+  test-sanitizers:
+    name: ${{ matrix.sanitizer }} / Python ${{ matrix.python }}
+    runs-on: ubuntu-24.04
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # ASan + UBSan with Python 3.12
+          - sanitizer: "ASan+UBSan"
+            python: "3.12"
+            cmake_flags: "-DENABLE_ASAN=ON -DENABLE_UBSAN=ON"
+            env_vars: "ASAN_OPTIONS=detect_leaks=1:abort_on_error=1"
+          # ASan + UBSan with Python 3.13
+          - sanitizer: "ASan+UBSan"
+            python: "3.13"
+            cmake_flags: "-DENABLE_ASAN=ON -DENABLE_UBSAN=ON"
+            env_vars: "ASAN_OPTIONS=detect_leaks=1:abort_on_error=1"
+          # TSan with Python 3.12 (separate because incompatible with ASan)
+          - sanitizer: "TSan"
+            python: "3.12"
+            cmake_flags: "-DENABLE_TSAN=ON"
+            env_vars: "TSAN_OPTIONS=second_deadlock_stack=1"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Set up Erlang
+        uses: erlef/setup-beam@v1
+        with:
+          otp-version: "27.0"
+          rebar3-version: "3.24"
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake
+
+      - name: Set Python library path
+        run: |
+          PYTHON_LIB=$(python3 -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
+          echo "LD_LIBRARY_PATH=${PYTHON_LIB}:${LD_LIBRARY_PATH}" >> $GITHUB_ENV
+
+      - name: Clean and compile with sanitizers
+        run: |
+          rm -rf _build/cmake
+          mkdir -p _build/cmake
+          cd _build/cmake
+          cmake ../../c_src ${{ matrix.cmake_flags }}
+          cmake --build . -- -j $(nproc)
+          cd ../..
+          rebar3 compile
+
+      - name: Run tests with sanitizers
+        env:
+          ASAN_OPTIONS: ${{ contains(matrix.env_vars, 'ASAN_OPTIONS') && 'detect_leaks=1:abort_on_error=1' || '' }}
+          TSAN_OPTIONS: ${{ contains(matrix.env_vars, 'TSAN_OPTIONS') && 'second_deadlock_stack=1' || '' }}
+        run: |
+          rebar3 ct --readable=compact
+
+      - name: Check debug counters
+        run: |
+          erl -pa _build/default/lib/erlang_python/ebin -noshell -eval '
+            application:ensure_all_started(erlang_python),
+            Counters = py_nif:get_debug_counters(),
+            io:format("Debug counters: ~p~n", [Counters]),
+            halt().
+          '
+
   lint:
     name: Lint
     runs-on: ubuntu-24.04

c_src/CMakeLists.txt

@@ -57,6 +57,33 @@ if(ASGI_PROFILING)
     add_definitions(-DASGI_PROFILING)
 endif()
 
+# Sanitizer options for debugging race conditions and memory issues
+option(ENABLE_ASAN "Enable AddressSanitizer" OFF)
+option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)
+option(ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF)
+
+if(ENABLE_ASAN)
+    message(STATUS "AddressSanitizer enabled")
+    add_compile_options(-fsanitize=address -fno-omit-frame-pointer -g -O1)
+    add_link_options(-fsanitize=address)
+    # ASan is incompatible with TSan
+    if(ENABLE_TSAN)
+        message(FATAL_ERROR "ASan and TSan cannot be used together")
+    endif()
+endif()
+
+if(ENABLE_TSAN)
+    message(STATUS "ThreadSanitizer enabled")
+    add_compile_options(-fsanitize=thread -fno-omit-frame-pointer -g -O1)
+    add_link_options(-fsanitize=thread)
+endif()
+
+if(ENABLE_UBSAN)
+    message(STATUS "UndefinedBehaviorSanitizer enabled")
+    add_compile_options(-fsanitize=undefined -fno-omit-frame-pointer -g -O1)
+    add_link_options(-fsanitize=undefined)
+endif()
+
 if(PERF_BUILD)
     message(STATUS "Performance build enabled - using aggressive optimizations")
     # Override compiler flags for maximum performance

c_src/py_callback.c

@@ -633,6 +633,7 @@ static suspended_context_state_t *create_suspended_context_state_for_call(
     memset(state, 0, sizeof(suspended_context_state_t));
 
     state->ctx = ctx;
+    enif_keep_resource(ctx);  /* Keep ctx alive while suspended state exists */
     state->callback_id = tl_pending_callback_id;
     state->request_type = PY_REQ_CALL;
 
@@ -718,6 +719,7 @@ static suspended_context_state_t *create_suspended_context_state_for_eval(
     memset(state, 0, sizeof(suspended_context_state_t));
 
     state->ctx = ctx;
+    enif_keep_resource(ctx);  /* Keep ctx alive while suspended state exists */
     state->callback_id = tl_pending_callback_id;
     state->request_type = PY_REQ_EVAL;
 

c_src/py_exec.c

@@ -655,7 +655,7 @@ static void *executor_thread_main(void *arg) {
     /* Acquire GIL for this thread */
     PyGILState_STATE gstate = PyGILState_Ensure();
 
-    g_executor_running = true;
+    atomic_store(&g_executor_running, true);
 
     /*
      * Main processing loop.
@@ -670,7 +670,7 @@ static void *executor_thread_main(void *arg) {
         Py_BEGIN_ALLOW_THREADS
 
         pthread_mutex_lock(&g_executor_mutex);
-        while (g_executor_queue_head == NULL && !g_executor_shutdown) {
+        while (g_executor_queue_head == NULL && !atomic_load(&g_executor_shutdown)) {
             pthread_cond_wait(&g_executor_cond, &g_executor_mutex);
         }
 
@@ -682,7 +682,7 @@ static void *executor_thread_main(void *arg) {
                 g_executor_queue_tail = NULL;
             }
             req->next = NULL;
-        } else if (g_executor_shutdown) {
+        } else if (atomic_load(&g_executor_shutdown)) {
             /* Queue is empty and shutdown requested - exit */
             should_exit = true;
         }
@@ -702,6 +702,9 @@ static void *executor_thread_main(void *arg) {
                 /* Process the request with GIL held */
                 process_request(req);
 
+                /* Track completed requests */
+                atomic_fetch_add(&g_counters.complete_count, 1);
+
                 /* Signal completion */
                 pthread_mutex_lock(&req->mutex);
                 req->completed = true;
@@ -711,7 +714,7 @@ static void *executor_thread_main(void *arg) {
         }
     }
 
-    g_executor_running = false;
+    atomic_store(&g_executor_running, false);
     PyGILState_Release(gstate);
 
     return NULL;
@@ -720,8 +723,19 @@ static void *executor_thread_main(void *arg) {
 /**
  * Enqueue a request to the appropriate executor based on execution mode.
  * Routes to multi-executor pool, single executor, or executes directly.
+ *
+ * @return 0 on success, -1 if shutting down (request rejected)
  */
-static void executor_enqueue(py_request_t *req) {
+static int executor_enqueue(py_request_t *req) {
+    /* Reject work if runtime is shutting down (except shutdown requests) */
+    if (runtime_is_shutting_down() && req->type != PY_REQ_SHUTDOWN) {
+        atomic_fetch_add(&g_counters.rejected_count, 1);
+        return -1;
+    }
+
+    /* Track enqueued requests */
+    atomic_fetch_add(&g_counters.enqueue_count, 1);
+
     switch (g_execution_mode) {
 #ifdef HAVE_FREE_THREADED
         case PY_MODE_FREE_THREADED:
@@ -736,15 +750,15 @@ static void executor_enqueue(py_request_t *req) {
                 pthread_cond_signal(&req->cond);
                 pthread_mutex_unlock(&req->mutex);
             }
-            return;
+            return 0;
 #endif
 
         case PY_MODE_MULTI_EXECUTOR:
-            if (g_multi_executor_initialized) {
+            if (atomic_load(&g_multi_executor_initialized)) {
                 /* Route to multi-executor pool */
                 int exec_id = select_executor();
                 multi_executor_enqueue(exec_id, req);
-                return;
+                return 0;
             }
             /* Fall through to single executor if multi not initialized */
             break;
@@ -767,6 +781,7 @@ static void executor_enqueue(py_request_t *req) {
     }
     pthread_cond_signal(&g_executor_cond);
     pthread_mutex_unlock(&g_executor_mutex);
+    return 0;
 }
 
 /**
@@ -785,7 +800,7 @@ static void executor_wait(py_request_t *req) {
  * Called during Python initialization.
  */
 static int executor_start(void) {
-    g_executor_shutdown = false;
+    atomic_store(&g_executor_shutdown, false);
     g_executor_queue_head = NULL;
     g_executor_queue_tail = NULL;
 
@@ -795,19 +810,19 @@ static int executor_start(void) {
 
     /* Wait for executor to be ready */
     int max_wait = 100;  /* 1 second max */
-    while (!g_executor_running && max_wait-- > 0) {
+    while (!atomic_load(&g_executor_running) && max_wait-- > 0) {
         usleep(10000);  /* 10ms */
     }
 
-    return g_executor_running ? 0 : -1;
+    return atomic_load(&g_executor_running) ? 0 : -1;
 }
 
 /**
  * Stop the executor thread.
  * Called during Python finalization.
  */
 static void executor_stop(void) {
-    if (!g_executor_running) {
+    if (!atomic_load(&g_executor_running)) {
         return;
     }
 
@@ -816,7 +831,7 @@ static void executor_stop(void) {
     request_init(&shutdown_req);
     shutdown_req.type = PY_REQ_SHUTDOWN;
 
-    g_executor_shutdown = true;
+    atomic_store(&g_executor_shutdown, true);
     executor_enqueue(&shutdown_req);
     executor_wait(&shutdown_req);
     request_cleanup(&shutdown_req);
@@ -926,7 +941,7 @@ static void multi_executor_enqueue(int exec_id, py_request_t *req) {
  * Start the multi-executor pool.
  */
 static int multi_executor_start(int num_executors) {
-    if (g_multi_executor_initialized) {
+    if (atomic_load(&g_multi_executor_initialized)) {
         return 0;
     }
 
@@ -978,15 +993,15 @@ static int multi_executor_start(int num_executors) {
         }
     }
 
-    g_multi_executor_initialized = all_ready;
+    atomic_store(&g_multi_executor_initialized, all_ready);
     return all_ready ? 0 : -1;
 }
 
 /**
  * Stop the multi-executor pool.
  */
 static void multi_executor_stop(void) {
-    if (!g_multi_executor_initialized) {
+    if (!atomic_load(&g_multi_executor_initialized)) {
         return;
     }
 
@@ -1023,7 +1038,7 @@ static void multi_executor_stop(void) {
         }
     }
 
-    g_multi_executor_initialized = false;
+    atomic_store(&g_multi_executor_initialized, false);
 }
 
 /*