Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kumaraditya303 wants to merge 1 commit into
base: main
Choose a base branch
from
+58 −1
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions Doc/c-api/set.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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.
Expand Down Expand Up @@ -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)

Expand All @@ -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.
Expand All @@ -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)

Expand All @@ -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
^^^^^^^^^^^^^^
Expand Down
25 changes: 24 additions & 1 deletion Doc/data/threadsafety.dat
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
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:
Loading