From ff5f05934db241dfafc604989b2de3487b09ca82 Mon Sep 17 00:00:00 2001 From: Alex Willmer Date: Sat, 6 Mar 2021 01:22:13 +0000 Subject: [PATCH] bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757) Previous wording implied that only the result of call N and N+1 could be meaningfully compared, whereas comparing call N and N+M is fine. --- Doc/library/time.rst | 8 ++++---- .../2021-03-04-22-53-03.bpo-43407.x570l5.rst | 4 ++++ 2 files changed, 8 insertions(+), 4 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2021-03-04-22-53-03.bpo-43407.x570l5.rst diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 143f84b565f..cfd67e87501 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -277,7 +277,7 @@ Functions Return the value (in fractional seconds) of a monotonic clock, i.e. a clock that cannot go backwards. The clock is not affected by system clock updates. The reference point of the returned value is undefined, so that only the - difference between the results of consecutive calls is valid. + difference between the results of two calls is valid. Use :func:`monotonic_ns` to avoid the precision loss caused by the :class:`float` type. @@ -306,7 +306,7 @@ Functions clock with the highest available resolution to measure a short duration. It does include time elapsed during sleep and is system-wide. The reference point of the returned value is undefined, so that only the difference between - the results of consecutive calls is valid. + the results of two calls is valid. Use :func:`perf_counter_ns` to avoid the precision loss caused by the :class:`float` type. @@ -334,7 +334,7 @@ Functions CPU time of the current process. It does not include time elapsed during sleep. It is process-wide by definition. The reference point of the returned value is undefined, so that only the difference between the results - of consecutive calls is valid. + of two calls is valid. Use :func:`process_time_ns` to avoid the precision loss caused by the :class:`float` type. @@ -626,7 +626,7 @@ Functions CPU time of the current thread. It does not include time elapsed during sleep. It is thread-specific by definition. The reference point of the returned value is undefined, so that only the difference between the results - of consecutive calls in the same thread is valid. + of two calls in the same thread is valid. Use :func:`thread_time_ns` to avoid the precision loss caused by the :class:`float` type. diff --git a/Misc/NEWS.d/next/Documentation/2021-03-04-22-53-03.bpo-43407.x570l5.rst b/Misc/NEWS.d/next/Documentation/2021-03-04-22-53-03.bpo-43407.x570l5.rst new file mode 100644 index 00000000000..615e3d01630 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-03-04-22-53-03.bpo-43407.x570l5.rst @@ -0,0 +1,4 @@ +Clarified that a result from :func:`time.monotonic`, +:func:`time.perf_counter`, :func:`time.process_time`, or +:func:`time.thread_time` can be compared with the result from any following +call to the same function - not just the next immediate call.