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

Add new clock identfiers:

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

2 files changed, 49 insertions, 0 deletions

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index c5d1e83..253df73 100644
--- 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 d3c3c1f..d5836d5 100644
--- 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
 -------------