Skip to content

gh-142518: Document thread-safety guarantees of list operations #142519

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
lysnikolaou wants to merge 5 commits into
base: main
Choose a base branch
from
Open

gh-142518: Document thread-safety guarantees of list operations #142519

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fd400f0
gh-142518: Document thread-safety guarantees of list operations
lysnikolaou Dec 4, 2025
38483c9
Address feedback; add more details
lysnikolaou Dec 11, 2025
cc5c2f0
Merge branch 'main' into list-thread-safety-docs
lysnikolaou Dec 11, 2025
2292896
Add everything to code blocks
lysnikolaou Dec 11, 2025
2b9e711
Improve wording around atomicity; specify exact types
lysnikolaou Dec 11, 2025
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
Improve wording around atomicity; specify exact types
  • Loading branch information
@lysnikolaou
lysnikolaou committed Dec 11, 2025
commit 2b9e711b248e719873217173694d599d59aa60d6
25 changes: 12 additions & 13 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1475,21 +1475,20 @@ application).
lst[i:j] = iterable

The :meth:`~list.index` and :meth:`~list.count` methods, and the ``in``
operator, iterate the list without holding a lock. They are safe to call
operator, iterate the list without holding a lock. They are safe to call
concurrently but may return results affected by concurrent modifications.

:meth:`~list.extend` is always atomic with respect to the target list.
However, the operation is fully atomic only when the iterable that's passed
to ``extend`` is a :class:`list`, a :class:`tuple`, a :class:`set`, a
:class:`frozenset`, a :class:`dict` or a
:ref:`dictionary view object <dict-views>`. Otherwise, an iterator is
created which can be concurrently modified by another thread. The same
applies to inplace concatenation of list with other iterables when using
``lst += iterable``.

Similarly, assigning to a list slice with ``lst[i:j] = iterable`` is always
atomic with respect to the target list, but ``iterable`` is only locked when
it is also a :class:`list`.
:meth:`~list.extend` is safe to call from multiple threads. However, the
operation is fully atomic only when the iterable that's passed to ``extend``
is a :class:`list`, a :class:`tuple`, a :class:`set`, a :class:`frozenset`,
a :class:`dict` or a :ref:`dictionary view object <dict-views>` (but not
their subclasses). Otherwise, an iterator is created which can be
concurrently modified by another thread. The same applies to inplace
concatenation of list with other iterables when using ``lst += iterable``.

Similarly, assigning to a list slice with ``lst[i:j] = iterable`` is safe
to call from multiple threads, but ``iterable`` is only locked when it is
also a :class:`list` (but not its subclasses).

Operations that involve multiple accesses, as well as iteration, are not
atomic. For example:
Expand Down
Loading