From 2839ee134573a6b2e7c6dcfb13f1038b7aba8a57 Mon Sep 17 00:00:00 2001
From: Kumar Aditya <kumaraditya@python.org>
Date: Sat, 11 Apr 2026 01:03:24 +0530
Subject: [PATCH] gh-142518: add thread safety docs for set C-APIs (GH-146562)
 (cherry picked from commit dd88e77fad887aaf00ead1a3ba655fc00fd1dc25)

Co-authored-by: Kumar Aditya <kumaraditya@python.org>
Co-authored-by: Victor Stinner <vstinner@python.org>
---
 Doc/c-api/set.rst         | 31 +++++++++++++++++++++++++++++++
 Doc/data/threadsafety.dat | 23 +++++++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
index b74859dd669c54..43413b0fb7c23f 100644
--- a/Doc/c-api/set.rst
+++ b/Doc/c-api/set.rst
@@ -92,6 +92,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 on :term:`free threading <free-threaded build>`
+      when *iterable* is a :class:`set`, :class:`frozenset`, :class:`dict` or :class:`frozendict`.
+
 
 .. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
 
@@ -100,6 +105,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 on :term:`free threading <free-threaded build>`
+      when *iterable* is a :class:`set`, :class:`frozenset`, :class:`dict` or :class:`frozendict`.
+
 
 The following functions and macros are available for instances of :class:`set`
 or :class:`frozenset` or instances of their subtypes.
@@ -127,6 +137,10 @@ 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 on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
 
 .. c:function:: int PySet_Add(PyObject *set, PyObject *key)
 
@@ -138,6 +152,12 @@ 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 on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
+
 
 The following functions are available for instances of :class:`set` or its
 subtypes but not for instances of :class:`frozenset` or its subtypes.
@@ -152,6 +172,11 @@ 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 on :term:`free threading <free-threaded build>`
+      when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
+
 
 .. c:function:: PyObject* PySet_Pop(PyObject *set)
 
@@ -167,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
 ^^^^^^^^^^^^^^
diff --git a/Doc/data/threadsafety.dat b/Doc/data/threadsafety.dat
index 82edd1167ef128..c059598fdbd76c 100644
--- a/Doc/data/threadsafety.dat
+++ b/Doc/data/threadsafety.dat
@@ -125,6 +125,29 @@ PyByteArray_GET_SIZE:atomic:
 PyByteArray_AsString:compatible:
 PyByteArray_AS_STRING:compatible:
 
+# Creation - may iterate the iterable argument, calling arbitrary code.
+# Atomic for sets, frozensets, 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