[Python-checkins] peps: PEP 418: Replace misuse of precision with resolution
victor.stinner
python-checkins at python.org
Tue Apr 24 00:30:30 CEST 2012
http://hg.python.org/peps/rev/72793ac1a4a8
changeset: 4299:72793ac1a4a8
user: Victor Stinner <victor.stinner at gmail.com>
date: Tue Apr 24 00:30:23 2012 +0200
summary:
PEP 418: Replace misuse of precision with resolution
files:
pep-0418.txt | 56 +++++++++++++++++++--------------------
1 files changed, 27 insertions(+), 29 deletions(-)
diff --git a/pep-0418.txt b/pep-0418.txt
--- a/pep-0418.txt
+++ b/pep-0418.txt
@@ -31,7 +31,7 @@
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 @@
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 @@
* 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 @@
* 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 @@
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 @@
^^^^^^^^^^^^
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 @@
* 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 @@
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 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 @@
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 @@
<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 @@
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 @@
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 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 @@
^^^^^^^^^^^^^^^^^^^
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 @@
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 @@
* 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 @@
* 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 @@
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 @@
* 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>`_
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list