PEP 418: Add time.clock(), fix typos, mention issue #14309

pep-0418.txt

@@ -84,7 +84,7 @@ 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 only the
-difference of consecutive calls is valid.
+difference between consecutive calls is valid.
 
 Availability: Windows, Mac OS X, Unix.
 
@@ -185,6 +185,43 @@ Pseudo-code [#pseudo]_::
             _time.sleep(seconds)
 
 
+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.
+
+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.
+
+Pseudo-code [#pseudo]_::
+
+    if os.name == 'nt':
+        def clock():
+            if clock.use_performance_counter:
+                if clock.perf_frequency is None:
+                    try:
+                        clock.perf_frequency = float(_time.QueryPerformanceFrequency())
+                    except OSError:
+                        # QueryPerformanceFrequency() fails if the installed
+                        # hardware does not support a high-resolution performance
+                        # counter
+                        clock.use_performance_counter = False
+                    else:
+                        return _time.QueryPerformanceCounter() / clock.perf_frequency
+                else:
+                    return _time.QueryPerformanceCounter() / clock.perf_frequency
+            return _time.clock()
+        clock.use_performance_counter = True
+        clock.perf_frequency = None
+    else:
+        clock = _time.clock
+
+
 time.get_clock_info(name)
 -------------------------
 
@@ -224,7 +261,7 @@ is 1 nanosecond.
 Accuracy
 --------
 
-The accuracy is the effective smallest difference of two timestamps of the
+The accuracy is the effective smallest difference between two timestamps of the
 clock. It does not reflect the stability the clock rate. For example,
 QueryPerformanceCounter() has a good accuracy but is known to not have a steady
 rate.
@@ -260,7 +297,7 @@ Hardware clocks
   processor clock cycle, but now the rate is usually constant (even if the
   processor changes frequency) and usually equals the maximum processor
   frequency. Multiple cores having different TSC values. Hibernation of system
-  will reset TSC value. The instructor RDTSC can be used to read this counter.
+  will reset TSC value. The RDTSC instruction can be used to read this counter.
   CPU frequency scaling for power saving.
 * ACPI PMTMR (power management timer): ACPI 24-bit timer with a frequency
   of 3.5 MHz (3,579,545 Hz). HPET can cause around 3 seconds of drift per day.
@@ -635,7 +672,7 @@ clock_settime(CLOCK_REALTIME).
 Process time
 ------------
 
-The process time cannot be set. It is not monotonic: the clocks stop while the
+The process time cannot be set. It It is not monotonic: the clocks stop while the
 process is idle.
 
 =========================  ===============
@@ -965,8 +1002,8 @@ Issues:
    use another clock, display an error, or do something else
 
 
-One function choosing the clock from a list of constrains
----------------------------------------------------------
+One function choosing the clock from a list of constraints
+----------------------------------------------------------
 
 ``time.get_clock(*flags)`` with the following flags:
 
@@ -1044,25 +1081,25 @@ Deferred API: time.perf_counter()
 =================================
 
 Performance counter used for benchmarking and profiling. The reference point of
-the returned value is undefined so only the difference of consecutive calls is
+the returned value is undefined so only the difference between consecutive calls is
 valid and is number of seconds.
 
 Pseudo-code::
 
     def perf_counter():
         if perf_counter.use_performance_counter:
-            if perf_counter.cpu_frequency is None:
+            if perf_counter.perf_frequency is None:
                 try:
-                    perf_counter.cpu_frequency = float(_time.QueryPerformanceFrequency())
+                    perf_counter.perf_frequency = float(_time.QueryPerformanceFrequency())
                 except OSError:
                     # QueryPerformanceFrequency() fails if the installed
                     # hardware does not support a high-resolution performance
                     # counter
                     perf_counter.use_performance_counter = False
                 else:
-                    return _time.QueryPerformanceCounter() / perf_counter.cpu_frequency
+                    return _time.QueryPerformanceCounter() / perf_counter.perf_frequency
             else:
-                return _time.QueryPerformanceCounter() / perf_counter.cpu_frequency
+                return _time.QueryPerformanceCounter() / perf_counter.perf_frequency
         if perf_counter.use_monotonic:
             # Monotonic clock is preferred over system clock
             try:
@@ -1072,7 +1109,7 @@ Pseudo-code::
         return time.time()
     perf_counter.use_performance_counter = (os.name == 'nt')
     if perf_counter.use_performance_counter:
-        perf_counter.cpu_frequency = None
+        perf_counter.perf_frequency = None
     perf_counter.use_monotonic = hasattr(time, 'monotonic')
 
 Other names proposed for time.perf_counter():
@@ -1103,6 +1140,8 @@ Related Python issues:
   <http://bugs.python.org/issue12822>`_
 * `Issue #14222: Use time.steady() to implement timeout
   <http://bugs.python.org/issue14222>`_
+* `Issue #14309: Deprecate time.clock()
+  <http://bugs.python.org/issue14309>`_
 * `Issue #14397: Use GetTickCount/GetTickCount64 instead of
   QueryPerformanceCounter for monotonic clock
   <http://bugs.python.org/issue14397>`_