diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index 6974f74fbd597a..072076924300d1 100644 --- a/Doc/c-api/set.rst +++ b/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 ^^^^^^^^^^^^^^ diff --git a/Doc/data/threadsafety.dat b/Doc/data/threadsafety.dat index afb053adf5c62b..9c7a083341373e 100644 --- a/Doc/data/threadsafety.dat +++ b/Doc/data/threadsafety.dat @@ -123,4 +123,27 @@ PyByteArray_GET_SIZE:atomic: # Raw data - no locking; mutating it is unsafe if the bytearray object is shared between threads PyByteArray_AsString:compatible: -PyByteArray_AS_STRING:compatible: \ No newline at end of file +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: