gh-107211: No longer export PyTime internal functions (#108422)

No longer export these 2 internal C API functions:

* _PyTime_AsNanoseconds()
* _PyTime_GetSystemClockWithInfo()

Change comment style to "// comment" and add comment explaining why
other functions have to be exported.

Include/internal/pycore_time.h

@@ -66,9 +66,9 @@ struct _time_runtime_state {
 struct timeval;
 #endif
 
-/* _PyTime_t: Python timestamp with subsecond precision. It can be used to
+// _PyTime_t: Python timestamp with subsecond precision. It can be used to
-   store a duration, and so indirectly a date (related to another date, like
+// store a duration, and so indirectly a date (related to another date, like
-   UNIX epoch). */
+// UNIX epoch).
 typedef int64_t _PyTime_t;
 // _PyTime_MIN nanoseconds is around -292.3 years
 #define _PyTime_MIN INT64_MIN
@@ -77,52 +77,61 @@ typedef int64_t _PyTime_t;
 #define _SIZEOF_PYTIME_T 8
 
 typedef enum {
-    /* Round towards minus infinity (-inf).
+    // Round towards minus infinity (-inf).
-       For example, used to read a clock. */
+    // For example, used to read a clock.
     _PyTime_ROUND_FLOOR=0,
-    /* Round towards infinity (+inf).
+
-       For example, used for timeout to wait "at least" N seconds. */
+    // Round towards infinity (+inf).
+    // For example, used for timeout to wait "at least" N seconds.
     _PyTime_ROUND_CEILING=1,
-    /* Round to nearest with ties going to nearest even integer.
+
-       For example, used to round from a Python float. */
+    // Round to nearest with ties going to nearest even integer.
+    // For example, used to round from a Python float.
     _PyTime_ROUND_HALF_EVEN=2,
-    /* Round away from zero
+
-       For example, used for timeout. _PyTime_ROUND_CEILING rounds
+    // Round away from zero
-       -1e-9 to 0 milliseconds which causes bpo-31786 issue.
+    // For example, used for timeout. _PyTime_ROUND_CEILING rounds
-       _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps
+    // -1e-9 to 0 milliseconds which causes bpo-31786 issue.
-       the timeout sign as expected. select.poll(timeout) must block
+    // _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps
-       for negative values." */
+    // the timeout sign as expected. select.poll(timeout) must block
+    // for negative values.
     _PyTime_ROUND_UP=3,
-    /* _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be
+
-       used for timeouts. */
+    // _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be
+    // used for timeouts.
     _PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP
 } _PyTime_round_t;
 
 
-/* Convert a time_t to a PyLong. */
+// Convert a time_t to a PyLong.
+// Export for '_testinternalcapi' shared extension
 PyAPI_FUNC(PyObject*) _PyLong_FromTime_t(time_t sec);
 
-/* Convert a PyLong to a time_t. */
+// Convert a PyLong to a time_t.
+// Export for '_datetime' shared extension
 PyAPI_FUNC(time_t) _PyLong_AsTime_t(PyObject *obj);
 
-/* Convert a number of seconds, int or float, to time_t. */
+// Convert a number of seconds, int or float, to time_t.
+// Export for '_datetime' shared extension.
 PyAPI_FUNC(int) _PyTime_ObjectToTime_t(
     PyObject *obj,
     time_t *sec,
     _PyTime_round_t);
 
-/* Convert a number of seconds, int or float, to a timeval structure.
+// Convert a number of seconds, int or float, to a timeval structure.
-   usec is in the range [0; 999999] and rounded towards zero.
+// usec is in the range [0; 999999] and rounded towards zero.
-   For example, -1.2 is converted to (-2, 800000). */
+// For example, -1.2 is converted to (-2, 800000).
+// Export for '_datetime' shared extension.
 PyAPI_FUNC(int) _PyTime_ObjectToTimeval(
     PyObject *obj,
     time_t *sec,
     long *usec,
     _PyTime_round_t);
 
-/* Convert a number of seconds, int or float, to a timespec structure.
+// Convert a number of seconds, int or float, to a timespec structure.
-   nsec is in the range [0; 999999999] and rounded towards zero.
+// nsec is in the range [0; 999999999] and rounded towards zero.
-   For example, -1.2 is converted to (-2, 800000000). */
+// For example, -1.2 is converted to (-2, 800000000).
+// Export for '_testinternalcapi' shared extension.
 PyAPI_FUNC(int) _PyTime_ObjectToTimespec(
     PyObject *obj,
     time_t *sec,
@@ -130,50 +139,58 @@ PyAPI_FUNC(int) _PyTime_ObjectToTimespec(
     _PyTime_round_t);
 
 
-/* Create a timestamp from a number of seconds. */
+// Create a timestamp from a number of seconds.
+// Export for '_socket' shared extension.
 PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds);
 
-/* Macro to create a timestamp from a number of seconds, no integer overflow.
+// Macro to create a timestamp from a number of seconds, no integer overflow.
-   Only use the macro for small values, prefer _PyTime_FromSeconds(). */
+// Only use the macro for small values, prefer _PyTime_FromSeconds().
 #define _PYTIME_FROMSECONDS(seconds) \
             ((_PyTime_t)(seconds) * (1000 * 1000 * 1000))
 
-/* Create a timestamp from a number of nanoseconds. */
+// Create a timestamp from a number of nanoseconds.
+// Export for '_testinternalcapi' shared extension.
 PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(_PyTime_t ns);
 
-/* Create a timestamp from a number of microseconds.
+// Create a timestamp from a number of microseconds.
- * Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow. */
+// Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow.
 extern _PyTime_t _PyTime_FromMicrosecondsClamp(_PyTime_t us);
 
-/* Create a timestamp from nanoseconds (Python int). */
+// Create a timestamp from nanoseconds (Python int).
+// Export for '_lsprof' shared extension.
 PyAPI_FUNC(int) _PyTime_FromNanosecondsObject(_PyTime_t *t,
     PyObject *obj);
 
-/* Convert a number of seconds (Python float or int) to a timestamp.
+// Convert a number of seconds (Python float or int) to a timestamp.
-   Raise an exception and return -1 on error, return 0 on success. */
+// Raise an exception and return -1 on error, return 0 on success.
+// Export for '_socket' shared extension.
 PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t,
     PyObject *obj,
     _PyTime_round_t round);
 
-/* Convert a number of milliseconds (Python float or int, 10^-3) to a timestamp.
+// Convert a number of milliseconds (Python float or int, 10^-3) to a timestamp.
-   Raise an exception and return -1 on error, return 0 on success. */
+// Raise an exception and return -1 on error, return 0 on success.
+// Export for 'select' shared extension.
 PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t,
     PyObject *obj,
     _PyTime_round_t round);
 
-/* Convert a timestamp to a number of seconds as a C double. */
+// Convert a timestamp to a number of seconds as a C double.
+// Export for '_socket' shared extension.
 PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t);
 
-/* Convert timestamp to a number of milliseconds (10^-3 seconds). */
+// Convert timestamp to a number of milliseconds (10^-3 seconds).
+// Export for '_ssl' shared extension.
 PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t,
     _PyTime_round_t round);
 
-/* Convert timestamp to a number of microseconds (10^-6 seconds). */
+// Convert timestamp to a number of microseconds (10^-6 seconds).
+// Export for '_queue' shared extension.
 PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t,
     _PyTime_round_t round);
 
-/* Convert timestamp to a number of nanoseconds (10^-9 seconds). */
+// Convert timestamp to a number of nanoseconds (10^-9 seconds).
-PyAPI_FUNC(_PyTime_t) _PyTime_AsNanoseconds(_PyTime_t t);
+extern _PyTime_t _PyTime_AsNanoseconds(_PyTime_t t);
 
 #ifdef MS_WINDOWS
 // Convert timestamp to a number of 100 nanoseconds (10^-7 seconds).
@@ -181,36 +198,40 @@ extern _PyTime_t _PyTime_As100Nanoseconds(_PyTime_t t,
     _PyTime_round_t round);
 #endif
 
-/* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int
+// Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int
-   object. */
+// object.
+// Export for '_testinternalcapi' shared extension.
 PyAPI_FUNC(PyObject*) _PyTime_AsNanosecondsObject(_PyTime_t t);
 
 #ifndef MS_WINDOWS
-/* Create a timestamp from a timeval structure.
+// Create a timestamp from a timeval structure.
-   Raise an exception and return -1 on overflow, return 0 on success. */
+// Raise an exception and return -1 on overflow, return 0 on success.
 extern int _PyTime_FromTimeval(_PyTime_t *tp, struct timeval *tv);
 #endif
 
-/* Convert a timestamp to a timeval structure (microsecond resolution).
+// Convert a timestamp to a timeval structure (microsecond resolution).
-   tv_usec is always positive.
+// tv_usec is always positive.
-   Raise an exception and return -1 if the conversion overflowed,
+// Raise an exception and return -1 if the conversion overflowed,
-   return 0 on success. */
+// return 0 on success.
+// Export for 'select' shared extension.
 PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t,
     struct timeval *tv,
     _PyTime_round_t round);
 
-/* Similar to _PyTime_AsTimeval() but don't raise an exception on overflow.
+// Similar to _PyTime_AsTimeval() but don't raise an exception on overflow.
-   On overflow, clamp tv_sec to _PyTime_t min/max. */
+// On overflow, clamp tv_sec to _PyTime_t min/max.
+// Export for 'select' shared extension.
 PyAPI_FUNC(void) _PyTime_AsTimeval_clamp(_PyTime_t t,
     struct timeval *tv,
     _PyTime_round_t round);
 
-/* Convert a timestamp to a number of seconds (secs) and microseconds (us).
+// Convert a timestamp to a number of seconds (secs) and microseconds (us).
-   us is always positive. This function is similar to _PyTime_AsTimeval()
+// us is always positive. This function is similar to _PyTime_AsTimeval()
-   except that secs is always a time_t type, whereas the timeval structure
+// except that secs is always a time_t type, whereas the timeval structure
-   uses a C long for tv_sec on Windows.
+// uses a C long for tv_sec on Windows.
-   Raise an exception and return -1 if the conversion overflowed,
+// Raise an exception and return -1 if the conversion overflowed,
-   return 0 on success. */
+// return 0 on success.
+// Export for '_datetime' shared extension.
 PyAPI_FUNC(int) _PyTime_AsTimevalTime_t(
     _PyTime_t t,
     time_t *secs,
@@ -218,17 +239,19 @@ PyAPI_FUNC(int) _PyTime_AsTimevalTime_t(
     _PyTime_round_t round);
 
 #if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE)
-/* Create a timestamp from a timespec structure.
+// Create a timestamp from a timespec structure.
-   Raise an exception and return -1 on overflow, return 0 on success. */
+// Raise an exception and return -1 on overflow, return 0 on success.
 extern int _PyTime_FromTimespec(_PyTime_t *tp, struct timespec *ts);
 
-/* Convert a timestamp to a timespec structure (nanosecond resolution).
+// Convert a timestamp to a timespec structure (nanosecond resolution).
-   tv_nsec is always positive.
+// tv_nsec is always positive.
-   Raise an exception and return -1 on error, return 0 on success. */
+// Raise an exception and return -1 on error, return 0 on success.
+// Export for '_testinternalcapi' shared extension.
 PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts);
 
-/* Similar to _PyTime_AsTimespec() but don't raise an exception on overflow.
+// Similar to _PyTime_AsTimespec() but don't raise an exception on overflow.
-   On overflow, clamp tv_sec to _PyTime_t min/max. */
+// On overflow, clamp tv_sec to _PyTime_t min/max.
+// Export for '_testinternalcapi' shared extension.
 PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(_PyTime_t t, struct timespec *ts);
 #endif
 
@@ -236,14 +259,14 @@ PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(_PyTime_t t, struct timespec *ts);
 // Compute t1 + t2. Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow.
 extern _PyTime_t _PyTime_Add(_PyTime_t t1, _PyTime_t t2);
 
-/* Compute ticks * mul / div.
+// Compute ticks * mul / div.
-   Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow.
+// Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow.
-   The caller must ensure that ((div - 1) * mul) cannot overflow. */
+// The caller must ensure that ((div - 1) * mul) cannot overflow.
 extern _PyTime_t _PyTime_MulDiv(_PyTime_t ticks,
     _PyTime_t mul,
     _PyTime_t div);
 
-/* Structure used by time.get_clock_info() */
+// Structure used by time.get_clock_info()
 typedef struct {
     const char *implementation;
     int monotonic;
@@ -251,72 +274,77 @@ typedef struct {
     double resolution;
 } _Py_clock_info_t;
 
-/* Get the current time from the system clock.
+// Get the current time from the system clock.
-
+//
-   If the internal clock fails, silently ignore the error and return 0.
+// If the internal clock fails, silently ignore the error and return 0.
-   On integer overflow, silently ignore the overflow and clamp the clock to
+// On integer overflow, silently ignore the overflow and clamp the clock to
-   [_PyTime_MIN; _PyTime_MAX].
+// [_PyTime_MIN; _PyTime_MAX].
-
+//
-   Use _PyTime_GetSystemClockWithInfo() to check for failure. */
+// Use _PyTime_GetSystemClockWithInfo() to check for failure.
+// Export for '_random' shared extension.
 PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void);
 
-/* Get the current time from the system clock.
+// Get the current time from the system clock.
- * On success, set *t and *info (if not NULL), and return 0.
+// On success, set *t and *info (if not NULL), and return 0.
- * On error, raise an exception and return -1.
+// On error, raise an exception and return -1.
- */
+extern int _PyTime_GetSystemClockWithInfo(
-PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo(
     _PyTime_t *t,
     _Py_clock_info_t *info);
 
-/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
+// 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 clock is not affected by system clock updates. The reference point of
-   the returned value is undefined, so that only the difference between the
+// the returned value is undefined, so that only the difference between the
-   results of consecutive calls is valid.
+// results of consecutive calls is valid.
-
+//
-   If the internal clock fails, silently ignore the error and return 0.
+// If the internal clock fails, silently ignore the error and return 0.
-   On integer overflow, silently ignore the overflow and clamp the clock to
+// On integer overflow, silently ignore the overflow and clamp the clock to
-   [_PyTime_MIN; _PyTime_MAX].
+// [_PyTime_MIN; _PyTime_MAX].
-
+//
-   Use _PyTime_GetMonotonicClockWithInfo() to check for failure. */
+// Use _PyTime_GetMonotonicClockWithInfo() to check for failure.
+// Export for '_random' shared extension.
 PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void);
 
-/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
+// 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 clock is not affected by system clock updates. The reference point of
-   the returned value is undefined, so that only the difference between the
+// the returned value is undefined, so that only the difference between the
-   results of consecutive calls is valid.
+// results of consecutive calls is valid.
-
+//
-   Fill info (if set) with information of the function used to get the time.
+// 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. */
+// Return 0 on success, raise an exception and return -1 on error.
+// Export for '_testsinglephase' shared extension.
 PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo(
     _PyTime_t *t,
     _Py_clock_info_t *info);
 
 
-/* Converts a timestamp to the Gregorian time, using the local time zone.
+// Converts a timestamp to the Gregorian time, using the local time zone.
-   Return 0 on success, raise an exception and return -1 on error. */
+// Return 0 on success, raise an exception and return -1 on error.
+// Export for '_datetime' shared extension.
 PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm);
 
-/* Converts a timestamp to the Gregorian time, assuming UTC.
+// Converts a timestamp to the Gregorian time, assuming UTC.
-   Return 0 on success, raise an exception and return -1 on error. */
+// Return 0 on success, raise an exception and return -1 on error.
+// 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
+// Get the performance counter: clock with the highest available resolution to
-   measure a short duration.
+// measure a short duration.
-
+//
-   If the internal clock fails, silently ignore the error and return 0.
+// If the internal clock fails, silently ignore the error and return 0.
-   On integer overflow, silently ignore the overflow and clamp the clock to
+// On integer overflow, silently ignore the overflow and clamp the clock to
-   [_PyTime_MIN; _PyTime_MAX].
+// [_PyTime_MIN; _PyTime_MAX].
-
+//
-   Use _PyTime_GetPerfCounterWithInfo() to check for failure. */
+// Use _PyTime_GetPerfCounterWithInfo() to check for failure.
+// Export for '_lsprof' shared extension.
 PyAPI_FUNC(_PyTime_t) _PyTime_GetPerfCounter(void);
 
-/* Get the performance counter: clock with the highest available resolution to
+// Get the performance counter: clock with the highest available resolution to
-   measure a short duration.
+// measure a short duration.
-
+//
-   Fill info (if set) with information of the function used to get the time.
+// 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. */
+// Return 0 on success, raise an exception and return -1 on error.
 extern int _PyTime_GetPerfCounterWithInfo(
     _PyTime_t *t,
     _Py_clock_info_t *info);
@@ -336,4 +364,4 @@ PyAPI_FUNC(_PyTime_t) _PyDeadline_Get(_PyTime_t deadline);
 #ifdef __cplusplus
 }
 #endif
-#endif /* !Py_INTERNAL_TIME_H */
+#endif   // !Py_INTERNAL_TIME_H