[Python-checkins] peps: PEP 418: Cleanup after reintroduction of fallback=True

[victor.stinner]

http://hg.python.org/peps/rev/011c7b9559b7
changeset:   4178:011c7b9559b7
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Sat Mar 31 02:00:43 2012 +0200
summary:
  PEP 418: Cleanup after reintroduction of fallback=True

files:
  pep-0418.txt |  34 ++++++++++++++++------------------
  1 files changed, 16 insertions(+), 18 deletions(-)


diff --git a/pep-0418.txt b/pep-0418.txt
--- a/pep-0418.txt
+++ b/pep-0418.txt
@@ -82,10 +82,14 @@
 be adjusted by NTP. The reference point of the returned value is undefined so
 only the difference of consecutive calls is valid.
 
-It is not available on all platforms and may raise an OSError. It is not
-available on GNU/Hurd for example.
+By default, it falls back to the system clock if no monotonic clock is
+available or if the monotonic clock failed, and so it cannot fail. If fallback
+is False, it raises OSError if the monotonic clock failed and
+NotImplementedError if the platform does not provide a monotonic clock (ex:
+GNU/Hurd).
 
-The monotonic clock may stop while the system is suspended.
+The elapsed time may or may not include time the system spends in sleep or
+hibernation, it depends on the operating system.
 
 Pseudo-code [#pseudo]_: ::
 
@@ -151,6 +155,12 @@
             monotonic.clocks.append(time.CLOCK_HIGHRES)
         monotonic.clocks.append(time.CLOCK_MONOTONIC)
 
+    else:
+        def monotonic(fallback=True):
+            if not fallback:
+                raise NotImplementedError("you platform does not provide any monotonic clock")
+            return time.time()
+
 On Windows, QueryPerformanceCounter() is not used even if it has a better
 resolution than GetTickCount(). It is not reliable and has too much issues.
 
@@ -204,7 +214,7 @@
 gethrtime                 1 ns            (*)             No               Not stopped
 CLOCK_HIGHRES             1 ns            (*)             No               ?
 CLOCK_MONOTONIC           1 ns            (*)             Yes on Linux     Stopped on Linux
-mach_absolute_time()      1 ns            ?               No               ?
+mach_absolute_time()      1 ns            (*)             No               ?
 QueryPerformanceCounter() \-              0.3 ns - 5 ns   No               Accuracy issue
 GetTickCount[64]()        1 ms            1 ms - 15 ms    No               Include suspend time
 timeGetTime()             1 ms            1 ms - 15 ms    No               ?
@@ -564,8 +574,8 @@
 Alternatives: API design
 ========================
 
-time.highres() function name
-----------------------------
+Name of the "monotonic or fallback" function name
+-------------------------------------------------
 
 Other names were proposed:
 
@@ -578,20 +588,6 @@
    chances with a best-effect clock."
  * time.wallclock()
 
-One function with a flag: time.monotonic(strict=False)
-------------------------------------------------------
-
- * time.monotonic(strict=False) falls back to the system clock if no monotonic
-   clock is available or if the monotonic clock failed.
- * time.monotonic(strict=True) raises OSError if monotonic clock fails and
-   NotImplementedError if the system does not provide a monotonic clock
-
-"A keyword argument that gets passed as a constant in the caller is usually
-poor API."
-
-Raising NotImplementedError for a function is something uncommon in Python and
-should be avoided.
-
 
 One function, no flag
 ---------------------

-- 
Repository URL: http://hg.python.org/peps