GH-116738: document thread-safety of bisect #136555
Draft
+89
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
picnixz
reviewed
Jul 11, 2025
There was a problem hiding this comment.
Possible suggestions:
- Use a
.. note::if you think users should know about it. - Use a
.. warning::if you think users should be careful about it. - Do not use either of them if you think it's just good that users know about it (a note or a warning is quite visible in the sense that it creates a box where the entire content is inside that box).
- Use a subsection about thread-safetiness. Or use a small warning box just saying that the functions are not thread-safe, and add a link to a section at the bottom of the page that contains more detailed explanations.
cc @hugovk
Comment on lines
+27
to
+35
| .. note:: | ||
|
|
||
| The functions in this module are not thread-safe. If multiple threads | ||
| concurrently use :mod:`bisect` functions on the same sequence, this | ||
| may result in undefined behaviour. Likewise, if the provided sequence | ||
| is mutated by a different thread while a :mod:`bisect` function | ||
| is operating on it, the result is undefined. For example, using | ||
| :py:func:`~bisect.insort_left` on the same list from multiple threads | ||
| may result in the list becoming unsorted. |
There was a problem hiding this comment.
Suggested change
| .. note:: | |
| The functions in this module are not thread-safe. If multiple threads | |
| concurrently use :mod:`bisect` functions on the same sequence, this | |
| may result in undefined behaviour. Likewise, if the provided sequence | |
| is mutated by a different thread while a :mod:`bisect` function | |
| is operating on it, the result is undefined. For example, using | |
| :py:func:`~bisect.insort_left` on the same list from multiple threads | |
| may result in the list becoming unsorted. | |
| .. note:: | |
| The functions in this module are not thread-safe. If multiple threads | |
| concurrently use :mod:`bisect` functions on the same sequence, this | |
| may result in undefined behaviour. Likewise, if the provided sequence | |
| is mutated by a different thread while a :mod:`bisect` function | |
| is operating on it, the result is undefined. For example, using | |
| :py:func:`~bisect.insort_left` on the same list from multiple threads | |
| may result in the list becoming unsorted. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I don't think it makes sense to make these functions thread-safe. They are already unsafe when used in the default build. And, given that they can operate on any sequence object, trying to lock the sequence object doesn't make sense.
I added a unit test because I believe these functions should not crash or produce TSAN warnings when they are used on a sequence being mutated in another thread.
📚 Documentation preview 📚: https://cpython-previews--136555.org.readthedocs.build/