PEP 418: Drop fallback parameter of time.monotonic()

time.monotonic() now always falls back and time.get_clock_info() can be used to
check if the clock is monotonic.

pep-0418.txt

@@ -13,8 +13,8 @@ Python-Version: 3.3
 Abstract
 ========
 
-Add time.monotonic(fallback=True), time.highres(), time.get_clock_info(name)
-functions to Python 3.3.
+Add time.monotonic(), time.highres(), time.get_clock_info(name) functions to
+Python 3.3.
 
 
 Rationale
@@ -25,8 +25,8 @@ Use cases:
 * Display the current time to a human (e.g. display a calendar or draw
   a wall clock): use system clock, i.e. time.time() or
   datetime.datetime.now().
-* Benchmark, profiling, timeout: time.highres().
-* Event scheduler: time.monotonic(), or time.monotonic(fallback=False).
+* Benchmark, profiling: time.highres().
+* Event scheduler, timeout: time.monotonic().
 
 
 Functions
@@ -36,10 +36,8 @@ To fulfill the use cases, the functions' properties are:
 
 * time.time(): system clock, "wall clock".
 * time.highres(): clock with the best accuracy.
-* time.monotonic(fallback=True): monotonic clock. If no monotonic
-  clock is available, falls back to system clock by default, or raises
-  an OSError if *fallback* is False.  time.monotonic(fallback=True)
-  cannot go backward.
+* time.monotonic(): monotonic clock, or system clock if no monotonic
+  clock is available
 * time.get_clock_info(name): get information on the specified time function
 
 
@@ -81,19 +79,16 @@ Pseudo-code [#pseudo]_::
                 return _time.time()
 
 
-time.monotonic(fallback=True)
------------------------------
+time.monotonic()
+----------------
 
-Clock that cannot go backward, its rate is as steady as possible.  Its
-rate may be adjusted by NTP.  The reference point of the returned
-value is undefined so only the difference of consecutive calls is
-valid.
+Monotonic clock, or system clock if the platform does not provide a monotonic
+clock (e.g. on GNU/Hurd). Its rate is as steady as possible. Its rate may be
+adjusted by NTP.  The reference point of the returned value is undefined so
+only the difference of consecutive calls is valid.
 
-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
-(e.g. on GNU/Hurd).
+Use time.get_clock_info('monotonic')['monotonic'] to check if the clock
+monotonic or not.
 
 The elapsed time may or may not include time the system spends in
 sleep or hibernation; this depends on the operating system.
@@ -103,10 +98,10 @@ Pseudo-code [#pseudo]_::
     if os.name == 'nt':
         # GetTickCount64() requires Windows Vista, Server 2008 or later
         if hasattr(time, '_GetTickCount64'):
-            def monotonic(fallback=True):
+            def monotonic():
                 return _time.GetTickCount64()
         else:
-            def monotonic(fallback=True):
+            def monotonic():
                 ticks = _time.GetTickCount()
                 if ticks < monotonic.last:
                     # Integer overflow detected
@@ -117,7 +112,7 @@ Pseudo-code [#pseudo]_::
             monotonic.delta = 0
 
     elif os.name == 'mac':
-        def monotonic(fallback=True):
+        def monotonic():
             if monotonic.factor is None:
                 factor = _time.mach_timebase_info()
                 monotonic.factor = timebase[0] / timebase[1]
@@ -125,7 +120,7 @@ Pseudo-code [#pseudo]_::
         monotonic.factor = None
 
     elif os.name.startswith('sunos'):
-        def monotonic(fallback=True):
+        def monotonic():
             if monotonic.use_clock_highres:
                 try:
                     time.clock_gettime(time.CLOCK_HIGHRES)
@@ -135,8 +130,6 @@ Pseudo-code [#pseudo]_::
                 try:
                     return time.gethrtime()
                 except OSError:
-                    if not fallback:
-                        raise
                     monotonic.use_gethrtime = False
             return time.time()
         monotonic.use_clock_highres = (hasattr(time, 'clock_gettime')
@@ -144,15 +137,13 @@ Pseudo-code [#pseudo]_::
         monotonic.use_gethrtime = True
 
     elif hasattr(time, "clock_gettime"):
-        def monotonic(fallback=True):
+        def monotonic():
             while monotonic.clocks:
                 try:
                     clk_id = monotonic.clocks[0]
                     return time.clock_gettime(clk_id)
                 except OSError:
                     # CLOCK_MONOTONIC_RAW requires a Linux kernel >= 2.6.28
-                    if len(monotonic.clocks) == 1 and not fallback:
-                        raise
                     del monotonic.clocks[0]
             return time.time()
         monotonic.clocks = []
@@ -163,9 +154,7 @@ Pseudo-code [#pseudo]_::
         monotonic.clocks.append(time.CLOCK_MONOTONIC)
 
     else:
-        def monotonic(fallback=True):
-            if not fallback:
-                raise NotImplementedError("you platform does not provide any monotonic clock")
+        def monotonic():
             return time.time()
 
 On Windows, QueryPerformanceCounter() is not used even though it has a
@@ -679,6 +668,21 @@ time.monotonic():
   a monotonic clock with an unspecified starting point
 
 
+One function with a flag: time.monotonic(fallback=True)
+-------------------------------------------------------
+
+ * time.monotonic(fallback=True) falls back to the system clock if no monotonic
+   clock is available or if the monotonic clock failed.
+ * time.monotonic(fallback=False) 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
 ---------------------