Close #10278: Add time.wallclock() function, monotonic clock.

Doc/library/time.rst

@@ -183,6 +183,18 @@ The module defines the following functions and data items:
 
    .. versionadded:: 3.3
 
+.. function:: wallclock()
+
+   .. index::
+      single: Wallclock
+      single: benchmarking
+
+   Return the current time in fractions of a second to the system's best ability.
+   Use this when the most accurate representation of wall-clock is required, i.e.
+   when "processor time" is inappropriate.  The reference point of the returned
+   value is undefined so only the difference of consecutive calls is valid.
+
+   .. versionadded: 3.3
 
 .. function:: ctime([secs])
 

Doc/whatsnew/3.3.rst

@@ -396,12 +396,14 @@ New module: :mod:`faulthandler`.
 time
 ----
 
-* The :mod:`time` module has new :func:`~time.clock_getres` and
-  :func:`~time.clock_gettime` functions and ``CLOCK_xxx`` constants.
-  :func:`~time.clock_gettime` can be used with :data:`time.CLOCK_MONOTONIC` to
-  get a monotonic clock.
+The :mod:`time` module has new functions:
 
-  (Contributed by Victor Stinner in :issue:`10278`)
+* :func:`~time.clock_getres` and :func:`~time.clock_gettime` functions and
+  ``CLOCK_xxx`` constants.  :func:`~time.clock_gettime` can be used with
+  :data:`time.CLOCK_MONOTONIC` to get a monotonic clock.
+* :func:`~time.wallclock`: monotonic clock.
+
+(Contributed by Victor Stinner in :issue:`10278`)
 
 
 ftplib

Lib/test/test_time.py

@@ -332,6 +332,13 @@ class TimeTestCase(unittest.TestCase):
         self.assertEqual(time.strftime('%Z', tt), tzname)
 
 
+    def test_wallclock(self):
+        t0 = time.wallclock()
+        time.sleep(0.1)
+        t1 = time.wallclock()
+        t = t1 - t0
+        self.assertAlmostEqual(t, 0.1, places=2)
+
 class TestLocale(unittest.TestCase):
     def setUp(self):
         self.oldloc = locale.setlocale(locale.LC_ALL)

Misc/NEWS

@@ -447,6 +447,8 @@ Core and Builtins
 Library
 -------
 
+- Issue #10278: Add time.wallclock() function, monotonic clock.
+
 - Issue #13809: Fix regression where bz2 module wouldn't work when threads are
   disabled. Original patch by Amaury Forgeot d'Arc.
 

Modules/timemodule.c

@@ -733,6 +733,52 @@ the local timezone used by methods such as localtime, but this behaviour\n\
 should not be relied on.");
 #endif /* HAVE_WORKING_TZSET */
 
+static PyObject *
+time_wallclock(PyObject *self, PyObject *unused)
+{
+#if defined(MS_WINDOWS) && !defined(__BORLANDC__)
+    return time_clock(self, NULL);
+#elif defined(HAVE_CLOCK_GETTIME) && defined(CLOCK_MONOTONIC)
+    static int clk_index = 0;
+    clockid_t clk_ids[] = {
+#ifdef CLOCK_MONOTONIC_RAW
+        CLOCK_MONOTONIC_RAW,
+#endif
+        CLOCK_MONOTONIC
+#ifdef CLOCK_REALTIME
+          /* On Linux, CLOCK_REALTIME uses the same clock than gettimeofday(),
+             but clock_gettime() has a nanosecond resolution. */
+        , CLOCK_REALTIME
+#endif
+    };
+    int ret;
+    struct timespec tp;
+
+    while (0 <= clk_index) {
+        clockid_t clk_id = clk_ids[clk_index];
+        ret = clock_gettime(clk_id, &tp);
+        if (ret == 0)
+            return PyFloat_FromDouble(tp.tv_sec + tp.tv_nsec * 1e-9);
+
+        clk_index++;
+        if (Py_ARRAY_LENGTH(clk_ids) <= clk_index)
+            clk_index = -1;
+    }
+    return time_time(self, NULL);
+#else
+    return time_time(self, NULL);
+#endif
+}
+
+PyDoc_STRVAR(wallclock_doc,
+"wallclock() -> float\n\
+\n\
+Return the current time in fractions of a second to the system's best\n\
+ability. Use this when the most accurate representation of wall-clock is\n\
+required, i.e. when "processor time" is inappropriate. The reference point\n\
+of the returned value is undefined so only the difference of consecutive\n\
+calls is valid.");
+
 static void
 PyInit_timezone(PyObject *m) {
     /* This code moved from PyInit_time wholesale to allow calling it from
@@ -868,6 +914,7 @@ static PyMethodDef time_methods[] = {
 #ifdef HAVE_WORKING_TZSET
     {"tzset",           time_tzset, METH_NOARGS, tzset_doc},
 #endif
+    {"wallclock",       time_wallclock, METH_NOARGS, wallclock_doc},
     {NULL,              NULL}           /* sentinel */
 };