[mypyc] Document free threading and other doc updates (#21494)

Free threading support and limitations weren't documented at all.

Some features that we currently support were still documented as
unsupported. This includes some dunders and numeric use cases. We now
support simple numeric use cases via `vec[float]`.

Author: JukkaL

mypyc/doc/differences_from_python.rst

@@ -260,6 +260,45 @@ When run as interpreted, the first example will execute slower due to
 the extra namespace lookups. In interpreted code final attributes can
 also be modified.
 
+.. _free-threading:
+
+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).
+
+As libraries often won't be able to control the concurrent access by
+user code, we recommend that modules document that multi-threaded
+access is only supported via public interfaces that ensure correct
+synchronization. Marking attributes as internal using an underscore
+attribute prefix is another possibility, but this is not enforced at
+runtime. Another option is to document that multithreaded access is
+not supported, or that particular objects should not be used from
+multiple threads concurrently.
+
+It's always safe to perform read-only operations concurrently. Using
+objects with final attributes and tuple objects can help prevent
+race conditions without introducing extra overhead from explicit
+synchronization operations.
+
 Unsupported features
 --------------------
 
@@ -284,10 +323,8 @@ Dunder methods
 Native classes **cannot** use these dunders. If defined, they will not
 work as expected.
 
-* ``__del__``
 * ``__index__``
-* ``__getattr__``, ``__getattribute__``
-* ``__setattr__``
+* ``__getattribute__``
 * ``__delattr__``
 
 Generator expressions
@@ -318,7 +355,6 @@ non-exhaustive list of what won't work:
 - Compiled methods aren't considered methods by ``inspect.ismethod``
 - ``inspect.signature`` chokes on compiled functions with default arguments that
   are not simple literals
-- ``inspect.iscoroutinefunction`` and ``asyncio.iscoroutinefunction`` will always return False for compiled functions, even those defined with `async def`
 
 Profiling hooks and tracing
 ***************************

mypyc/doc/introduction.rst

@@ -23,8 +23,8 @@ also as normal, interpreted Python modules.
 Existing code with type annotations is often **1.5x to 5x** faster
 when compiled. Code tuned for mypyc can be **5x to 10x** faster.
 
-Mypyc currently aims to speed up non-numeric code, such as server
-applications. Mypyc is also used to compile itself (and mypy).
+Mypyc aims to be effective in many common use cases, including
+server applications. Mypyc is also used to compile itself (and mypy).
 
 Why mypyc?
 ----------
@@ -54,10 +54,11 @@ requires only minor changes to compile using mypyc.
 normal Python code. You can use interpreted Python during development,
 with familiar and fast workflows.
 
-**Runtime type safety.** Mypyc protects you from segfaults and memory
-corruption. Any unexpected runtime type safety violation is a bug in
-mypyc. Runtime values are checked against type annotations. (Without
-mypyc, type annotations are ignored at runtime.)
+**Runtime type safety.** Mypyc partially protects you from segfaults and
+memory corruption (see :ref:`free-threading` for limitations). Any
+unexpected runtime type safety violation is a bug in mypyc. Runtime
+values are checked against type annotations. (Without mypyc, type
+annotations are ignored at runtime.)
 
 **Find errors statically.** Mypyc uses mypy for static type checking
 that helps catch many bugs.
@@ -110,8 +111,7 @@ differently, however:
 * Mypyc performs strict enforcement of type annotations at runtime,
   resulting in better runtime type safety and easier debugging.
 
-Unlike Cython, mypyc doesn't directly support interfacing with C libraries
-or speeding up numeric code.
+Unlike Cython, mypyc doesn't directly support interfacing with C libraries.
 
 How does it work
 ----------------