PEP 418: Add last comments

* Indicate if a clock is system-wide or process-wide
 * Add time.metronomic() alternative name
 * Explain why "steady" name was not chosen

pep-0418.txt

@@ -111,10 +111,17 @@ Return a dictionary with the following keys:
 time.monotonic()
 ^^^^^^^^^^^^^^^^
 
-Monotonic clock, cannot go backward.  It is not affected by system
+Monotonic clock, cannot go backward.  It is not affected by system clock
-clock updates.  The reference point of the returned value is
+updates.  The reference point of the returned value is undefined, so that only
-undefined, so that only the difference between the results of
+the difference between the results of consecutive calls is valid.
-consecutive calls is valid.
+
+On Windows older than Vista, ``time.monotonic()`` detects ``GetTickCount()``
+integer overflow (32 bits, roll-over after 49.7 days): it increases a delta by
+2\ :sup:`32` each time than an overflow is detected.  The delta is stored in
+the process-local state and so the value of ``time.monotonic()`` may be
+different in two Python processes running for more than 49 days. On more recent
+versions of Windows and on other operating systems, ``time.monotonic()`` is
+system-wide.
 
 Availability: Windows, Mac OS X, Unix, Solaris. Not available on GNU/Hurd.
 
@@ -160,21 +167,14 @@ On Windows, ``QueryPerformanceCounter()`` is not used even though it
 has a better precision than ``GetTickCount()``.  It is not reliable
 and has too many issues.
 
-``time.monotonic()`` detects ``GetTickCount()`` integer overflow (32 bits,
-roll-over after 49.7 days): it increases a delta by 2\ :sup:`32` each time
-than an overflow is detected.  The delta is stored in the process-local
-state and so the value of ``time.monotonic()`` may be different in two
-Python processes running for more than 49 days.
-
 
 time.perf_counter()
 ^^^^^^^^^^^^^^^^^^^
 
-Performance counter used for benchmarking.  It is monotonic,
+Performance counter used for benchmarking.  It is monotonic, i.e. cannot go
-i.e. cannot go backward.  It does include time elapsed during sleep.
+backward.  It does include time elapsed during sleep and is system-wide.  The
-The reference point of the returned value is undefined, so that only
+reference point of the returned value is undefined, so that only the difference
-the difference between the results of consecutive calls is valid and
+between the results of consecutive calls is valid and is number of seconds.
-is number of seconds.
 
 Pseudo-code::
 
@@ -208,10 +208,10 @@ Pseudo-code::
 time.process_time()
 ^^^^^^^^^^^^^^^^^^^
 
-Process time used for profiling: sum of the kernel and user-space CPU
+Process time used for profiling: sum of the kernel and user-space CPU time.  It
-time.  It does not include time elapsed during sleep.  The reference
+does not include time elapsed during sleep. It is process-wide by definition.
-point of the returned value is undefined, so that only the difference
+The reference point of the returned value is undefined, so that only the
-between the results of consecutive calls is valid.
+difference between the results of consecutive calls is valid.
 
 Pseudo-code [#pseudo]_::
 
@@ -264,7 +264,7 @@ time.time()
 
 The system time is the "wall clock".  It can be set manually by the
 system administrator or automatically by a NTP daemon.  It can jump
-backward and forward.  It is not monotonic.
+backward and forward.  It is system-wide but not monotonic.
 
 It is available on all platforms and cannot fail.
 
@@ -347,15 +347,15 @@ 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
+expressed in seconds. It is process-wide by definition. The precision, and in
-of the meaning of "processor time", depends on that of the C function
+fact the very definition of the meaning of "processor time", depends on that of
-of the same name, but in any case, this is the function to use for
+the C function of the same name, but in any case, this is the function to use
-benchmarking Python or timing algorithms.
+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.
+typically better than one microsecond.  It is system-wide.
 
 Pseudo-code [#pseudo]_::
 
@@ -391,12 +391,19 @@ Other names for new functions
 time.monotonic():
 
 * time.counter()
+* time.metronomic()
 * time.seconds()
 * time.steady()
 * time.timeout_clock()
 * time.wallclock(): it is not the system time aka the "wall clock",
   but a monotonic clock with an unspecified starting point
 
+"steady" is ambiguous: it means different things to different people. For
+example, on Linux, CLOCK_MONOTONIC is adjusted. If we uses the real time as the
+reference clock, we may say that CLOCK_MONOTONIC is steady.  But
+CLOCK_MONOTONIC gets suspended on system suspend, whereas real time includes
+any time spent in suspend.
+
 The name "time.try_monotonic()" was also proposed when
 time.monotonic() was falling back to the system clock when no
 monotonic clock was available.