Make green_switch (python level greenlet.switch) and green_throw check for (prohibit) cross-thread switches early on free-threaded builds. This fixes some corruption around argument handling. The TLBC issue may also be corrected; at least, I don't reproduce it anymore.

Author: jamadden

.github/workflows/tests.yml

@@ -114,20 +114,6 @@ jobs:
         python -c 'import greenlet._greenlet as G; assert G.GREENLET_USE_STANDARD_THREADING'
         python -m unittest discover -v greenlet.tests
     - name: Doctest
-      env:
-        # XXX: On 3.14t, when the thread-local bytecode cache is
-        # enabled, sphinx crashes on module cleanup: there is a
-        # reference to pdb.set_trace in ``glob``, and when the
-        # shutdown sequence tries to clear that value, it segfaults
-        # dec-reffing it after taking it out of the module dict. The
-        # object appears to be corrupt, but it is utterly unclear how
-        # we could have done this. It is 100% reliable on bath Mac and
-        # Linux. It can be traced down to a very simple doctest
-        # snippet in greenlet_gc.rst, but running that same snippet
-        # standalone in a unit test doesn't produce the error.
-        #
-        # So this is a temporary workaround.
-        PYTHON_TLBC: "0"
       run: |
         sphinx-build -b doctest -d docs/_build/doctrees2 docs docs/_build/doctest2
     - name: Lint

CHANGES.rst

@@ -16,12 +16,22 @@
   <https://github.com/python-greenlet/greenlet/pull/499>`_ by Nicolas
   Bouvrette.
 - Address the results of an automated code audit performed by
-  devdanzin. This includes several minor correctness changes that
+  Daniel Diniz. This includes several minor correctness changes that
   theoretically could have been crashing bugs, but typically only in
   very rare circumstances.
 
   See `PR 502 <https://github.com/python-greenlet/greenlet/pull/502>`_.
 
+- Fix several race conditions that could arise in free-threaded
+  builds when using greenlet objects from multiple threads, some of
+  which could lead to assertion failures or interpreter crashes. On CI,
+  this also eliminated the need to disable the thread-local bytecode
+  cache.
+
+  See `issue 503
+  <https://github.com/python-greenlet/greenlet/issues/503>`_, with
+  thanks to Nitay Dariel and Daniel Diniz.
+
 3.3.2 (2026-02-20)
 ==================
 

docs/caveats.rst

@@ -37,7 +37,8 @@ Free-threading Is Experimental
 ==============================
 
 Beginning with greenlet 3.3.0, support for Python 3.14's free-threaded
-mode is enabled. Use caution, as it has only limited testing.
+mode is enabled; greenlet 3.4.0 expands this support and fixes several
+race conditions. Use caution, as it has only limited testing.
 
 There are known issues running greenlets in a free-threaded CPython.
 These include:
@@ -52,4 +53,6 @@ These include:
   hence the specializing interpreter) to avoid a rare crash. If your
   process crashes on accessing an attribute or object, or at shutdown
   during module cleanup, try setting the environment variable
-  ``PYTHON_TLBC=0`` or using the ``-X tlbc=0`` argument.
+  ``PYTHON_TLBC=0`` or using the ``-X tlbc=0`` argument. (If you
+  encounter this with greenlet 3.4, please open an issue and let the
+  maintainers know.)

src/greenlet/PyGreenlet.cpp

@@ -372,6 +372,29 @@ PyDoc_STRVAR(
 static PyObject*
 green_switch(PyGreenlet* self, PyObject* args, PyObject* kwargs)
 {
+    // Our use of Greenlet::args() makes this method non-reentrant.
+    // Therefore, check to be sure the switch will be allowed ---
+    // we're calling from the same thread that ``self`` belongs to ---
+    // BEFORE doing anything with args(). If we don't do this, we can
+    // find args() getting clobbered by switches that will never
+    // succeed.
+    //
+    // TODO: We're only doing this for free-threaded builds because
+    // those are the only ones that have demonstrated an issue,
+    // trusting our later checks in g_switch to perform the same
+    // function and the GIL to keep us from being reentered in regular
+    // builds. BUT should we always do this as an extra measure of
+    // safety in case we run code at unexpected times (e.g., a GC?)
+#ifdef Py_GIL_DISABLED
+    try {
+        self->pimpl->check_switch_allowed();
+    }
+    catch (const PyErrOccurred&) {
+        return nullptr;
+    }
+#endif
+
+
     using greenlet::SwitchingArgs;
     SwitchingArgs switch_args(OwnedObject::owning(args), OwnedObject::owning(kwargs));
     self->pimpl->may_switch_away();
@@ -454,6 +477,16 @@ PyDoc_STRVAR(
 static PyObject*
 green_throw(PyGreenlet* self, PyObject* args)
 {
+    // See green_switch for why we call this early.
+#ifdef Py_GIL_DISABLED
+    try {
+        self->pimpl->check_switch_allowed();
+    }
+    catch (const PyErrOccurred&) {
+        return nullptr;
+    }
+#endif
+
     PyArgParseParam typ(mod_globs->PyExc_GreenletExit);
     PyArgParseParam val;
     PyArgParseParam tb;

src/greenlet/TGreenlet.cpp

@@ -198,7 +198,7 @@ Greenlet::g_switchstack(void)
 
     // No stack-based variables are valid anymore.
 
-    // But the global is volatile so we can reload it without the
+    // But the global is thread_local volatile so we can reload it without the
     // compiler caching it from earlier.
     Greenlet* greenlet_that_switched_in = switching_thread_state; // aka this
     switching_thread_state = nullptr;
@@ -234,14 +234,14 @@ Greenlet::check_switch_allowed() const
     // TODO: Give the objects an API to determine if they belong
     // to a dead thread.
 
-    const BorrowedMainGreenlet main_greenlet = this->find_main_greenlet_in_lineage();
+    const BorrowedMainGreenlet my_main_greenlet = this->find_main_greenlet_in_lineage();
 
-    if (!main_greenlet) {
+    if (!my_main_greenlet) {
         throw PyErrOccurred(mod_globs->PyExc_GreenletError,
                             "cannot switch to a garbage collected greenlet");
     }
 
-    if (!main_greenlet->thread_state()) {
+    if (!my_main_greenlet->thread_state()) {
         throw PyErrOccurred(mod_globs->PyExc_GreenletError,
                             "cannot switch to a different thread (which happens to have exited)");
     }
@@ -255,26 +255,26 @@ Greenlet::check_switch_allowed() const
     // may not be visible yet. So we need to check against the
     // current thread state (once the cheaper checks are out of
     // the way)
-    const BorrowedMainGreenlet current_main_greenlet = GET_THREAD_STATE().state().borrow_main_greenlet();
+    const BorrowedMainGreenlet main_greenlet_cur_thread = GET_THREAD_STATE().state().borrow_main_greenlet();
     if (
         // lineage main greenlet is not this thread's greenlet
-        current_main_greenlet != main_greenlet
+        main_greenlet_cur_thread != my_main_greenlet
         || (
             // atteched to some thread
             this->main_greenlet()
             // XXX: Same condition as above. Was this supposed to be
             // this->main_greenlet()?
-            && current_main_greenlet != main_greenlet)
+            && main_greenlet_cur_thread != my_main_greenlet)
         // switching into a known dead thread (XXX: which, if we get here,
         // is bad, because we just accessed the thread state, which is
         // gone!)
-        || (!current_main_greenlet->thread_state())) {
+        || (!main_greenlet_cur_thread->thread_state())) {
         // CAUTION: This may trigger memory allocations, gc, and
         // arbitrary Python code.
         throw PyErrOccurred(
             mod_globs->PyExc_GreenletError,
             "Cannot switch to a different thread\n\tCurrent:  %R\n\tExpected: %R",
-            current_main_greenlet, main_greenlet);
+            main_greenlet_cur_thread, my_main_greenlet);
     }
 }
 

src/greenlet/TGreenlet.hpp

@@ -403,6 +403,18 @@ namespace greenlet
         }
 
         virtual OwnedObject throw_GreenletExit_during_dealloc(const ThreadState& current_thread_state);
+
+        /**
+         * Depends on the state of this->args() or the current Python
+         * error indicator. Thus, it is not threadsafe or reentrant.
+         * You (you being ``green_switch``, the Python-level
+         * ``greenlet.switch`` method) should call
+         * ``check_switch_allowed`` in free-threaded builds before
+         * calling this method and catch ``PyErrOccurred`` if it isn't
+         * a valid switch. This method should also call that method
+         * because there are places where we can switch internally
+         * without going through the Python method.
+         */
         virtual OwnedObject g_switch() = 0;
         /**
          * Force the greenlet to appear dead. Used when it's not
@@ -500,6 +512,11 @@ namespace greenlet
         // slp_switch() failed.
         virtual bool force_slp_switch_error() const noexcept;
 
+        // Check the preconditions for switching to this greenlet; if they
+        // aren't met, throws PyErrOccurred. Most callers will want to
+        // catch this and clear the arguments if they've been set.
+        inline void check_switch_allowed() const;
+
     protected:
         inline void release_args();
 
@@ -566,11 +583,6 @@ namespace greenlet
         // Returns the previous greenlet we just switched away from.
         virtual OwnedGreenlet g_switchstack_success() noexcept;
 
-
-        // Check the preconditions for switching to this greenlet; if they
-        // aren't met, throws PyErrOccurred. Most callers will want to
-        // catch this and clear the arguments
-        inline void check_switch_allowed() const;
         class GreenletStartedWhileInPython : public std::runtime_error
         {
         public:

src/greenlet/TUserGreenlet.cpp

@@ -119,9 +119,16 @@ UserGreenlet::g_switch()
 {
     try {
         if (!this->args() && !PyErr_Occurred()) {
-            // we have nothing to send as the result of switching, most
-            // likely the result of trying to switch to a dead
-            // greenlet.
+            // we have nothing to send as the result of switching,
+            // most likely because we've somehow allowed concurrent
+            // uses of switch from multiple threads (which may or may
+            // not be allowed by check_switch_allowed)
+            // ``green_switch`` defends against this by calling
+            // ``check_switch_allowed`` before messing with
+            // ``args()``, but we have at least one internal caller
+            // (``throw_GreenletExit_during_dealloc``) so we keep both
+            // this explicit check and our call to
+            // ``check_switch_allowed``
             throw PyErrOccurred(mod_globs->PyExc_GreenletError,
                                 "cannot switch with no pending arguments or exception");
         }

src/greenlet/greenlet_refs.hpp

@@ -446,8 +446,6 @@ namespace greenlet {
         void CLEAR()
         {
             Py_CLEAR(this->p);
-            // XXX: Have failed this assertion in free-threaded builds
-            // using multiple threads
             assert(this->p == nullptr);
         }
     };

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 envlist =
-    py{37,38,39,310,311,312,313,314},py{310,311,312,313,314}-ns,docs,py314t,tsan-314#,tsan-314t
+    py{310,311,312,313,314},docs,py314t,tsan-314,tsan-314t
 
 [testenv]
 commands =