Update docs regarding free-threading.

Author: jamadden

CHANGES.rst

@@ -13,6 +13,12 @@
   CPython on Windows. (Free-threaded CPython 3.13 may work, but is
   untested and unsupported.)
 
+  .. caution::
+
+     Under some rare scenarios, the interpreter may crash on accessing
+     a variable or attribute or when shutting down. If this happens,
+     try disabling the thread-local bytecode cache. See the greenlet
+     documentation for more.
 
 3.2.4 (2025-08-07)
 ==================

docs/caveats.rst

@@ -33,17 +33,23 @@ lead to a hang.
 
 See :issue:`143` for an example.
 
-Free-threading Is Not Supported
-===============================
+Free-threading Is Experimental
+==============================
 
-Beginning with 3.14 (and experimental in 3.13), CPython may be built
-in a free-threaded mode where the GIL is not used by default. greenlet
-does not support this mode (although it will build with it), and using
-greenlet in such an interpreter will cause the GIL to be enabled.
+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.
 
-In addition, there are known issues running greenlets in a
-free-threaded CPython. These include:
+There are known issues running greenlets in a free-threaded CPython.
+These include:
 
+- As with any threaded program, use caution when forking. Greenlet
+  maintains internal locks and forking at the wrong time might result
+  in the child process hanging.
 - Garbage collection differences may cause ``GreenletExit`` to no
   longer be raised in certain multi-threaded scenarios.
 - There may be other memory leaks.
+- It may be necessary to disable the thread-local bytecode cache (and
+  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.

docs/index.rst

@@ -80,8 +80,8 @@ that since they're cooperatively scheduled, you are in control of
 when they execute, and since they are coroutines, many greenlets can
 exist in a single native thread.
 
-Note that greenlet will cause a free-threaded build of Python to
-allocate a GIL, so no actual free-threading will take place. For more
+Beginning with greenlet 3.3, free-threaded builds of CPython are
+supported, but they have limited testing and some other limitations. For more
 on free-threading and greenlet, see :doc:`caveats`.
 
 .. rubric:: How are greenlets different from threads?
@@ -106,9 +106,9 @@ implemented entirely without involving the operating system, they can
 require fewer resources; it is often practical to have many more
 greenlets than it is threads.
 
-Note that greenlet will cause a free-threaded build of Python to
-allocate a GIL, so no actual free-threading will take place. For more
-on free-threading and greenlet, see :doc:`caveats`.
+Beginning with greenlet 3.3, you can combine threads and greenlets on
+free-threaded builds of CPython to take advantage of the strengths of
+both, but there may be limitations. See :doc:`caveats`.
 
 .. _race conditions: https://en.wikipedia.org/wiki/Race_condition
 .. _deadlocks: https://docs.microsoft.com/en-us/troubleshoot/dotnet/visual-basic/race-conditions-deadlocks#when-deadlocks-occur