Skip to content

gh-142518: Annotate PyDict_* C APIs for thread safety #145875

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

Merged
kumaraditya303 merged 8 commits into from
Apr 10, 2026
Merged

gh-142518: Annotate PyDict_* C APIs for thread safety #145875

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
52297b7
gh-142518: Annotate PyDict_* C APIs for thread safety
lysnikolaou Mar 12, 2026
e69f105
Merge branch 'main' into annotate-pydict
lysnikolaou Mar 18, 2026
a8d04a4
Merge branch 'main' of https://github.com/python/cpython into annotat…
kumaraditya303 Apr 2, 2026
c92c681
address review
kumaraditya303 Apr 2, 2026
8bc4cb5
address review on atomicity
kumaraditya303 Apr 10, 2026
4e22ad1
Merge branch 'main' of https://github.com/python/cpython into annotat…
kumaraditya303 Apr 10, 2026
9cacc03
Update Doc/data/threadsafety.dat
kumaraditya303 Apr 10, 2026
54a8c33
mention bool & bytes
kumaraditya303 Apr 10, 2026
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
Prev Previous commit
Next Next commit
address review
  • Loading branch information
@kumaraditya303
kumaraditya303 committed Apr 2, 2026
commit c92c681547fd479a7c6bd850738065a4a687eb47
76 changes: 29 additions & 47 deletions Doc/c-api/dict.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,12 @@ Dictionary objects

The first argument can be a :class:`dict` or a :class:`frozendict`.

.. note::

The operation is atomic in the :term:`free-threaded build`, if *key*
is a builtin 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.
Comment thread
kumaraditya303 marked this conversation as resolved.
Outdated

.. versionchanged:: next
Also accept :class:`frozendict`.

Expand Down Expand Up @@ -107,12 +113,9 @@ Dictionary objects

.. note::

In the :term:`free-threaded build`, key hashing via
:meth:`~object.__hash__` and key comparison via :meth:`~object.__eq__`
can execute arbitrary Python code, during which the :term:`per-object
lock` may be temporarily released. For built-in key types
(:class:`str`, :class:`int`, :class:`float`), the lock is not released
during comparison.
The operation is atomic in the :term:`free-threaded build`, if *key*
is a builtin 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 PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
Expand All @@ -121,15 +124,6 @@ Dictionary objects
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.

.. note::

In the :term:`free-threaded build`, key hashing via
:meth:`~object.__hash__` and key comparison via :meth:`~object.__eq__`
can execute arbitrary Python code, during which the :term:`per-object
lock` may be temporarily released. For built-in key types
(:class:`str`, :class:`int`, :class:`float`), the lock is not released
during comparison.


.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)

Expand All @@ -140,12 +134,9 @@ Dictionary objects

.. note::

In the :term:`free-threaded build`, key hashing via
:meth:`~object.__hash__` and key comparison via :meth:`~object.__eq__`
can execute arbitrary Python code, during which the :term:`per-object
lock` may be temporarily released. For built-in key types
(:class:`str`, :class:`int`, :class:`float`), the lock is not released
during comparison.
The operation is atomic in the :term:`free-threaded build`, if *key*
is a builtin 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 PyDict_DelItemString(PyObject *p, const char *key)
Expand All @@ -154,15 +145,6 @@ Dictionary objects
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.

.. note::

In the :term:`free-threaded build`, key hashing via
:meth:`~object.__hash__` and key comparison via :meth:`~object.__eq__`
can execute arbitrary Python code, during which the :term:`per-object
lock` may be temporarily released. For built-in key types
(:class:`str`, :class:`int`, :class:`float`), the lock is not released
during comparison.


.. c:function:: int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)

Expand All @@ -176,6 +158,12 @@ Dictionary objects

The first argument can be a :class:`dict` or a :class:`frozendict`.

.. note::

The operation is atomic in the :term:`free-threaded build`, if *key*
is a builtin 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.

.. versionadded:: 3.13

.. versionchanged:: next
Expand Down Expand Up @@ -305,6 +293,12 @@ Dictionary objects
These may refer to the same object: in that case you hold two separate
references to it.

.. note::

The operation is atomic in the :term:`free-threaded build`, if *key*
is a builtin 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.

.. versionadded:: 3.13


Expand All @@ -322,16 +316,13 @@ Dictionary objects
Similar to :meth:`dict.pop`, but without the default value and
not raising :exc:`KeyError` if the key is missing.

.. versionadded:: 3.13

.. note::

In the :term:`free-threaded build`, key hashing via
:meth:`~object.__hash__` and key comparison via :meth:`~object.__eq__`
can execute arbitrary Python code, during which the :term:`per-object
lock` may be temporarily released. For built-in key types
(:class:`str`, :class:`int`, :class:`float`), the lock is not released
during comparison.
The operation is atomic in the :term:`free-threaded build`, if *key*
is a builtin 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.

.. versionadded:: 3.13


.. c:function:: int PyDict_PopString(PyObject *p, const char *key, PyObject **result)
Expand All @@ -342,15 +333,6 @@ Dictionary objects

.. versionadded:: 3.13

.. note::

In the :term:`free-threaded build`, key hashing via
:meth:`~object.__hash__` and key comparison via :meth:`~object.__eq__`
can execute arbitrary Python code, during which the :term:`per-object
lock` may be temporarily released. For built-in key types
(:class:`str`, :class:`int`, :class:`float`), the lock is not released
during comparison.


.. c:function:: PyObject* PyDict_Items(PyObject *p)

Expand Down
11 changes: 6 additions & 5 deletions Doc/data/threadsafety.dat
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,10 @@ PyDict_CheckExact:atomic:
PyDict_New:atomic:

# Lock-free lookups - use _Py_dict_lookup_threadsafe(), no locking
PyDict_Contains:atomic:
# atomic with simple types
PyDict_Contains:shared:
PyDict_ContainsString:atomic:
PyDict_GetItemRef:atomic:
PyDict_GetItemRef:shared:
PyDict_GetItemStringRef:atomic:
PyDict_Size:atomic:
PyDict_GET_SIZE:atomic:
Expand All @@ -49,12 +50,12 @@ PyDict_Next:compatible:

# Single-item mutations - protected by per-object critical section
PyDict_SetItem:shared:
PyDict_SetItemString:shared:
PyDict_SetItemString:atomic:
PyDict_DelItem:shared:
PyDict_DelItemString:shared:
PyDict_DelItemString:atomic:
PyDict_SetDefaultRef:shared:
PyDict_Pop:shared:
PyDict_PopString:shared:
PyDict_PopString:atomic:

# Bulk reads - hold per-object lock for duration
PyDict_Clear:atomic:
Expand Down
Loading