gh-125997: suggest efficient alternatives for time.sleep(0)

[picnixz]

After a discussion with Victor and because #128274 is not convincing enough, we decide to:

• keep the current behaviour of time.sleep(), and
• document efficient (and probably semantically more correct) alternatives for time.sleep(0).

See #125997 (comment) for more details.

• Issue: time.sleep(0) is slower on Python 3.11 than on Python 3.10 #125997

---

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

[picnixz]

@hauntsaninja and @charles-cooper: I would appreciate if you can share your thoughts on those suggestions as you were also involved in the other PR's discussion.

[charles-cooper]

i think it's interesting that select() is already mentioned as a possible implementation for time.sleep(), so maybe the approach in #128274 is valid actually.

https://github.com/python/cpython/pull/128752/files#diff-6203e0fc16084e67996c5bdd5e1caf4cc4699f67fde5da0abebe2ca239278ed4R402

besides that, i would just mention that clock_nanosleep may sleep at least 50us on linux. (i mean this is arguably a linux bug, but it is kind of surprising to users that sleep(0) sleeps a lot longer than one might expect).

[picnixz]

sleep(0) sleeps a lot longer than one might expect

Actually, sleep() does not provide any guarantee that it will sleep exactly of the amount being requested. Granted it's surprising, but it's still documented in man nanosleep and others (sleep says "sleep() causes the calling thread to sleep either until the number of real-time seconds specified in seconds have elapsed" without saying "at least until" but I think it should be understood like this).

(), so maybe the approach in #128274 is valid actually.

While it's mentioned like that, I think it's wrong in the first place to rely on select() to implement sleep() (as I said on the issue). But since it's documented as a fallback, I think we should live with this discrepency, but we shouldn't make the "correct" implementation uses something else (namely "select()"). Even if the correct choice (clock_nanosleep/nanosleep) looks "buggy", that's what the caller should expect (I mean, I would expect time.sleep to rely on sleep-like functions).

Another solution is to check if we're on FreeBSD or not, but this makes maintainance harder. Also, for those reading the PR only, the sleep gap only happens at t = 0 and not at t = 1e-9 (for t = 1e-9, select() is still as slow as clock_nanosleep()). It's just that at t = 0, it returns immediately. So we can also just skip t = 0 calls on non-Windows platforms directly.

[hauntsaninja]

Thanks, this PR looks great, I think this is right approach.

I would not document current implementation choices of default Linux scheduler, especially since we've currently only had one report in >2 years. (If it does come up again, we can mention os.sched_setscheduler / PR_SET_TIMERSLACK)

[vstinner]

LGTM

[ZeroIntensity]

Instead of just repeating "relinquish the CPU" from sched_yield's docs, I think it's worth being more specific. Something like "allow other threads to execute" and/or "temporarily release the GIL" could be useful.

The other issue here is that sched_yield is specific to Unix systems--what are Windows users supposed to use if they want to explicitly let another thread take the GIL, if not time.sleep()?

[picnixz]

They use time.sleep(0). The note is for the Unix section. On Windows, Sleep(0) relinquishes the CPU: https://learn.microsoft.com/en-gb/windows/win32/api/synchapi/nf-synchapi-sleep?redirectedfrom=MSDN.

A value of zero causes the thread to relinquish the remainder of its time slice to any other thread that is ready to run. If there are no other threads ready to run, the function returns immediately, and the thread continues execution. Windows XP: A value of zero causes the thread to relinquish the remainder of its time slice to any other thread of equal priority that is ready to run. If there are no other threads of equal priority ready to run, the function returns immediately, and the thread continues execution. This behavior changed starting with Windows Server 2003.

[picnixz]

Maybe I can add "On non-Windows platforms" if you want?

[ZeroIntensity]

Ah, got it. I didn't see that this was explicitly the Unix section, I thought you were just reformatting. (I still do think we should mention the GIL here, but it's up to you.)

Anyways, this is out of the scope of this PR, but this kind of situation probably isn't ideal for users. You have to maintain two code paths: one to call time.sleep(0) on Windows, and then os.sched_yield on Linux. Do you think it's a good idea to add a dedicated function for that in a follow-up issue?

[picnixz]

I don't know. I don't know much about Windows users but maybe os.sched_yield() could, call Sleep(0) on Windows? Considering that no one ever complained about this specifically (what users complain is that it takes too much time, and probably don't really care about what we're actually doing behind the scene), I think we shouldn't bother for now.

[ZeroIntensity]

It's probably because it's difficult to notice--in practice, people use time.sleep(0) on both systems, because the performance issue on Linux generally isn't clear, especially for multithreaded programs. My theory is that providing a dedicated function will get people to notice the issue more. I'm speculating though!

[picnixz]

Maybe we could open a DPO thread for that. Namely, whether to provide a Windows-equivalent of os.sched_yield() but that does not have the meaning of a scheduling policy.

[vstinner]

IMO you're trying to solve a non-existent problem. time.sleep(0) is efficient and does what the developer expects. It's just that os.sched_yield() can be even more efficient on Linux. IMO time.sleep(0) is the portable "pass the CPU to another thread", even if it's not "optimal" (on Linux).

[vstinner]

If you really need the most efficient "yield":

if hasattr(os, 'sched_yield'):
    def portable_efficient_yield():
        os.sched_yield()
else:
    def portable_efficient_yield():
        time.sleep(0)

[ZeroIntensity]

Yeah, I made a DPO thread, feel free to post concerns there: https://discuss.python.org/t/platform-agnostic-yielding-of-the-gil/77006/

I'm in favor of a function other than time.sleep(0) for yielding, because it's not particularly clear that sleep(0) would actually do something useful, but we're killing two birds with one stone because of the performance.

[picnixz]

@vstinner I plan to merge this PR with no commit message and the current PR title. I don't want to expand more on the rationale in the commit and I think it's better to look at the issue directly. WDYT?

[vstinner]

LGTM. Go ahead.

[miss-islington-app]

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

[miss-islington-app]

Thanks @picnixz for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @picnixz, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker f4afaa6f1190fbbea3e27c590096951d8ffdfb71 3.12

[bedevere-app]

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

[bedevere-app]

GH-128985 is a backport of this pull request to the 3.12 branch.