From c2f96995d0dfdcb1ac3fe255448fc577e3633905 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 24 Apr 2012 00:30:23 +0200 Subject: [PATCH] PEP 418: Replace misuse of precision with resolution --- pep-0418.txt | 56 +++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 29 deletions(-) diff --git a/pep-0418.txt b/pep-0418.txt index be22b8753..b7bdf1ec1 100644 --- a/pep-0418.txt +++ b/pep-0418.txt @@ -31,7 +31,7 @@ instead to not be affected by system time updates: To measure the performance of a function, ``time.clock()`` can be used but it is very different on Windows and on Unix. On Windows, ``time.clock()`` includes time elapsed during sleep, whereas it does -not on Unix. ``time.clock()`` precision is very good on Windows, but +not on Unix. ``time.clock()`` resolution is very good on Windows, but very bad on Unix. The new ``time.perf_counter()`` function should be used instead to always get the most precise performance counter with a portable behaviour (ex: include time spend during sleep). @@ -39,18 +39,18 @@ portable behaviour (ex: include time spend during sleep). Until now, Python did not provide directly a portable function to measure CPU time. ``time.clock()`` can be used on Unix, but it has bad -precision. ``resource.getrusage()`` or ``os.times()`` can also be +resolution. ``resource.getrusage()`` or ``os.times()`` can also be used on Unix, but they require to compute the sum of time spent in kernel space and user space. The new ``time.process_time()`` function acts as a portable counter that always measures CPU time (excluding time elapsed during sleep) and has the best available -precision. +resolution. Each operating system implements clocks and performance counters differently, and it is useful to know exactly which function is used -and some properties of the clock like its resolution and its -precision. The new ``time.get_clock_info()`` function gives access to -all available information about each Python time function. +and some properties of the clock like its resolution. The new +``time.get_clock_info()`` function gives access to all available +information about each Python time function. New functions: @@ -67,7 +67,7 @@ Users of new functions: * time.perf_counter(): trace and timeit modules, pybench program * time.process_time(): profile module * time.get_clock_info(): pybench program to display information about the - timer like the precision or the resolution + timer like the resolution The ``time.clock()`` function is deprecated because it is not portable: it behaves differently depending on the operating system. @@ -126,8 +126,6 @@ Return a dictionary with the following keys: * Optional keys: - * ``"precision"`` (float): precision in seconds of the clock - reported by the operating system. * ``"is_adjusted"`` (bool): True if the clock is adjusted (e.g. by a NTP daemon). @@ -189,14 +187,14 @@ Pseudo-code [#pseudo]_:: On Windows, ``QueryPerformanceCounter()`` is not used even though it -has a better precision than ``GetTickCount()``. It is not reliable +has a better resolution than ``GetTickCount()``. It is not reliable and has too many issues. time.perf_counter() ^^^^^^^^^^^^^^^^^^^ -Performance counter with the highest available precision to measure a +Performance counter 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 @@ -385,7 +383,7 @@ time.clock() ^^^^^^^^^^^^ On Unix, return the current processor time as a floating point number -expressed in seconds. It is process-wide by definition. The precision, +expressed in seconds. It is process-wide by definition. The resolution, 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 @@ -523,7 +521,7 @@ This includes at least: * time.MONOTONIC: clock cannot go backward * time.STEADY: clock rate is steady * time.ADJUSTED: clock may be adjusted, for example by NTP -* time.HIGHRES: clock with the highest precision +* time.HIGHRES: clock with the highest resolution It returns a clock object with a .now() method returning the current time. The clock object is annotated with metadata describing the clock feature set; @@ -931,7 +929,7 @@ timeGetTime() 1 ms No Yes ? The "C Resolution" column is the resolution of the underlying C structure. -Examples of clock precision on x86_64: +Examples of clock resolution on x86_64: ========================= ================ ============= ================= Name Operating system OS Resolution Python Resolution @@ -978,7 +976,7 @@ CLOCK_MONOTONIC, CLOCK_MONOTONIC_RAW, CLOCK_BOOTTIME ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW represent monotonic time since -some unspecified starting point. They cannot be set. The precision +some unspecified starting point. They cannot be set. The resolution can be read using ``clock_getres()``. Documentation: refer to the manual page of your operating system. @@ -1031,7 +1029,7 @@ Windows: QueryPerformanceCounter High-resolution performance counter. It is monotonic. The frequency of the counter can be read using QueryPerformanceFrequency(). -The precision is 1 / QueryPerformanceFrequency(). +The resolution is 1 / QueryPerformanceFrequency(). It has a much higher resolution, but has lower long term precision than GetTickCount() and timeGetTime() clocks. For example, it will @@ -1097,7 +1095,7 @@ not adjusted by SetSystemTimeAdjustment(). MSDN documentation: `_, `GetTickCount64() `_. -The precision can be read using GetSystemTimeAdjustment(). +The resolution can be read using GetSystemTimeAdjustment(). The elapsed time retrieved by GetTickCount() or GetTickCount64() includes time the system spends in sleep or hibernation. @@ -1153,7 +1151,7 @@ CLOCK_HIGHRES is the nonadjustable, high-resolution clock. For timers created with a clockid_t value of CLOCK_HIGHRES, the system will attempt to use an optimal hardware source. -The precision of CLOCK_HIGHRES can be read using ``clock_getres()``. +The resolution of CLOCK_HIGHRES can be read using ``clock_getres()``. Solaris: gethrtime ^^^^^^^^^^^^^^^^^^ @@ -1191,7 +1189,7 @@ time() 1 sec Yes Yes The "C Resolution" column is the resolution of the underlying C structure. -Examples of clock precision on x86_64: +Examples of clock resolution on x86_64: ========================= ================ ============= ================= Name Operating system OS Resolution Python Resolution @@ -1219,7 +1217,7 @@ Windows: GetSystemTimeAsFileTime ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The system time can be read using GetSystemTimeAsFileTime(), ftime() and -time(). The precision of the system time can be read using +time(). The resolution of the system time can be read using GetSystemTimeAdjustment(). Read the `GetSystemTimeAsFileTime() documentation @@ -1231,7 +1229,7 @@ System time on UNIX ^^^^^^^^^^^^^^^^^^^ gettimeofday(), ftime(), time() and clock_gettime(CLOCK_REALTIME) return -the system time. The precision of CLOCK_REALTIME can be read using +the system time. The resolution of CLOCK_REALTIME can be read using clock_getres(). The system time can be set using settimeofday() or @@ -1265,7 +1263,7 @@ clock() \- Yes on Windows, No otherwise No The "C Resolution" column is the resolution of the underlying C structure. -Examples of clock precision on x86_64: +Examples of clock resolution on x86_64: ========================= ================ ============= =================== Name Operating system OS Resolution Python Resolution @@ -1304,10 +1302,10 @@ Functions * Windows: `GetProcessTimes() `_. - The precision can be read using GetSystemTimeAdjustment(). + The resolution can be read using GetSystemTimeAdjustment(). * clock_gettime(CLOCK_PROCESS_CPUTIME_ID): High-resolution per-process - timer from the CPU. The precision can be read using clock_getres(). -* clock(). The precision is 1 / CLOCKS_PER_SEC. + timer from the CPU. The resolution can be read using clock_getres(). +* clock(). The resolution is 1 / CLOCKS_PER_SEC. * Windows: The elapsed wall-clock time since the start of the process (elapsed time in seconds times CLOCKS_PER_SEC). Include @@ -1317,7 +1315,7 @@ Functions * getrusage(RUSAGE_SELF) returns a structure of resource usage of the currenet process. ru_utime is user CPU time and ru_stime is the system CPU time. -* times(): structure of process times. The precision is 1 / ticks_per_seconds, +* times(): structure of process times. The resolution is 1 / ticks_per_seconds, where ticks_per_seconds is sysconf(_SC_CLK_TCK) or the HZ constant. Python source code includes a portable library to get the process time (CPU @@ -1346,7 +1344,7 @@ GetThreadTimes() 100 ns No ? The "C Resolution" column is the resolution of the underlying C structure. -Examples of clock precision on x86_64: +Examples of clock resolution on x86_64: ========================= ================ ============= ================= Name Operating system OS Resolution Python Resolution @@ -1369,10 +1367,10 @@ Functions * Windows: `GetThreadTimes() `_. - The precision can be read using GetSystemTimeAdjustment(). + The resolution can be read using GetSystemTimeAdjustment(). * clock_gettime(CLOCK_THREAD_CPUTIME_ID): Thread-specific CPU-time clock. It uses a number of CPU cycles, not a number of seconds. - The precision can be read using of clock_getres(). + The resolution can be read using of clock_getres(). See also the `QueryThreadCycleTime() function `_