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

Merged
lysnikolaou merged 9 commits into from
Jan 12, 2026
Merged

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

Changes from 1 commit
Commits
Show all changes
9 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
688b25a
Better explain lock-free and atomicity
lysnikolaou Dec 17, 2025
11e8072
Use correct ref for atomic
lysnikolaou Dec 18, 2025
8728c54
Merge branch 'main' into list-thread-safety-docs
lysnikolaou Dec 18, 2025
f09430b
Fix lint error
lysnikolaou Dec 18, 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
Next Next commit
Use correct ref for atomic
  • Loading branch information
@lysnikolaou
lysnikolaou committed Dec 18, 2025
commit 11e807236914b63b54b5bf6f24a58a95363ead77
6 changes: 3 additions & 3 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1467,7 +1467,7 @@ application).
threads and will not corrupt the list.
Comment on lines +1466 to +1467
Copy link
Copy Markdown
Contributor

@dpdani dpdani Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is safe in the sense that it won't corrupt the list, but should we also mention that it results in a race condition?


The following operations return new objects and appear
:term:`atomic <atomic operations>` to other threads:
:term:`atomic <atomic operation>` to other threads:

.. code-block::
:class: good
Expand All @@ -1477,15 +1477,15 @@ application).
lst.copy() # returns a shallow copy of the list

Methods that only operate on a single elements with no shifting required are
:term:`atomic <atomic operations>`:
:term:`atomic <atomic operation>`:

.. code-block::
:class: good

lst.append(x) # append to the end of the list, no shifting required
lst.pop() # pop element from the end of the list, no shifting required

The :meth:`~list.clear` method is also :term:`atomic <atomic operations>`.
The :meth:`~list.clear` method is also :term:`atomic <atomic operation>`.
Other threads cannot observe elements being removed.

The :meth:`~list.sort` method is not :term:`atomic <atomic operation>`.
Expand Down