pythongh-110850: Rename internal PyTime C API functions (python#115734)

Rename functions:

* _PyTime_GetSystemClock() => _PyTime_TimeUnchecked()
* _PyTime_GetPerfCounter() => _PyTime_PerfCounterUnchecked()
* _PyTime_GetMonotonicClock() => _PyTime_MonotonicUnchecked()
* _PyTime_GetSystemClockWithInfo() => _PyTime_TimeWithInfo()
* _PyTime_GetMonotonicClockWithInfo() => _PyTime_MonotonicWithInfo()
* _PyTime_GetMonotonicClockWithInfo() => _PyTime_MonotonicWithInfo()

Changes:

* Remove "typedef PyTime_t PyTime_t;" which was
  "typedef PyTime_t _PyTime_t;" before a previous rename.
* Update comments of "Unchecked" functions.
* Remove invalid PyTime_Time() comment.

Author: vstinner

Include/internal/pycore_time.h

@@ -62,7 +62,6 @@ extern "C" {
 struct timeval;
 #endif
 
-typedef PyTime_t PyTime_t;
 #define _SIZEOF_PYTIME_T 8
 
 typedef enum {
@@ -253,37 +252,28 @@ typedef struct {
     double resolution;
 } _Py_clock_info_t;
 
-// Get the current time from the system clock.
-//
-// If the internal clock fails, silently ignore the error and return 0.
-// On integer overflow, silently ignore the overflow and clamp the clock to
-// [_PyTime_MIN; _PyTime_MAX].
+// Similar to PyTime_Time() but silently ignore the error and return 0 if the
+// internal clock fails.
 //
-// Use _PyTime_GetSystemClockWithInfo or the public PyTime_Time() to check
+// Use _PyTime_TimeWithInfo() or the public PyTime_Time() to check
 // for failure.
 // Export for '_random' shared extension.
-PyAPI_FUNC(PyTime_t) _PyTime_GetSystemClock(void);
+PyAPI_FUNC(PyTime_t) _PyTime_TimeUnchecked(void);
 
 // Get the current time from the system clock.
 // On success, set *t and *info (if not NULL), and return 0.
 // On error, raise an exception and return -1.
-extern int _PyTime_GetSystemClockWithInfo(
+extern int _PyTime_TimeWithInfo(
     PyTime_t *t,
     _Py_clock_info_t *info);
 
-// Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
-// The clock is not affected by system clock updates. The reference point of
-// the returned value is undefined, so that only the difference between the
-// results of consecutive calls is valid.
+// Similar to PyTime_Monotonic() but silently ignore the error and return 0 if
+// the internal clock fails.
 //
-// If the internal clock fails, silently ignore the error and return 0.
-// On integer overflow, silently ignore the overflow and clamp the clock to
-// [_PyTime_MIN; _PyTime_MAX].
-//
-// Use _PyTime_GetMonotonicClockWithInfo or the public PyTime_Monotonic()
+// Use _PyTime_MonotonicWithInfo() or the public PyTime_Monotonic()
 // to check for failure.
 // Export for '_random' shared extension.
-PyAPI_FUNC(PyTime_t) _PyTime_GetMonotonicClock(void);
+PyAPI_FUNC(PyTime_t) _PyTime_MonotonicUnchecked(void);
 
 // Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
 // The clock is not affected by system clock updates. The reference point of
@@ -294,7 +284,7 @@ PyAPI_FUNC(PyTime_t) _PyTime_GetMonotonicClock(void);
 //
 // Return 0 on success, raise an exception and return -1 on error.
 // Export for '_testsinglephase' shared extension.
-PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo(
+PyAPI_FUNC(int) _PyTime_MonotonicWithInfo(
     PyTime_t *t,
     _Py_clock_info_t *info);
 
@@ -309,17 +299,13 @@ PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm);
 // Export for '_datetime' shared extension.
 PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm);
 
-// Get the performance counter: clock with the highest available resolution to
-// measure a short duration.
+// Similar to PyTime_PerfCounter() but silently ignore the error and return 0
+// if the internal clock fails.
 //
-// If the internal clock fails, silently ignore the error and return 0.
-// On integer overflow, silently ignore the overflow and clamp the clock to
-// [_PyTime_MIN; _PyTime_MAX].
-//
-// Use _PyTime_GetPerfCounterWithInfo() or the public PyTime_PerfCounter
-// to check for failure.
+// Use _PyTime_PerfCounterWithInfo() or the public PyTime_PerfCounter() to
+// check for failure.
 // Export for '_lsprof' shared extension.
-PyAPI_FUNC(PyTime_t) _PyTime_GetPerfCounter(void);
+PyAPI_FUNC(PyTime_t) _PyTime_PerfCounterUnchecked(void);
 
 
 // Get the performance counter: clock with the highest available resolution to
@@ -328,7 +314,7 @@ PyAPI_FUNC(PyTime_t) _PyTime_GetPerfCounter(void);
 // Fill info (if set) with information of the function used to get the time.
 //
 // Return 0 on success, raise an exception and return -1 on error.
-extern int _PyTime_GetPerfCounterWithInfo(
+extern int _PyTime_PerfCounterWithInfo(
     PyTime_t *t,
     _Py_clock_info_t *info);
 
@@ -341,12 +327,12 @@ extern int _PyTime_GetPerfCounterWithInfo(
 // --- _PyDeadline -----------------------------------------------------------
 
 // Create a deadline.
-// Pseudo code: _PyTime_GetMonotonicClock() + timeout.
+// Pseudo code: _PyTime_MonotonicUnchecked() + timeout.
 // Export for '_ssl' shared extension.
 PyAPI_FUNC(PyTime_t) _PyDeadline_Init(PyTime_t timeout);
 
 // Get remaining time from a deadline.
-// Pseudo code: deadline - _PyTime_GetMonotonicClock().
+// Pseudo code: deadline - _PyTime_MonotonicUnchecked().
 // Export for '_ssl' shared extension.
 PyAPI_FUNC(PyTime_t) _PyDeadline_Get(PyTime_t deadline);
 

Modules/_datetimemodule.c

@@ -5133,7 +5133,7 @@ datetime_from_timestamp(PyObject *cls, TM_FUNC f, PyObject *timestamp,
 static PyObject *
 datetime_best_possible(PyObject *cls, TM_FUNC f, PyObject *tzinfo)
 {
-    PyTime_t ts = _PyTime_GetSystemClock();
+    PyTime_t ts = _PyTime_TimeUnchecked();
     time_t secs;
     int us;
 

Modules/_lsprof.c

@@ -121,7 +121,7 @@ call_timer(ProfilerObject *pObj)
         return CallExternalTimer(pObj);
     }
     else {
-        return _PyTime_GetPerfCounter();
+        return _PyTime_PerfCounterUnchecked();
     }
 }
 

Modules/_randommodule.c

@@ -75,7 +75,7 @@
 #include "pycore_modsupport.h"    // _PyArg_NoKeywords()
 #include "pycore_moduleobject.h"  // _PyModule_GetState()
 #include "pycore_pylifecycle.h"   // _PyOS_URandomNonblock()
-#include "pycore_time.h"          // _PyTime_GetSystemClock()
+#include "pycore_time.h"          // _PyTime_TimeUnchecked()
 
 #ifdef HAVE_UNISTD_H
 #  include <unistd.h>             // getpid()
@@ -266,7 +266,7 @@ random_seed_time_pid(RandomObject *self)
     PyTime_t now;
     uint32_t key[5];
 
-    now = _PyTime_GetSystemClock();
+    now = _PyTime_TimeUnchecked();
     key[0] = (uint32_t)(now & 0xffffffffU);
     key[1] = (uint32_t)(now >> 32);
 
@@ -278,7 +278,7 @@ random_seed_time_pid(RandomObject *self)
     key[2] = 0;
 #endif
 
-    now = _PyTime_GetMonotonicClock();
+    now = _PyTime_MonotonicUnchecked();
     key[3] = (uint32_t)(now & 0xffffffffU);
     key[4] = (uint32_t)(now >> 32);
 

Modules/_testinternalcapi/test_lock.c

@@ -2,7 +2,7 @@
 
 #include "parts.h"
 #include "pycore_lock.h"
-#include "pycore_time.h"          // _PyTime_GetMonotonicClock()
+#include "pycore_time.h"          // _PyTime_MonotonicUnchecked()
 
 #include "clinic/test_lock.c.h"
 
@@ -290,7 +290,7 @@ _testinternalcapi_benchmark_locks_impl(PyObject *module,
         goto exit;
     }
 
-    PyTime_t start = _PyTime_GetMonotonicClock();
+    PyTime_t start = _PyTime_MonotonicUnchecked();
 
     for (Py_ssize_t i = 0; i < num_threads; i++) {
         thread_data[i].bench_data = &bench_data;
@@ -307,7 +307,7 @@ _testinternalcapi_benchmark_locks_impl(PyObject *module,
     }
 
     Py_ssize_t total_iters = bench_data.total_iters;
-    PyTime_t end = _PyTime_GetMonotonicClock();
+    PyTime_t end = _PyTime_MonotonicUnchecked();
 
     // Return the total number of acquisitions and the number of acquisitions
     // for each thread.

Modules/_testsinglephase.c

@@ -71,13 +71,13 @@ _set_initialized(PyTime_t *initialized)
 {
     /* We go strictly monotonic to ensure each time is unique. */
     PyTime_t prev;
-    if (_PyTime_GetMonotonicClockWithInfo(&prev, NULL) != 0) {
+    if (_PyTime_MonotonicWithInfo(&prev, NULL) != 0) {
         return -1;
     }
     /* We do a busy sleep since the interval should be super short. */
     PyTime_t t;
     do {
-        if (_PyTime_GetMonotonicClockWithInfo(&t, NULL) != 0) {
+        if (_PyTime_MonotonicWithInfo(&t, NULL) != 0) {
             return -1;
         }
     } while (t == prev);

Modules/timemodule.c

@@ -106,8 +106,8 @@ _PyFloat_FromPyTime(PyTime_t t)
 static int
 get_system_time(PyTime_t *t)
 {
-    // Avoid _PyTime_GetSystemClock() which silently ignores errors.
-    return _PyTime_GetSystemClockWithInfo(t, NULL);
+    // Avoid _PyTime_TimeUnchecked() which silently ignores errors.
+    return _PyTime_TimeWithInfo(t, NULL);
 }
 
 
@@ -1159,8 +1159,8 @@ should not be relied on.");
 static int
 get_monotonic(PyTime_t *t)
 {
-    // Avoid _PyTime_GetMonotonicClock() which silently ignores errors.
-    return _PyTime_GetMonotonicClockWithInfo(t, NULL);
+    // Avoid _PyTime_MonotonicUnchecked() which silently ignores errors.
+    return _PyTime_MonotonicWithInfo(t, NULL);
 }
 
 
@@ -1198,8 +1198,8 @@ Monotonic clock, cannot go backward, as nanoseconds.");
 static int
 get_perf_counter(PyTime_t *t)
 {
-    // Avoid _PyTime_GetPerfCounter() which silently ignores errors.
-    return _PyTime_GetPerfCounterWithInfo(t, NULL);
+    // Avoid _PyTime_PerfCounterUnchecked() which silently ignores errors.
+    return _PyTime_PerfCounterWithInfo(t, NULL);
 }
 
 
@@ -1615,17 +1615,17 @@ time_get_clock_info(PyObject *module, PyObject *args)
 #endif
 
     if (strcmp(name, "time") == 0) {
-        if (_PyTime_GetSystemClockWithInfo(&t, &info) < 0) {
+        if (_PyTime_TimeWithInfo(&t, &info) < 0) {
             return NULL;
         }
     }
     else if (strcmp(name, "monotonic") == 0) {
-        if (_PyTime_GetMonotonicClockWithInfo(&t, &info) < 0) {
+        if (_PyTime_MonotonicWithInfo(&t, &info) < 0) {
             return NULL;
         }
     }
     else if (strcmp(name, "perf_counter") == 0) {
-        if (_PyTime_GetPerfCounterWithInfo(&t, &info) < 0) {
+        if (_PyTime_PerfCounterWithInfo(&t, &info) < 0) {
             return NULL;
         }
     }

Python/gc.c

@@ -12,7 +12,7 @@
 #include "pycore_object_alloc.h"  // _PyObject_MallocWithType()
 #include "pycore_pyerrors.h"
 #include "pycore_pystate.h"       // _PyThreadState_GET()
-#include "pycore_time.h"          // _PyTime_GetPerfCounter()
+#include "pycore_time.h"          // _PyTime_PerfCounterUnchecked()
 #include "pycore_weakref.h"       // _PyWeakref_ClearRef()
 #include "pydtrace.h"
 
@@ -1327,7 +1327,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
     if (gcstate->debug & _PyGC_DEBUG_STATS) {
         PySys_WriteStderr("gc: collecting generation %d...\n", generation);
         show_stats_each_generations(gcstate);
-        t1 = _PyTime_GetPerfCounter();
+        t1 = _PyTime_PerfCounterUnchecked();
     }
 
     if (PyDTrace_GC_START_ENABLED()) {
@@ -1428,7 +1428,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
             debug_cycle("uncollectable", FROM_GC(gc));
     }
     if (gcstate->debug & _PyGC_DEBUG_STATS) {
-        double d = _PyTime_AsSecondsDouble(_PyTime_GetPerfCounter() - t1);
+        double d = _PyTime_AsSecondsDouble(_PyTime_PerfCounterUnchecked() - t1);
         PySys_WriteStderr(
             "gc: done, %zd unreachable, %zd uncollectable, %.4fs elapsed\n",
             n+m, n, d);

Python/gc_free_threading.c

@@ -1108,7 +1108,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
     if (gcstate->debug & _PyGC_DEBUG_STATS) {
         PySys_WriteStderr("gc: collecting generation %d...\n", generation);
         show_stats_each_generations(gcstate);
-        t1 = _PyTime_GetPerfCounter();
+        t1 = _PyTime_PerfCounterUnchecked();
     }
 
     if (PyDTrace_GC_START_ENABLED()) {
@@ -1136,7 +1136,7 @@ gc_collect_main(PyThreadState *tstate, int generation, _PyGC_Reason reason)
     n = state.uncollectable;
 
     if (gcstate->debug & _PyGC_DEBUG_STATS) {
-        double d = _PyTime_AsSecondsDouble(_PyTime_GetPerfCounter() - t1);
+        double d = _PyTime_AsSecondsDouble(_PyTime_PerfCounterUnchecked() - t1);
         PySys_WriteStderr(
             "gc: done, %zd unreachable, %zd uncollectable, %.4fs elapsed\n",
             n+m, n, d);

Python/import.c

@@ -13,7 +13,7 @@
 #include "pycore_pymem.h"         // _PyMem_SetDefaultAllocator()
 #include "pycore_pystate.h"       // _PyInterpreterState_GET()
 #include "pycore_sysmodule.h"     // _PySys_Audit()
-#include "pycore_time.h"          // _PyTime_GetPerfCounter()
+#include "pycore_time.h"          // _PyTime_PerfCounterUnchecked()
 #include "pycore_weakref.h"       // _PyWeakref_GET_REF()
 
 #include "marshal.h"              // PyMarshal_ReadObjectFromString()
@@ -2748,7 +2748,7 @@ import_find_and_load(PyThreadState *tstate, PyObject *abs_name)
 #undef header
 
         import_level++;
-        t1 = _PyTime_GetPerfCounter();
+        t1 = _PyTime_PerfCounterUnchecked();
         accumulated = 0;
     }
 
@@ -2763,7 +2763,7 @@ import_find_and_load(PyThreadState *tstate, PyObject *abs_name)
                                        mod != NULL);
 
     if (import_time) {
-        PyTime_t cum = _PyTime_GetPerfCounter() - t1;
+        PyTime_t cum = _PyTime_PerfCounterUnchecked() - t1;
 
         import_level--;
         fprintf(stderr, "import time: %9ld | %10ld | %*s%s\n",

Python/lock.c

@@ -5,7 +5,7 @@
 #include "pycore_lock.h"
 #include "pycore_parking_lot.h"
 #include "pycore_semaphore.h"
-#include "pycore_time.h"          // _PyTime_GetMonotonicClock()
+#include "pycore_time.h"          // _PyTime_MonotonicUnchecked()
 
 #ifdef MS_WINDOWS
 #  define WIN32_LEAN_AND_MEAN
@@ -66,7 +66,7 @@ _PyMutex_LockTimed(PyMutex *m, PyTime_t timeout, _PyLockFlags flags)
         return PY_LOCK_FAILURE;
     }
 
-    PyTime_t now = _PyTime_GetMonotonicClock();
+    PyTime_t now = _PyTime_MonotonicUnchecked();
     PyTime_t endtime = 0;
     if (timeout > 0) {
         endtime = _PyTime_Add(now, timeout);
@@ -143,7 +143,7 @@ mutex_unpark(PyMutex *m, struct mutex_entry *entry, int has_more_waiters)
 {
     uint8_t v = 0;
     if (entry) {
-        PyTime_t now = _PyTime_GetMonotonicClock();
+        PyTime_t now = _PyTime_MonotonicUnchecked();
         int should_be_fair = now > entry->time_to_be_fair;
 
         entry->handed_off = should_be_fair;

Python/parking_lot.c

@@ -6,7 +6,7 @@
 #include "pycore_pyerrors.h"      // _Py_FatalErrorFormat
 #include "pycore_pystate.h"       // _PyThreadState_GET
 #include "pycore_semaphore.h"     // _PySemaphore
-#include "pycore_time.h"          //_PyTime_GetMonotonicClock()
+#include "pycore_time.h"          //_PyTime_MonotonicUnchecked()
 
 #include <stdbool.h>
 
@@ -120,13 +120,13 @@ _PySemaphore_PlatformWait(_PySemaphore *sema, PyTime_t timeout)
         struct timespec ts;
 
 #if defined(CLOCK_MONOTONIC) && defined(HAVE_SEM_CLOCKWAIT)
-        PyTime_t deadline = _PyTime_Add(_PyTime_GetMonotonicClock(), timeout);
+        PyTime_t deadline = _PyTime_Add(_PyTime_MonotonicUnchecked(), timeout);
 
         _PyTime_AsTimespec_clamp(deadline, &ts);
 
         err = sem_clockwait(&sema->platform_sem, CLOCK_MONOTONIC, &ts);
 #else
-        PyTime_t deadline = _PyTime_Add(_PyTime_GetSystemClock(), timeout);
+        PyTime_t deadline = _PyTime_Add(_PyTime_TimeUnchecked(), timeout);
 
         _PyTime_AsTimespec_clamp(deadline, &ts);
 
@@ -163,7 +163,7 @@ _PySemaphore_PlatformWait(_PySemaphore *sema, PyTime_t timeout)
             _PyTime_AsTimespec_clamp(timeout, &ts);
             err = pthread_cond_timedwait_relative_np(&sema->cond, &sema->mutex, &ts);
 #else
-            PyTime_t deadline = _PyTime_Add(_PyTime_GetSystemClock(), timeout);
+            PyTime_t deadline = _PyTime_Add(_PyTime_TimeUnchecked(), timeout);
             _PyTime_AsTimespec_clamp(deadline, &ts);
 
             err = pthread_cond_timedwait(&sema->cond, &sema->mutex, &ts);