From 539ae6b9ea180ad54e8daa1f2bdb791db4f6e689 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Sun, 15 Apr 2012 15:39:48 +0200 Subject: [PATCH] PEP 418: Add last comments * Indicate if a clock is system-wide or process-wide * Add time.metronomic() alternative name * Explain why "steady" name was not chosen --- pep-0418.txt | 57 +++++++++++++++++++++++++++++----------------------- 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/pep-0418.txt b/pep-0418.txt index 8a05c8bb0..957550435 100644 --- a/pep-0418.txt +++ b/pep-0418.txt @@ -111,10 +111,17 @@ Return a dictionary with the following keys: time.monotonic() ^^^^^^^^^^^^^^^^ -Monotonic clock, cannot go backward. It 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. +Monotonic clock, cannot go backward. It 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. + +On Windows older than Vista, ``time.monotonic()`` detects ``GetTickCount()`` +integer overflow (32 bits, roll-over after 49.7 days): it increases a delta by +2\ :sup:`32` each time than an overflow is detected. The delta is stored in +the process-local state and so the value of ``time.monotonic()`` may be +different in two Python processes running for more than 49 days. On more recent +versions of Windows and on other operating systems, ``time.monotonic()`` is +system-wide. Availability: Windows, Mac OS X, Unix, Solaris. Not available on GNU/Hurd. @@ -160,21 +167,14 @@ On Windows, ``QueryPerformanceCounter()`` is not used even though it has a better precision than ``GetTickCount()``. It is not reliable and has too many issues. -``time.monotonic()`` detects ``GetTickCount()`` integer overflow (32 bits, -roll-over after 49.7 days): it increases a delta by 2\ :sup:`32` each time -than an overflow is detected. The delta is stored in the process-local -state and so the value of ``time.monotonic()`` may be different in two -Python processes running for more than 49 days. - time.perf_counter() ^^^^^^^^^^^^^^^^^^^ -Performance counter used for benchmarking. It is monotonic, -i.e. cannot go backward. It does include time elapsed during sleep. -The reference point of the returned value is undefined, so that only -the difference between the results of consecutive calls is valid and -is number of seconds. +Performance counter used for benchmarking. It is monotonic, i.e. cannot go +backward. 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 and is number of seconds. Pseudo-code:: @@ -208,10 +208,10 @@ Pseudo-code:: time.process_time() ^^^^^^^^^^^^^^^^^^^ -Process time used for profiling: sum of the kernel and user-space CPU -time. It does not include time elapsed during sleep. The reference -point of the returned value is undefined, so that only the difference -between the results of consecutive calls is valid. +Process time used for profiling: sum of the kernel and user-space CPU time. 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. Pseudo-code [#pseudo]_:: @@ -264,7 +264,7 @@ time.time() The system time is the "wall clock". It can be set manually by the system administrator or automatically by a NTP daemon. It can jump -backward and forward. It is not monotonic. +backward and forward. It is system-wide but not monotonic. It is available on all platforms and cannot fail. @@ -347,15 +347,15 @@ time.clock() ^^^^^^^^^^^^ On Unix, return the current processor time as a floating point number -expressed in seconds. The precision, and in fact the very definition -of the meaning of "processor time", depends on that of the C function -of the same name, but in any case, this is the function to use for -benchmarking Python or timing algorithms. +expressed in seconds. It is process-wide by definition. The precision, and in +fact the very definition of the meaning of "processor time", depends on that of +the C function of the same name, but in any case, this is the function to use +for benchmarking Python or timing algorithms. On Windows, this function returns wall-clock seconds elapsed since the first call to this function, as a floating point number, based on the Win32 function ``QueryPerformanceCounter()``. The resolution is -typically better than one microsecond. +typically better than one microsecond. It is system-wide. Pseudo-code [#pseudo]_:: @@ -391,12 +391,19 @@ Other names for new functions time.monotonic(): * time.counter() +* time.metronomic() * time.seconds() * time.steady() * time.timeout_clock() * time.wallclock(): it is not the system time aka the "wall clock", but a monotonic clock with an unspecified starting point +"steady" is ambiguous: it means different things to different people. For +example, on Linux, CLOCK_MONOTONIC is adjusted. If we uses the real time as the +reference clock, we may say that CLOCK_MONOTONIC is steady. But +CLOCK_MONOTONIC gets suspended on system suspend, whereas real time includes +any time spent in suspend. + The name "time.try_monotonic()" was also proposed when time.monotonic() was falling back to the system clock when no monotonic clock was available.