Skip to content

Commit a65b95f

Browse files
committed
Document non-thread-safe C extensions re-enabling GIL
1 parent c8dfcaf commit a65b95f

1 file changed

Lines changed: 12 additions & 0 deletions

File tree

docs/considerations.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,18 @@ Module-level functions are picklable and work with both backends. For instance:
150150
151151
Hello!
152152
153+
Non-Thread-Safe C Extensions
154+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
155+
156+
In free-threaded Python builds, the GIL is re-enabled at runtime when a C extension not marked as thread-safe is
157+
loaded. Since :mod:`freethreading` determines its backend once at import time based on the current GIL state, loading
158+
such an extension afterward means the library continues using the :mod:`threading` backend even though the GIL is now
159+
enabled.
160+
161+
This is by design — switching backends mid-execution would cause incompatibilities between primitives created at
162+
different times. To avoid this, import :mod:`freethreading` after loading any C extensions whose thread-safety is
163+
unknown.
164+
153165
``Queue.qsize()`` on macOS
154166
^^^^^^^^^^^^^^^^^^^^^^^^^^
155167

0 commit comments

Comments
 (0)