gh-110850: Add PyTime_TimeRaw() function (#118394)

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.

Co-authored-by: Petr Viktorin <encukou@gmail.com>

1 files changed, 69 insertions, 24 deletions

diff --git a/Python/pytime.c b/Python/pytime.c
index d5b3804..12b36bb 100644
--- 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,44 @@ 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;
+#ifdef Py_DEBUG
+    int result = PyTime_TimeRaw(&t);
+    if (result != 0) {
+        Py_FatalError("unable to read the system clock");
+    }
+#else
+    (void)PyTime_TimeRaw(&t);
+#endif
+    return t;
+}
+
+
 int
 _PyTime_TimeWithInfo(PyTime_t *t, _Py_clock_info_t *info)
 {
@@ -1140,6 +1159,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,22 +1248,21 @@ 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;
     }
@@ -1248,6 +1270,22 @@ PyTime_Monotonic(PyTime_t *result)
 }
 
 
+PyTime_t
+_PyTime_MonotonicUnchecked(void)
+{
+    PyTime_t t;
+#ifdef Py_DEBUG
+    int result = PyTime_MonotonicRaw(&t);
+    if (result != 0) {
+        Py_FatalError("unable to read the monotonic clock");
+    }
+#else
+    (void)PyTime_MonotonicRaw(&t);
+#endif
+    return t;
+}
+
+
 int
 _PyTime_MonotonicWithInfo(PyTime_t *tp, _Py_clock_info_t *info)
 {
@@ -1262,17 +1300,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();
 }