bpo-31917: Add 3 new clock identifiers (#4207)

Add new clock identfiers:

* time.CLOCK_BOOTTIME
* time.CLOCK_PROF
* time.CLOCK_UPTIME

Doc/library/time.rst

@@ -663,6 +663,21 @@ Clock ID Constants
 These constants are used as parameters for :func:`clock_getres` and
 :func:`clock_gettime`.
 
+.. data:: CLOCK_BOOTTIME
+
+   Identical to :data:`CLOCK_MONOTONIC`, except it also includes any time that
+   the system is suspended.
+
+   This allows applications to get a suspend-aware monotonic  clock  without
+   having to deal with the complications of :data:`CLOCK_REALTIME`, which may
+   have  discontinuities if the time is changed using ``settimeofday()`` or
+   similar.
+
+   Availability: Linux 2.6.39 or later.
+
+   .. versionadded:: 3.7
+
+
 .. data:: CLOCK_HIGHRES
 
    The Solaris OS has a ``CLOCK_HIGHRES`` timer that attempts to use an optimal
@@ -703,6 +718,15 @@ These constants are used as parameters for :func:`clock_getres` and
    .. versionadded:: 3.3
 
 
+.. data:: CLOCK_PROF
+
+   High-resolution per-process timer from the CPU.
+
+   Availability: FreeBSD 3 or later, NetBSD 7 or later, OpenBSD.
+
+   .. versionadded:: 3.7
+
+
 .. data:: CLOCK_THREAD_CPUTIME_ID
 
    Thread-specific CPU-time clock.
@@ -712,6 +736,17 @@ These constants are used as parameters for :func:`clock_getres` and
    .. versionadded:: 3.3
 
 
+.. data:: CLOCK_UPTIME
+
+   Time whose absolute value is the time the system has been running and not
+   suspended, providing accurate uptime measurement, both absolute and
+   interval.
+
+   Availability: FreeBSD 7 or later, OpenBSD 5.5 or later.
+
+   .. versionadded:: 3.7
+
+
 The following constant is the only parameter that can be sent to
 :func:`clock_settime`.
 

Doc/whatsnew/3.7.rst

@@ -310,6 +310,20 @@ string
 expression pattern for braced placeholders and non-braced placeholders
 separately.  (Contributed by Barry Warsaw in :issue:`1198569`.)
 
+time
+----
+
+Add new clock identifiers:
+
+* :data:`time.CLOCK_BOOTTIME` (Linux): Identical to
+  :data:`time.CLOCK_MONOTONIC`, except it also includes any time that the
+  system is suspended.
+* :data:`time.CLOCK_PROF` (FreeBSD, NetBSD and OpenBSD): High-resolution
+  per-process timer from the CPU.
+* :data:`time.CLOCK_UPTIME` (FreeBSD, OpenBSD): Time whose absolute value is
+  the time the system has been running and not suspended, providing accurate
+  uptime measurement, both absolute and interval.
+
 unittest.mock
 -------------
 

Misc/NEWS.d/next/Library/2017-11-01-03-28-24.bpo-31917.DYQL0g.rst

@@ -0,0 +1,2 @@
+Add 3 new clock identifiers: :data:`time.CLOCK_BOOTTIME`,
+:data:`time.CLOCK_PROF` and :data:`time.CLOCK_UPTIME`.

Modules/timemodule.c

@@ -1389,6 +1389,15 @@ PyInit_time(void)
 #ifdef CLOCK_THREAD_CPUTIME_ID
     PyModule_AddIntMacro(m, CLOCK_THREAD_CPUTIME_ID);
 #endif
+#ifdef CLOCK_PROF
+    PyModule_AddIntMacro(m, CLOCK_PROF);
+#endif
+#ifdef CLOCK_BOOTTIME
+    PyModule_AddIntMacro(m, CLOCK_BOOTTIME);
+#endif
+#ifdef CLOCK_UPTIME
+    PyModule_AddIntMacro(m, CLOCK_UPTIME);
+#endif
 
     if (!initialized) {
         if (PyStructSequence_InitType2(&StructTimeType,