PEP 418: more data about OS monotonic clocks

pep-0418.txt

@@ -180,6 +180,25 @@ Clocks
 Monotonic
 ---------
 
+Summary
+^^^^^^^
+
+Table summarizing all monotonic clocks:
+
+
+=========================  ===============  ================  =================
+Name                       Resolution       Adjusted by NTP?  Action on suspend
+=========================  ===============  ================  =================
+CLOCK_MONOTONIC_RAW        1 ns             No                ?
+gethrtime                  1 ns             ?                 ?
+mach_absolute_time()       1 ns             ?                 ?
+CLOCK_HIGHRES              1 ns             ?                 ?
+CLOCK_MONOTONIC            1 ns             Yes on Linux      Stopped on Linux
+QueryPerformanceCounter()  0.3 ns - 5 ns    No                ?
+GetTickCount[64]()         1 ms - 15 ms     No                ?
+timeGetTime()              1 ms - 15 ms     ?                 ?
+=========================  ===============  ================  =================
+
 mach_absolute_time
 ^^^^^^^^^^^^^^^^^^
 
@@ -246,6 +265,10 @@ Windows: QueryPerformanceCounter
 High-resolution performance counter. It is monotonic.
 QueryPerformanceFrequency() gives its frequency.
 
+It has much higher resolution, but has lower long term accuracy than
+GetTickCount() and timeGetTime() clocks. For example, it will drift compared to
+the low precision clocks.
+
 Documentation:
 
  * `MSDN: QueryPerformanceCounter() documentation
@@ -258,13 +281,18 @@ Hardware clocks used by QueryPerformanceCounter:
  * Windows XP: RDTSC instruction of Intel processors, the clock frequency is
    the frequency of the processor (between 200 MHz and 3 GHz, usually greater
    than 1 GHz nowadays)
- * Windows 2000: ACPI power management timer, frequency = 3,549,545 Hz
+ * Windows 2000: ACPI power management timer, frequency = 3,549,545 Hz. It can
+   be forced through the "/usepmtimer" flag in boot.ini
  * Windows 95/98: 8245 PIT chipset, frequency = 1,193,181 Hz
 
 QueryPerformanceFrequency() should only be called once:  the frequency will not
 change while the system is running. It fails if the installed hardware does not
 support a high-resolution performance counter.
 
+QueryPerformanceCounter() cannot be adjusted: `SetSystemTimeAdjustment()
+<http://msdn.microsoft.com/en-us/library/windows/desktop/ms724943(v=vs.85).aspx>`_
+does only adjust the system time.
+
 Bugs:
 
  * The performance counter value may unexpectedly leap forward because of a
@@ -277,6 +305,7 @@ Bugs:
    #8707 <https://www.virtualbox.org/ticket/8707>`_).
  * Windows XP had a bug (see `KB896256`_): on a multiprocessor computer,
    QueryPerformanceCounter() returned a different value for each processor.
+   The bug was fixed in Windows XP SP2.
 
 .. _KB896256: http://support.microsoft.com/?id=896256
 .. _KB274323: http://support.microsoft.com/?id=274323
@@ -285,7 +314,10 @@ Bugs:
 Windows: GetTickCount(), GetTickCount64()
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-GetTickCount() and GetTickCount64() are monotonic and cannot fail.
+GetTickCount() and GetTickCount64() are monotonic, cannot fail and are not
+adjusted by SetSystemTimeAdjustment().  MSDN documentation:
+`GetTickCount() <http://msdn.microsoft.com/en-us/library/windows/desktop/ms724408(v=vs.85).aspx>`_,
+`GetTickCount64() <http://msdn.microsoft.com/en-us/library/windows/desktop/ms724411(v=vs.85).aspx>`_.
 
 GetTickCount64() was added to Windows Vista and Windows Server 2008.
 
@@ -297,6 +329,29 @@ There are applications using this undocumented function, example:
 `Timer Resolution <http://www.lucashale.com/timer-resolution/>`_.
 
 
+Windows: timeGetTime
+^^^^^^^^^^^^^^^^^^^^
+
+The timeGetTime function retrieves the system time, in milliseconds. The system
+time is the time elapsed since Windows was started. Read the `timeGetTime()
+documentation
+<http://msdn.microsoft.com/en-us/library/windows/desktop/dd757629(v=vs.85).aspx>`_.
+
+The return type of timeGetTime() is a 32-bit unsigned integer. As
+GetTickCount(), timeGetTime() rolls over after 2^32 milliseconds (49.7 days).
+
+The default precision of the timeGetTime function can be five milliseconds or
+more, depending on the machine.
+
+timeBeginPeriod() can be used to increase the precision of timeGetTime() up to
+1 millisecond.
+
+.. note::
+   timeGetTime() and timeBeginPeriod() are part the Windows multimedia library
+   and so require to link the program with winmm or to load dynamically the
+   library.
+
+
 Solaris: CLOCK_HIGHRES
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -329,7 +384,7 @@ The system time can be read using GetSystemTimeAsFileTime(), ftime() and
 time().
 
 The system time resolution can be read using GetSystemTimeAdjustment(). The
-accurary is usually between 0.5 millisecond and 15 milliseconds. Resolution:
+accurary is usually between 1 millisecond and 15 milliseconds. Resolution:
 
  * GetSystemTimeAsFileTime(): 100 nanoseconds
  * ftime(): 1 millisecond
@@ -495,7 +550,7 @@ Librairies exposing monotonic clocks:
  * `Qt library: QElapsedTimer
    <http://qt-project.org/doc/qt-4.8/qelapsedtimer.html>`_
  * `glib library: g_get_monotonic_time ()
-   <http://developer.gnome.org/glib/2.30/glib-Date-and-Time-Functions.html>`_
+   <http://developer.gnome.org/glib/2.30/glib-Date-and-Time-Functions.html#g-get-monotonic-time>`_
    uses GetTickCount64()/GetTickCount() on Windows,
    clock_gettime(CLOCK_MONOTONIC) on UNIX or falls back to the system clock
  * `python-monotonic-time
@@ -512,7 +567,7 @@ Librairies exposing monotonic clocks:
    "AbsoluteTime.monotonic?" method indicates if AbsoluteTime.now is monotonic
    or not.
 
-Related documents:
+Time:
 
  * `C++ Timeout Specification
    <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3128.html>`_
@@ -520,4 +575,18 @@ Related documents:
    <http://msdn.microsoft.com/en-us/library/ee417693.aspx>`_
  * `Implement a Continuously Updating, High-Resolution Time Provider for Windows
    <http://msdn.microsoft.com/en-us/magazine/cc163996.aspx>`_
+ * `clockspeed <http://cr.yp.to/clockspeed.html>`_ uses a hardware tick counter
+   to compensate for a persistently fast or slow system clock
+ * `Retrieving system time
+   <http://en.wikipedia.org/wiki/System_time#Retrieving_system_time>`_
+   lists hardware clocks and time functions with their resolution
+   and epoch or range
+ * On Windows, the JavaScript runtime of Firefox interpolates
+   GetSystemTimeAsFileTime() with QueryPerformanceCounter() to get
+   an higher resolution. See the `Bug 363258 - bad millisecond resolution for
+   (new Date).getTime() / Date.now() on Windows
+   <https://bugzilla.mozilla.org/show_bug.cgi?id=363258>`_.
+ * `When microseconds matter
+   <http://www.ibm.com/developerworks/library/i-seconds/>`_: How the IBM High
+   Resolution Time Stamp Facility accurately measures itty bits of time