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

Add new clock identfiers:

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

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index c5d1e83e739b6f01eff9fadc034de23f241a16cf..253df733bf32c4f556cfdaf1376d5e10ea71dbf6 100644 (file)
--- a/Doc/library/time.rst
+++ b/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`.
 

diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index d3c3c1f75378a1bf4e9c681a94841445f06073a8..d5836d509be40dd6a0c79b07781311a2296d346a 100644 (file)
--- a/Doc/whatsnew/3.7.rst
+++ b/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
 -------------
 

diff --git a/Misc/NEWS.d/next/Library/2017-11-01-03-28-24.bpo-31917.DYQL0g.rst b/Misc/NEWS.d/next/Library/2017-11-01-03-28-24.bpo-31917.DYQL0g.rst
new file mode 100644 (file)
index 0000000..dbfe92a
--- /dev/null
+++ b/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`.

diff --git a/Modules/timemodule.c b/Modules/timemodule.c
index b5e168f9ec3c45e2d9e13efff2461f1b27751f87..347c8282d8ed31836fdd2d6c3577890fcdd72fbe 100644 (file)
--- a/Modules/timemodule.c
+++ b/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,