update docs

python · picnixz · Dec 26, 2024 · Dec 26, 2024 · Dec 26, 2024 · Dec 26, 2024
commit ecb96365160bc01938eb663a88ca6cfe97928716
diff --git 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,20 @@ 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
+
+   If *secs* is zero, ``select()`` is used. Otherwise:
 
    * Use ``clock_nanosleep()`` if available (resolution: 1 nanosecond);
    * Or use ``nanosleep()`` if available (resolution: 1 nanosecond);
    * Or use ``select()`` (resolution: 1 microsecond).
 
+   .. note::
+
+      To voluntarily relinquish the CPU, specify a read-time :ref:`scheduling
+      policy <os-scheduling-policy>` (see :manpage:`sched_yield(2)`) and use
+      :func:`os.sched_yield` instead.
+
    .. audit-event:: time.sleep secs
 
    .. versionchanged:: 3.5
@@ -413,6 +423,10 @@ Functions
    .. versionchanged:: 3.13
       Raises an auditing event.
 
+   .. versionchanged:: next
+      On Unix, ``time.sleep(0)`` always uses ``select()``, even if the
+      ``clock_nanosleep()`` or ``nanosleep()`` functions are available.
+
 .. index::
    single: % (percent); datetime format