[3.12] gh-125997: suggest efficient alternatives for `time.sleep(0)` (GH-128752)...

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 18e58249a81b084d99753f063db8a921c9e8b272..0c53e4bdc1c69476ad9f5d6dd6864220d227fc17 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -5058,6 +5058,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.
@@ -5149,7 +5151,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 db53296e2a56982decc2278f9ba3c7b493804e3b..ebc1ef1abac23b81f9ded7237ba8b4b0ab65b3b9 100644 (file)
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -367,6 +367,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
@@ -375,12 +377,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.
+
    .. versionchanged:: 3.5
       The function now sleeps at least *secs* even if the sleep is interrupted
       by a signal, except if the signal handler raises an exception (see