[Python-checkins] peps: PEP 418: Drop fallback parameter of time.monotonic()

Sun Apr 1 04:24:05 CEST 2012

http://hg.python.org/peps/rev/e6e799e92983
changeset: 4184:e6e799e92983
user: Victor Stinner <victor.stinner at gmail.com>
date: Sun Apr 01 04:23:32 2012 +0200
summary:
 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.
files:
 pep-0418.txt | 65 +++++++++++++++++++++------------------
 1 files changed, 35 insertions(+), 30 deletions(-)

diff --git a/pep-0418.txt b/pep-0418.txt
--- a/pep-0418.txt
+++ b/pep-0418.txt
@@ -13,8 +13,8 @@
 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 @@
 * 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 @@
 
 * 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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
 ---------------------
 
-- 
Repository URL: http://hg.python.org/peps
