From b86bd52a10121b1655238ff9de8db6716e48bd07 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Thu, 9 Jul 2026 14:15:13 +0100 Subject: [PATCH] [mypyc] Update free threading Python compatibility docs --- mypyc/doc/differences_from_python.rst | 44 +++++++++++++++------------ mypyc/doc/librt_threading.rst | 2 ++ 2 files changed, 27 insertions(+), 19 deletions(-) diff --git a/mypyc/doc/differences_from_python.rst b/mypyc/doc/differences_from_python.rst index 414476723125b..a139fab3aa2fb 100644 --- a/mypyc/doc/differences_from_python.rst +++ b/mypyc/doc/differences_from_python.rst @@ -265,25 +265,31 @@ also be modified. Free threading -------------- -Mypyc has basic support for free threading, but it doesn't provide the -same memory safety guarantees as Python in compiled modules, since -in current Python versions this would cause an unacceptable performance -impact. - -The exact details of the memory safety in the presence of data races -are likely to evolve in the future. Currently, compiled code must -ensure that proper synchronization is used to prevent data races. In -particular, these operations require explicit synchronization, such as -via ``threading.Lock``, if there is a possibility of data races -(the list is not exhaustive): - -* Reads or writes of non-final instance data attributes of native - classes. -* List item access or iteration using a ``list`` static type (using - ``Sequence`` or ``MutableSequence`` as the type ensure correct - implicit synchronization). -* Dict item access using a static ``dict`` type (using ``Mapping`` - or ``MutableMapping`` ensures correct implicit synchronization). +Mypyc supports free threading, but it doesn't provide the exact +memory safety guarantees as Python in compiled modules under +free threading when there are race conditions. + +Additionally, optimized primitive operations in compiled code may have +different atomicity properties compared to CPython. Use explicit +synchronization if code depends on operations being atomic. This is +already the recommended approach for normal Python code. + +Currently, compiled code must ensure that proper synchronization is +used to prevent data races involving non-final attributes in native +classes, unless the attribute has a value type such as ``bool``, +``float`` or ``i64``. You can use explicit +synchronization, such as via +:ref:`librt.threading.Lock ` (or +:py:class:`threading.Lock`, which is less efficient than +``librt.threading.Lock``) if there is a possibility of such a data +race. + +.. note:: + + We are working on improving memory safety in free-threading + builds of Python, and hope to make all normal Python features + memory safe, while providing more efficient but less safe + opt-in, non-standard features. As libraries often won't be able to control the concurrent access by user code, we recommend that modules document that multi-threaded diff --git a/mypyc/doc/librt_threading.rst b/mypyc/doc/librt_threading.rst index c6cb5c9e84e72..0af795bc0daab 100644 --- a/mypyc/doc/librt_threading.rst +++ b/mypyc/doc/librt_threading.rst @@ -9,6 +9,8 @@ threading primitives. Classes ------- +.. _librt-threading-lock: + Lock ^^^^