GH-116738: document thread-safety of bisect

[nascheme]

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.

• Issue: Audit all built-in modules for thread safety #116738

---

📚 Documentation preview 📚: https://cpython-previews--136555.org.readthedocs.build/

[picnixz]

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

[nascheme]

Using "note" seems appropriate to me in this case. In the long term, I suggest it makes sense to have a thread-safety (or concurrency-safety) section for any module that has unusual rules (non-atomic functions, shared state). In the "warnings" doc, I added a "Concurrent safety of Context Managers" section to it. That's a case where the rules are quite complex and a dedicated section makes sense.

[kumaraditya303]

Suggested change

from threading import Thread, Barrier

this would fix lint CI

[miss-islington-app]

Thanks @nascheme for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-137221 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-137222 is a backport of this pull request to the 3.13 branch.

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot s390x Fedora Stable LTO + PGO 3.x (tier-3) has failed when building commit 5236b02.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1627/builds/893) and take a look at the build logs.
4. Check if the failure is related to this commit (5236b02) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1627/builds/893

Summary of the results of the build (if available):

Click to see traceback logs

remote: Enumerating objects: 9, done.        
remote: Counting objects:  14% (1/7)        
remote: Counting objects:  28% (2/7)        
remote: Counting objects:  42% (3/7)        
remote: Counting objects:  57% (4/7)        
remote: Counting objects:  71% (5/7)        
remote: Counting objects:  85% (6/7)        
remote: Counting objects: 100% (7/7)        
remote: Counting objects: 100% (7/7), done.        
remote: Compressing objects:  50% (1/2)        
remote: Compressing objects: 100% (2/2)        
remote: Compressing objects: 100% (2/2), done.        
remote: Total 9 (delta 5), reused 5 (delta 5), pack-reused 2 (from 1)        
From https://github.com/python/cpython
 * branch                    main       -> FETCH_HEAD
Note: switching to '5236b0281b91a874b14cf15f3fdef9b7beffb22f'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at 5236b0281b9 GH-116738: document thread-safety of bisect (GH-136555)
Switched to and reset branch 'main'

find: ‘build’: No such file or directory
find: ‘build’: No such file or directory
find: ‘build’: No such file or directory
find: ‘build’: No such file or directory
make[2]: [Makefile:3398: clean-retain-profile] Error 1 (ignored)
Python/ceval.c: In function ‘_PyEvalFramePushAndInit_Ex’:
Python/ceval.c:1916:38: warning: ‘stack_array’ may be used uninitialized [-Wmaybe-uninitialized]
 1916 |     _PyInterpreterFrame *new_frame = _PyEvalFramePushAndInit(
      |                                      ^~~~~~~~~~~~~~~~~~~~~~~~
 1917 |         tstate, func, locals,
      |         ~~~~~~~~~~~~~~~~~~~~~         
 1918 |         newargs, nargs, kwnames, previous
      |         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 1919 |     );
      |     ~                                 
Python/ceval.c:1839:1: note: by argument 4 of type ‘const union _PyStackRef *’ to ‘_PyEvalFramePushAndInit’ declared here
 1839 | _PyEvalFramePushAndInit(PyThreadState *tstate, _PyStackRef func,
      | ^~~~~~~~~~~~~~~~~~~~~~~
Python/ceval.c:1885:17: note: ‘stack_array’ declared here
 1885 |     _PyStackRef stack_array[8];
      |                 ^~~~~~~~~~~
test_denial_of_service_prevented_int_to_str (test.test_int.IntStrDigitLimitsTests.test_denial_of_service_prevented_int_to_str)
Regression test: ensure we fail before performing O(N**2) work. ... FAIL
test_denial_of_service_prevented_str_to_int (test.test_int.IntStrDigitLimitsTests.test_denial_of_service_prevented_str_to_int)
Regression test: ensure we fail before performing O(N**2) work. ... ok
test_disabled_limit (test.test_int.IntStrDigitLimitsTests.test_disabled_limit) ... ok
test_int_from_other_bases (test.test_int.IntStrDigitLimitsTests.test_int_from_other_bases) ... ok
test_int_max_str_digits_is_per_interpreter (test.test_int.IntStrDigitLimitsTests.test_int_max_str_digits_is_per_interpreter) ... ok
test_max_str_digits (test.test_int.IntStrDigitLimitsTests.test_max_str_digits) ... ok
test_max_str_digits_edge_cases (test.test_int.IntStrDigitLimitsTests.test_max_str_digits_edge_cases)
Ignore the +/- sign and space padding. ... ok
test_power_of_two_bases_unlimited (test.test_int.IntStrDigitLimitsTests.test_power_of_two_bases_unlimited)
The limit does not apply to power of 2 bases. ... ok
test_sign_not_counted (test.test_int.IntStrDigitLimitsTests.test_sign_not_counted) ... ok
test_underscores_ignored (test.test_int.IntStrDigitLimitsTests.test_underscores_ignored) ... ok
test_denial_of_service_prevented_int_to_str (test.test_int.IntSubclassStrDigitLimitsTests.test_denial_of_service_prevented_int_to_str)
Regression test: ensure we fail before performing O(N**2) work. ... ok
test_denial_of_service_prevented_str_to_int (test.test_int.IntSubclassStrDigitLimitsTests.test_denial_of_service_prevented_str_to_int)
Regression test: ensure we fail before performing O(N**2) work. ... ok
test_disabled_limit (test.test_int.IntSubclassStrDigitLimitsTests.test_disabled_limit) ... ok
test_int_from_other_bases (test.test_int.IntSubclassStrDigitLimitsTests.test_int_from_other_bases) ... ok
test_int_max_str_digits_is_per_interpreter (test.test_int.IntSubclassStrDigitLimitsTests.test_int_max_str_digits_is_per_interpreter) ... ok
test_max_str_digits (test.test_int.IntSubclassStrDigitLimitsTests.test_max_str_digits) ... ok
test_max_str_digits_edge_cases (test.test_int.IntSubclassStrDigitLimitsTests.test_max_str_digits_edge_cases)
Ignore the +/- sign and space padding. ... ok
test_power_of_two_bases_unlimited (test.test_int.IntSubclassStrDigitLimitsTests.test_power_of_two_bases_unlimited)
The limit does not apply to power of 2 bases. ... ok
test_sign_not_counted (test.test_int.IntSubclassStrDigitLimitsTests.test_sign_not_counted) ... ok
test_underscores_ignored (test.test_int.IntSubclassStrDigitLimitsTests.test_underscores_ignored) ... ok
test_basic (test.test_int.IntTestCases.test_basic) ... ok
test_error_message (test.test_int.IntTestCases.test_error_message) ... ok
test_int_base_bad_types (test.test_int.IntTestCases.test_int_base_bad_types)
Not integer types are not valid bases; issue16772. ... ok
test_int_base_indexable (test.test_int.IntTestCases.test_int_base_indexable) ... ok
test_int_base_limits (test.test_int.IntTestCases.test_int_base_limits)
Testing the supported limits of the int() base parameter. ... ok
test_int_memoryview (test.test_int.IntTestCases.test_int_memoryview) ... ok
test_int_returns_int_subclass (test.test_int.IntTestCases.test_int_returns_int_subclass) ... ok
test_int_subclass_with_index (test.test_int.IntTestCases.test_int_subclass_with_index) ... ok
test_int_subclass_with_int (test.test_int.IntTestCases.test_int_subclass_with_int) ... ok
test_intconversion (test.test_int.IntTestCases.test_intconversion) ... ok
test_invalid_signs (test.test_int.IntTestCases.test_invalid_signs) ... ok
test_issue31619 (test.test_int.IntTestCases.test_issue31619) ... ok
test_keyword_args (test.test_int.IntTestCases.test_keyword_args) ... ok
test_no_args (test.test_int.IntTestCases.test_no_args) ... ok
test_non_numeric_input_types (test.test_int.IntTestCases.test_non_numeric_input_types) ... ok
test_round_with_none_arg_direct_call (test.test_int.IntTestCases.test_round_with_none_arg_direct_call) ... ok
test_small_ints (test.test_int.IntTestCases.test_small_ints) ... ok
test_string_float (test.test_int.IntTestCases.test_string_float) ... ok
test_underscores (test.test_int.IntTestCases.test_underscores) ... ok
test_unicode (test.test_int.IntTestCases.test_unicode) ... ok
test_pylong_compute_powers (test.test_int.PyLongModuleTests.test_pylong_compute_powers) ... ok
test_pylong_int_divmod (test.test_int.PyLongModuleTests.test_pylong_int_divmod) ... ok
test_pylong_int_to_decimal (test.test_int.PyLongModuleTests.test_pylong_int_to_decimal) ... ok
test_pylong_int_to_decimal_2 (test.test_int.PyLongModuleTests.test_pylong_int_to_decimal_2) ... skipped "resource 'cpu' is not enabled"
test_pylong_misbehavior_error_path_from_str (test.test_int.PyLongModuleTests.test_pylong_misbehavior_error_path_from_str) ... ok
test_pylong_misbehavior_error_path_to_str (test.test_int.PyLongModuleTests.test_pylong_misbehavior_error_path_to_str) ... ok
test_pylong_roundtrip (test.test_int.PyLongModuleTests.test_pylong_roundtrip) ... ok
test_pylong_roundtrip_huge (test.test_int.PyLongModuleTests.test_pylong_roundtrip_huge) ... skipped "resource 'cpu' is not enabled"
test_pylong_str_to_int (test.test_int.PyLongModuleTests.test_pylong_str_to_int) ... ok
test_whitebox_dec_str_to_int_inner_failsafe (test.test_int.PyLongModuleTests.test_whitebox_dec_str_to_int_inner_failsafe) ... skipped "resource 'cpu' is not enabled"
test_whitebox_dec_str_to_int_inner_monster (test.test_int.PyLongModuleTests.test_whitebox_dec_str_to_int_inner_monster) ... ok

======================================================================
FAIL: test_denial_of_service_prevented_int_to_str (test.test_int.IntStrDigitLimitsTests.test_denial_of_service_prevented_int_to_str)
Regression test: ensure we fail before performing O(N**2) work.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.x.cstratak-fedora-stable-s390x.lto-pgo/build/Lib/test/test_int.py", line 611, in test_denial_of_service_prevented_int_to_str
    self.assertLessEqual(sw_fail_huge.seconds, sw_convert.seconds/2)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 0.3910390669479966 not less than or equal to 0.01879003643989563

----------------------------------------------------------------------
Ran 51 tests in 1.646s

FAILED (failures=1, skipped=3)
test test_int failed
make: *** [Makefile:1032: profile-run-stamp] Error 2