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

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 6fec27bc6f68a2f6adb50dc5b8fae30602802322..2445b008eb5a7590df95311bf52dac054a8a68f0 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -5411,6 +5411,8 @@ information, consult your Unix manpages.
 The following scheduling policies are exposed if they are supported by the
 operating system.
 
+.. _os-scheduling-policy:
+
 .. data:: SCHED_OTHER
 
    The default scheduling policy.
@@ -5514,7 +5516,7 @@ operating system.
 
 .. function:: sched_yield()
 
-   Voluntarily relinquish the CPU.
+   Voluntarily relinquish the CPU. See :manpage:`sched_yield(2)` for details.
 
 
 .. function:: sched_setaffinity(pid, mask, /)

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 6265c2214eaa0dd955ed80a3b7bee3331b0f0851..804e2679027bd4e0c6077ba6023f40c760b31e72 100644 (file)
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -385,6 +385,8 @@ Functions
    The suspension time may be longer than requested by an arbitrary amount,
    because of the scheduling of other activity in the system.
 
+   .. rubric:: Windows implementation
+
    On Windows, if *secs* is zero, the thread relinquishes 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
@@ -393,12 +395,19 @@ Functions
    <https://learn.microsoft.com/windows-hardware/drivers/kernel/high-resolution-timers>`_
    which provides resolution of 100 nanoseconds. If *secs* is zero, ``Sleep(0)`` is used.
 
-   Unix implementation:
+   .. rubric:: Unix implementation
 
    * Use ``clock_nanosleep()`` if available (resolution: 1 nanosecond);
    * Or use ``nanosleep()`` if available (resolution: 1 nanosecond);
    * Or use ``select()`` (resolution: 1 microsecond).
 
+   .. note::
+
+      To emulate a "no-op", use :keyword:`pass` instead of ``time.sleep(0)``.
+
+      To voluntarily relinquish the CPU, specify a real-time :ref:`scheduling
+      policy <os-scheduling-policy>` and use :func:`os.sched_yield` instead.
+
    .. audit-event:: time.sleep secs
 
    .. versionchanged:: 3.5