bpo-37205: time.perf_counter() and time.monotonic() are system-wide (GH-23284)

time.perf_counter() on Windows and time.monotonic() on macOS are now
system-wide. Previously, they used an offset computed at startup to
reduce the precision loss caused by the float type. Use
time.perf_counter_ns() and time.monotonic_ns() added in Python 3.7 to
avoid this precision loss.

1 files changed, 36 insertions, 7 deletions

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index cff6320..143f84b 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -166,6 +166,9 @@ Functions
    Return the time of the specified clock *clk_id*.  Refer to
    :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
 
+   Use :func:`clock_gettime_ns` to avoid the precision loss caused by the
+   :class:`float` type.
+
    .. availability:: Unix.
 
    .. versionadded:: 3.3
@@ -185,6 +188,9 @@ Functions
    Set the time of the specified clock *clk_id*.  Currently,
    :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
 
+   Use :func:`clock_settime_ns` to avoid the precision loss caused by the
+   :class:`float` type.
+
    .. availability:: Unix.
 
    .. versionadded:: 3.3
@@ -273,10 +279,17 @@ Functions
    The reference point of the returned value is undefined, so that only the
    difference between the results of consecutive calls is valid.
 
+   Use :func:`monotonic_ns` to avoid the precision loss caused by the
+   :class:`float` type.
+
    .. versionadded:: 3.3
+
    .. versionchanged:: 3.5
       The function is now always available and always system-wide.
 
+   .. versionchanged:: 3.10
+      On macOS, the function is now system-wide.
+
 
 .. function:: monotonic_ns() -> int
 
@@ -295,8 +308,14 @@ Functions
    point of the returned value is undefined, so that only the difference between
    the results of consecutive calls is valid.
 
+   Use :func:`perf_counter_ns` to avoid the precision loss caused by the
+   :class:`float` type.
+
    .. versionadded:: 3.3
 
+   .. versionchanged:: 3.10
+      On Windows, the function is now system-wide.
+
 .. function:: perf_counter_ns() -> int
 
    Similar to :func:`perf_counter`, but return time as nanoseconds.
@@ -317,6 +336,9 @@ Functions
    returned value is undefined, so that only the difference between the results
    of consecutive calls is valid.
 
+   Use :func:`process_time_ns` to avoid the precision loss caused by the
+   :class:`float` type.
+
    .. versionadded:: 3.3
 
 .. function:: process_time_ns() -> int
@@ -581,6 +603,17 @@ Functions
    :class:`struct_time` object is returned, from which the components
    of the calendar date may be accessed as attributes.
 
+   Use :func:`time_ns` to avoid the precision loss caused by the :class:`float`
+   type.
+
+
+.. function:: time_ns() -> int
+
+   Similar to :func:`~time.time` but returns time as an integer number of nanoseconds
+   since the epoch_.
+
+   .. versionadded:: 3.7
+
 
 .. function:: thread_time() -> float
 
@@ -595,6 +628,9 @@ Functions
    returned value is undefined, so that only the difference between the results
    of consecutive calls in the same thread is valid.
 
+   Use :func:`thread_time_ns` to avoid the precision loss caused by the
+   :class:`float` type.
+
    .. availability::  Windows, Linux, Unix systems supporting
       ``CLOCK_THREAD_CPUTIME_ID``.
 
@@ -608,13 +644,6 @@ Functions
    .. versionadded:: 3.7
 
 
-.. function:: time_ns() -> int
-
-   Similar to :func:`~time.time` but returns time as an integer number of nanoseconds
-   since the epoch_.
-
-   .. versionadded:: 3.7
-
 .. function:: tzset()
 
    Reset the time conversion rules used by the library routines. The environment