pythongh-110850: Add PyTime_TimeRaw() function

Add "Raw" variant of PyTime functions: * PyTime_MonotonicRaw() * PyTime_PerfCounterRaw() * PyTime_TimeRaw() Changes: * Add documentation and tests. Tests release the GIL while calling raw clock functions. * py_get_system_clock() and py_get_monotonic_clock() now check that the GIL is hold by the caller if raise_exc is non-zero. * Reimplement "Unchecked" functions with raw clock functions.
vstinner · Apr 29, 2024 · 9a69ac4 · 9a69ac4
1 parent 23d0371
commit 9a69ac4
Show file tree

Hide file tree

Showing 7 changed files with 165 additions and 35 deletions.
diff --git a/Doc/c-api/time.rst b/Doc/c-api/time.rst
@@ -72,6 +72,31 @@ with the :term:`GIL` held.
    See :func:`time.time` for details important on this clock.
 
 
+Raw Clock Functions
+-------------------
+
+Similar to clock functions, but don't set an exception on error and don't
+require the caller to hold the GIL.
+
+The functions return ``0`` on success, or set ``*result`` to ``0`` return
+``-1`` on failure.
+
+.. c:function:: int PyTime_MonotonicRaw(PyTime_t *result)
+
+   Similar to :c:func:`PyTime_Monotonic`,
+   but don't set an exception on error and don't require holding the GIL.
+
+.. c:function:: int PyTime_PerfCounterRaw(PyTime_t *result)
+
+   Similar to :c:func:`PyTime_PerfCounter`,
+   but don't set an exception on error and don't require holding the GIL.
+
+.. c:function:: int PyTime_TimeRaw(PyTime_t *result)
+
+   Similar to :c:func:`PyTime_Time`,
+   but don't set an exception on error and don't require holding the GIL.
+
+
 Conversion functions
 --------------------
 

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
@@ -1882,9 +1882,15 @@ New Features
 
   * :c:type:`PyTime_t` type.
   * :c:var:`PyTime_MIN` and :c:var:`PyTime_MAX` constants.
-  * :c:func:`PyTime_AsSecondsDouble`
-    :c:func:`PyTime_Monotonic`, :c:func:`PyTime_PerfCounter`, and
-    :c:func:`PyTime_Time` functions.
+  * Add functions:
+
+    * :c:func:`PyTime_AsSecondsDouble`.
+    * :c:func:`PyTime_Monotonic`.
+    * :c:func:`PyTime_MonotonicRaw`.
+    * :c:func:`PyTime_PerfCounter`.
+    * :c:func:`PyTime_PerfCounterRaw`.
+    * :c:func:`PyTime_Time`.
+    * :c:func:`PyTime_TimeRaw`.
 
   (Contributed by Victor Stinner and Petr Viktorin in :gh:`110850`.)
 

diff --git a/Include/cpython/pytime.h b/Include/cpython/pytime.h
@@ -16,6 +16,10 @@ PyAPI_FUNC(int) PyTime_Monotonic(PyTime_t *result);
 PyAPI_FUNC(int) PyTime_PerfCounter(PyTime_t *result);
 PyAPI_FUNC(int) PyTime_Time(PyTime_t *result);
 
+PyAPI_FUNC(int) PyTime_MonotonicRaw(PyTime_t *result);
+PyAPI_FUNC(int) PyTime_PerfCounterRaw(PyTime_t *result);
+PyAPI_FUNC(int) PyTime_TimeRaw(PyTime_t *result);
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/Lib/test/test_capi/test_time.py b/Lib/test/test_capi/test_time.py
@@ -18,11 +18,6 @@ def test_min_max(self):
         self.assertEqual(PyTime_MIN, -2**63)
         self.assertEqual(PyTime_MAX, 2**63 - 1)
 
-    def check_clock(self, c_func, py_func):
-        t1 = c_func()
-        t2 = py_func()
-        self.assertAlmostEqual(t1, t2, delta=CLOCK_RES)
-
     def test_assecondsdouble(self):
         # Test PyTime_AsSecondsDouble()
         def ns_to_sec(ns):
@@ -58,14 +53,22 @@ def ns_to_sec(ns):
                 self.assertEqual(_testcapi.PyTime_AsSecondsDouble(ns),
                                  ns_to_sec(ns))
 
+    def check_clock(self, c_func, py_func):
+        t1 = c_func()
+        t2 = py_func()
+        self.assertAlmostEqual(t1, t2, delta=CLOCK_RES)
+
     def test_monotonic(self):
-        # Test PyTime_Monotonic()
+        # Test PyTime_Monotonic() and PyTime_MonotonicRaw()
         self.check_clock(_testcapi.PyTime_Monotonic, time.monotonic)
+        self.check_clock(_testcapi.PyTime_MonotonicRaw, time.monotonic)
 
     def test_perf_counter(self):
-        # Test PyTime_PerfCounter()
+        # Test PyTime_PerfCounter() and PyTime_PerfCounterRaw()
         self.check_clock(_testcapi.PyTime_PerfCounter, time.perf_counter)
+        self.check_clock(_testcapi.PyTime_PerfCounterRaw, time.perf_counter)
 
     def test_time(self):
-        # Test PyTime_time()
+        # Test PyTime_Time() and PyTime_TimeRaw()
         self.check_clock(_testcapi.PyTime_Time, time.time)
+        self.check_clock(_testcapi.PyTime_TimeRaw, time.time)
diff --git a/Misc/NEWS.d/next/C API/2024-04-29-17-19-07.gh-issue-110850.vcpLn1.rst b/Misc/NEWS.d/next/C API/2024-04-29-17-19-07.gh-issue-110850.vcpLn1.rst
@@ -0,0 +1,7 @@
+Add "Raw" variant of PyTime functions
+
+* :c:func:`PyTime_MonotonicRaw`
+* :c:func:`PyTime_PerfCounterRaw`
+* :c:func:`PyTime_TimeRaw`
+
+Patch by Victor Stinner.
diff --git a/Modules/_testcapi/time.c b/Modules/_testcapi/time.c
@@ -58,6 +58,23 @@ test_pytime_monotonic(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
 }
 
 
+static PyObject*
+test_pytime_monotonic_raw(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
+{
+    PyTime_t t;
+    int res;
+    Py_BEGIN_ALLOW_THREADS
+    res = PyTime_MonotonicRaw(&t);
+    Py_END_ALLOW_THREADS
+    if (res < 0) {
+        PyErr_SetString(PyExc_RuntimeError, "PyTime_MonotonicRaw() failed");
+        return NULL;
+    }
+    assert(res == 0);
+    return pytime_as_float(t);
+}
+
+
 static PyObject*
 test_pytime_perf_counter(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
 {
@@ -71,6 +88,23 @@ test_pytime_perf_counter(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
 }
 
 
+static PyObject*
+test_pytime_perf_counter_raw(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
+{
+    PyTime_t t;
+    int res;
+    Py_BEGIN_ALLOW_THREADS
+    res = PyTime_PerfCounterRaw(&t);
+    Py_END_ALLOW_THREADS
+    if (res < 0) {
+        PyErr_SetString(PyExc_RuntimeError, "PyTime_PerfCounterRaw() failed");
+        return NULL;
+    }
+    assert(res == 0);
+    return pytime_as_float(t);
+}
+
+
 static PyObject*
 test_pytime_time(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
 {
@@ -84,11 +118,31 @@ test_pytime_time(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
 }
 
 
+static PyObject*
+test_pytime_time_raw(PyObject *Py_UNUSED(self), PyObject *Py_UNUSED(args))
+{
+    PyTime_t t;
+    int res;
+    Py_BEGIN_ALLOW_THREADS
+    res = PyTime_TimeRaw(&t);
+    Py_END_ALLOW_THREADS
+    if (res < 0) {
+        PyErr_SetString(PyExc_RuntimeError, "PyTime_TimeRaw() failed");
+        return NULL;
+    }
+    assert(res == 0);
+    return pytime_as_float(t);
+}
+
+
 static PyMethodDef test_methods[] = {
     {"PyTime_AsSecondsDouble", test_pytime_assecondsdouble, METH_VARARGS},
     {"PyTime_Monotonic", test_pytime_monotonic, METH_NOARGS},
+    {"PyTime_MonotonicRaw", test_pytime_monotonic_raw, METH_NOARGS},
     {"PyTime_PerfCounter", test_pytime_perf_counter, METH_NOARGS},
+    {"PyTime_PerfCounterRaw", test_pytime_perf_counter_raw, METH_NOARGS},
     {"PyTime_Time", test_pytime_time, METH_NOARGS},
+    {"PyTime_TimeRaw", test_pytime_time_raw, METH_NOARGS},
     {NULL},
 };
 

diff --git a/Python/pytime.c b/Python/pytime.c
@@ -898,6 +898,10 @@ static int
 py_get_system_clock(PyTime_t *tp, _Py_clock_info_t *info, int raise_exc)
 {
     assert(info == NULL || raise_exc);
+    if (raise_exc) {
+        // raise_exc requires to hold the GIL
+        assert(PyGILState_Check());
+    }
 
 #ifdef MS_WINDOWS
     FILETIME system_time;
@@ -1004,29 +1008,37 @@ py_get_system_clock(PyTime_t *tp, _Py_clock_info_t *info, int raise_exc)
 }
 
 
-PyTime_t
-_PyTime_TimeUnchecked(void)
+int
+PyTime_Time(PyTime_t *result)
 {
-    PyTime_t t;
-    if (py_get_system_clock(&t, NULL, 0) < 0) {
-        // If clock_gettime(CLOCK_REALTIME) or gettimeofday() fails:
-        // silently ignore the failure and return 0.
-        t = 0;
+    if (py_get_system_clock(result, NULL, 1) < 0) {
+        *result = 0;
+        return -1;
     }
-    return t;
+    return 0;
 }
 
 
 int
-PyTime_Time(PyTime_t *result)
+PyTime_TimeRaw(PyTime_t *result)
 {
-    if (py_get_system_clock(result, NULL, 1) < 0) {
+    if (py_get_system_clock(result, NULL, 0) < 0) {
         *result = 0;
         return -1;
     }
     return 0;
 }
 
+
+PyTime_t
+_PyTime_TimeUnchecked(void)
+{
+    PyTime_t t;
+    (void)PyTime_TimeRaw(&t);
+    return t;
+}
+
+
 int
 _PyTime_TimeWithInfo(PyTime_t *t, _Py_clock_info_t *info)
 {
@@ -1140,6 +1152,10 @@ static int
 py_get_monotonic_clock(PyTime_t *tp, _Py_clock_info_t *info, int raise_exc)
 {
     assert(info == NULL || raise_exc);
+    if (raise_exc) {
+        // raise_exc requires to hold the GIL
+        assert(PyGILState_Check());
+    }
 
 #if defined(MS_WINDOWS)
     if (py_get_win_perf_counter(tp, info, raise_exc) < 0) {
@@ -1225,29 +1241,37 @@ py_get_monotonic_clock(PyTime_t *tp, _Py_clock_info_t *info, int raise_exc)
 }
 
 
-PyTime_t
-_PyTime_MonotonicUnchecked(void)
+int
+PyTime_Monotonic(PyTime_t *result)
 {
-    PyTime_t t;
-    if (py_get_monotonic_clock(&t, NULL, 0) < 0) {
-        // Ignore silently the error and return 0.
-        t = 0;
+    if (py_get_monotonic_clock(result, NULL, 1) < 0) {
+        *result = 0;
+        return -1;
     }
-    return t;
+    return 0;
 }
 
 
 int
-PyTime_Monotonic(PyTime_t *result)
+PyTime_MonotonicRaw(PyTime_t *result)
 {
-    if (py_get_monotonic_clock(result, NULL, 1) < 0) {
+    if (py_get_monotonic_clock(result, NULL, 0) < 0) {
         *result = 0;
         return -1;
     }
     return 0;
 }
 
 
+PyTime_t
+_PyTime_MonotonicUnchecked(void)
+{
+    PyTime_t t;
+    (void)PyTime_MonotonicRaw(&t);
+    return t;
+}
+
+
 int
 _PyTime_MonotonicWithInfo(PyTime_t *tp, _Py_clock_info_t *info)
 {
@@ -1262,17 +1286,24 @@ _PyTime_PerfCounterWithInfo(PyTime_t *t, _Py_clock_info_t *info)
 }
 
 
-PyTime_t
-_PyTime_PerfCounterUnchecked(void)
+int
+PyTime_PerfCounter(PyTime_t *result)
 {
-    return _PyTime_MonotonicUnchecked();
+    return PyTime_Monotonic(result);
 }
 
 
 int
-PyTime_PerfCounter(PyTime_t *result)
+PyTime_PerfCounterRaw(PyTime_t *result)
 {
-    return PyTime_Monotonic(result);
+    return PyTime_MonotonicRaw(result);
+}
+
+
+PyTime_t
+_PyTime_PerfCounterUnchecked(void)
+{
+    return _PyTime_MonotonicUnchecked();
 }