PEP 418: Re-add the pseudo-code for time.perf_counter()

pep-0418.txt

@@ -993,23 +993,46 @@ Issues of a hacked monotonic function:
 Deferred API: time.perf_counter()
 =================================
 
-Python does not provide a portable "performance counter" clock for benchmarking
+Performance counter used for benchmarking and profiling. The reference point of
-or profiling. Each tool has to implement its own heuristic to decide which
+the returned value is undefined so only the difference of consecutive calls is
-clock is the best depending on the OS and on which counters are available.
+valid and is number of seconds.
 
-A previous version of the PEP proposed a time.perf_counter() function using
+Pseudo-code::
-QueryPerformanceCounter() on Windows, time.monotonic(), or falls back to the
-system time. This function was not well defined and the idea is deferred.
 
-Proposed names for such function:
+    def perf_counter():
+        if perf_counter.use_performance_counter:
+            if perf_counter.cpu_frequency is None:
+                try:
+                    perf_counter.cpu_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
+            else:
+                return _time.QueryPerformanceCounter() / perf_counter.cpu_frequency
+        if perf_counter.use_monotonic:
+            # Monotonic clock is preferred over system clock
+            try:
+                return time.monotonic()
+            except OSError:
+                perf_counter.use_monotonic = False
+        return time.time()
+    perf_counter.use_performance_counter = (os.name == 'nt')
+    if perf_counter.use_performance_counter:
+        perf_counter.cpu_frequency = None
+    perf_counter.use_monotonic = hasattr(time, 'monotonic')
+
+Other names proposed for time.perf_counter():
 
  * time.hires()
  * time.highres()
- * time.perf_counter()
  * time.timer()
 
-Python source code includes a portable library to get the process time:
+Python source code includes a portable library to get the process time (CPU
-`Tools/pybench/systimes.py
+time): `Tools/pybench/systimes.py
 <http://hg.python.org/cpython/file/tip/Tools/pybench/systimes.py>`_.