gh-142518: add thread safety docs for set C-APIs

Doc/c-api/set.rst

@@ -89,6 +89,11 @@ the constructor functions work with any iterable Python object.
    actually iterable.  The constructor is also useful for copying a set
    (``c=set(s)``).
 
+   .. note::
+
+      The operation is atomic in the :term:`free-threaded build`, if *iterable* is a set,
+      frozenset or dict.
+
 
 .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
 
@@ -97,6 +102,11 @@ the constructor functions work with any iterable Python object.
    set on success or ``NULL`` on failure.  Raise :exc:`TypeError` if *iterable* is
    not actually iterable.
 
+   .. note::
+
+      The operation is atomic in the :term:`free-threaded build`, if *iterable* is a set,
+      frozenset or dict.
+
 
 The following functions and macros are available for instances of :class:`set`
 or :class:`frozenset` or instances of their subtypes.
@@ -124,6 +134,11 @@ or :class:`frozenset` or instances of their subtypes.
    the *key* is unhashable. Raise :exc:`SystemError` if *anyset* is not a
    :class:`set`, :class:`frozenset`, or an instance of a subtype.
 
+   .. note::
+
+      The operation is atomic in the :term:`free-threaded build`, if *key*
+      is a simple type (e.g. :class:`str`, :class:`int`, :class:`float`) or any
+      other object which does not define :meth:`~object.__hash__` and :meth:`~object.__eq__` methods.
 
 .. c:function:: int PySet_Add(PyObject *set, PyObject *key)
 
@@ -135,6 +150,13 @@ or :class:`frozenset` or instances of their subtypes.
    :exc:`SystemError` if *set* is not an instance of :class:`set` or its
    subtype.
 
+   .. note::
+
+      The operation is atomic in the :term:`free-threaded build`, if *key*
+      is a simple type (e.g. :class:`str`, :class:`int`, :class:`float`) or any
+      other object which does not define :meth:`~object.__hash__` and :meth:`~object.__eq__` methods.
+
+
 
 The following functions are available for instances of :class:`set` or its
 subtypes but not for instances of :class:`frozenset` or its subtypes.
@@ -149,6 +171,12 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
    temporary frozensets. Raise :exc:`SystemError` if *set* is not an
    instance of :class:`set` or its subtype.
 
+   .. note::
+
+      The operation is atomic in the :term:`free-threaded build`, if *key*
+      is a simple type (e.g. :class:`str`, :class:`int`, :class:`float`) or any
+      other object which does not define :meth:`~object.__hash__` and :meth:`~object.__eq__` methods.
+
 
 .. c:function:: PyObject* PySet_Pop(PyObject *set)
 
@@ -164,6 +192,12 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
    success. Return ``-1`` and raise :exc:`SystemError` if *set* is not an instance of
    :class:`set` or its subtype.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the set is emptied before its entries
+      are cleared, so other threads will observe an empty set rather than
+      intermediate states.
+
 
 Deprecated API
 ^^^^^^^^^^^^^^

Doc/data/threadsafety.dat

@@ -125,6 +125,28 @@ PyByteArray_GET_SIZE:atomic:
 PyByteArray_AsString:compatible:
 PyByteArray_AS_STRING:compatible:
 
+# Creation - may iterate the iterable argument, calling arbitrary code
+# atomic for sets, dicts, and frozendicts.
+PySet_New:shared:
+PyFrozenSet_New:shared:
+
+# Size - uses atomic load on free-threaded builds
+PySet_Size:atomic:
+PySet_GET_SIZE:atomic:
+
+# Contains - lock-free, atomic with simple types
+PySet_Contains:shared:
+
+# Mutations - hold per-object lock for duration
+# atomic with simple types
+PySet_Add:shared:
+PySet_Discard:shared:
+
+# Pop - hold per-object lock for duration;
+PySet_Pop:atomic:
+
+# Clear - empties the set before clearing
+PySet_Clear:atomic:
 # Capsule objects (Doc/c-api/capsule.rst)
 
 # Type check - read ob_type pointer, always safe