Change levels and add new section to thread safety page

- Change levels to include atomic and safe on distinct objects.
- Add a section explaining the levels in the thread safety page
- Cross reference levels section from annotation

Author: lysnikolaou

Doc/data/threadsafety.dat

@@ -6,12 +6,14 @@
 # Where level is one of:
 #   incompatible -- not safe even with external locking
 #   compatible   -- safe if the caller serializes all access with external locks
-#   safe         -- safe for concurrent use
+#   distinct     -- safe on distinct objects without external synchronization
+#   shared       -- safe for concurrent use on the same object
+#   atomic       -- atomic
 #
 # Lines beginning with '#' are ignored.
 # The function name must match the C domain identifier used in the documentation.
 
 # Synchronization primitives (Doc/c-api/synchronization.rst)
-PyMutex_Lock:safe:
-PyMutex_Unlock:safe:
-PyMutex_IsLocked:safe:
+PyMutex_Lock:shared:
+PyMutex_Unlock:shared:
+PyMutex_IsLocked:atomic:

Doc/glossary.rst

@@ -1587,19 +1587,6 @@ Glossary
       See :ref:`Thread State and the Global Interpreter Lock <threads>` for more
       information.
 
-   thread-compatible
-      A function or operation that is safe to call from multiple threads
-      provided the caller supplies appropriate external synchronization, for
-      example by holding a :term:`lock` for the duration of each call. Without
-      such synchronization, concurrent calls may produce :term:`race conditions
-      <race condition>` or :term:`data races <data race>`.
-
-   thread-incompatible
-      A function or operation that cannot be made safe for concurrent use even
-      with external synchronization. Thread-incompatible code typically
-      accesses global state in an unsynchronized way and must be called from
-      only one thread at a time throughout the program's lifetime.
-
    thread-safe
       A module, function, or class that behaves correctly when used by multiple
       threads concurrently.  Thread-safe code uses appropriate

Doc/library/threadsafety.rst

@@ -13,6 +13,88 @@ For general guidance on writing thread-safe code in free-threaded Python, see
 :ref:`freethreading-python-howto`.
 
 
+.. _threadsafety-levels:
+
+Thread safety levels
+====================
+
+The C API documentation uses the following levels to describe the thread
+safety guarantees of each function. The levels are listed from least to
+most safe.
+
+.. _threadsafety-level-incompatible:
+
+Incompatible
+------------
+
+A function or operation that cannot be made safe for concurrent use even
+with external synchronization. Incompatible code typically accesses
+global state in an unsynchronized way and must only be called from a single
+thread throughout the program's lifetime.
+
+Example: a function that modifies process-wide state such as signal handlers
+or environment variables, where concurrent calls from any threads, even with
+external locking, can conflict with the runtime or other libraries.
+
+.. _threadsafety-level-compatible:
+
+Compatible
+----------
+
+A function or operation that is safe to call from multiple threads
+*provided* the caller supplies appropriate external synchronization, for
+example by holding a :term:`lock` for the duration of each call. Without
+such synchronization, concurrent calls may produce :term:`race conditions
+<race condition>` or :term:`data races <data race>`.
+
+Example: a function that reads from or writes to an object whose internal
+state is not protected by a lock. Callers must ensure that no two threads
+access the same object at the same time.
+
+.. _threadsafety-level-distinct:
+
+Safe on distinct objects
+------------------------
+
+A function or operation that is safe to call from multiple threads without
+external synchronization, as long as each thread operates on a **different**
+object. Two threads may call the function at the same time, but they must
+not pass the same object (or objects that share underlying state) as
+arguments.
+
+Example: a function that modifies fields of a struct using non-atomic
+writes. Two threads can each call the function on their own struct
+instance safely, but concurrent calls on the *same* instance require
+external synchronization.
+
+.. _threadsafety-level-shared:
+
+Safe on shared objects
+----------------------
+
+A function or operation that is safe for concurrent use on the **same**
+object. The implementation uses internal synchronization (such as
+:term:`per-object locks <per-object lock>` or
+:ref:`critical sections <python-critical-section-api>`) to protect shared
+mutable state, so callers do not need to supply their own locking.
+
+Example: :c:func:`PyMutex_Lock` can be called from multiple threads on the
+same :c:type:`PyMutex` - it uses internal synchronization to serialize
+access.
+
+.. _threadsafety-level-atomic:
+
+Atomic
+------
+
+A function or operation that appears :term:`atomic <atomic operation>` with
+respect to other threads - it executes instantaneously from the perspective
+of other threads. This is the strongest form of thread safety.
+
+Example: :c:func:`PyMutex_IsLocked` performs an atomic read of the mutex
+state and can be called from any thread at any time.
+
+
 .. _thread-safety-list:
 
 Thread safety for list objects

Doc/tools/extensions/c_annotations.py

@@ -127,7 +127,9 @@ def read_stable_abi_data(stable_abi_file: Path) -> dict[str, StableABIEntry]:
 _VALID_THREADSAFETY_LEVELS = frozenset({
     "incompatible",
     "compatible",
-    "safe",
+    "distinct",
+    "shared",
+    "atomic",
 })
 
 
@@ -307,25 +309,35 @@ def _threadsafety_annotation(level: str) -> nodes.emphasis:
     match level:
         case "incompatible":
             display = sphinx_gettext("Not safe to call from multiple threads.")
-            reftarget = "thread-incompatible"
+            reftarget = "threadsafety-level-incompatible"
         case "compatible":
             display = sphinx_gettext(
-                "Safe to call from multiple threads with external synchronization only."
+                "Safe to call from multiple threads"
+                " with external synchronization only."
             )
-            reftarget = "thread-compatible"
-        case "safe":
-            display = sphinx_gettext("Safe for concurrent use.")
-            reftarget = "thread-safe"
-        case _:
-            raise AssertionError(
-                "Only the levels 'incompatible', 'compatible' and 'safe' are possible"
+            reftarget = "threadsafety-level-compatible"
+        case "distinct":
+            display = sphinx_gettext(
+                "Safe to call without external synchronization"
+                " on distinct objects."
+            )
+            reftarget = "threadsafety-level-distinct"
+        case "shared":
+            display = sphinx_gettext(
+                "Safe for concurrent use on the same object."
             )
+            reftarget = "threadsafety-level-shared"
+        case "atomic":
+            display = sphinx_gettext("Atomic.")
+            reftarget = "threadsafety-level-atomic"
+        case _:
+            raise AssertionError(f"Unknown thread safety level {level!r}")
     ref_node = addnodes.pending_xref(
         display,
         nodes.Text(display),
         refdomain="std",
         reftarget=reftarget,
-        reftype="term",
+        reftype="ref",
         refexplicit="True",
     )
     prefix = sphinx_gettext("Thread safety:") + " "