PEP 418: Replace misuse of precision with resolution
This commit is contained in:
Victor Stinner
parent
94fb568222
commit
c2f96995d0
56
pep-0418.txt
56
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:
|
|||
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms724408(v=vs.85).aspx>`_,
|
||||
`GetTickCount64()
|
||||
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms724411(v=vs.85).aspx>`_.
|
||||
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()
|
||||
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms683223(v=vs.85).aspx>`_.
|
||||
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()
|
||||
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms683237(v=vs.85).aspx>`_.
|
||||
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
|
||||
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms684943(v=vs.85).aspx>`_
|
||||
|
|
|
|||
Loading…
Reference in New Issue