Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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.
This commit is contained in:
Victor Stinner 2023-08-24 17:17:40 +02:00 committed by GitHub
parent a35d48d4bd
commit 3f7e93be51
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 146 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

264
Include/internal/pycore_time.h
View File

@ -66,9 +66,9 @@ struct _time_runtime_state {
struct timeval;
#endif
/* _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
UNIX epoch). */
// _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
// 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).
For example, used to read a clock. */
// Round towards minus infinity (-inf).
// 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
-1e-9 to 0 milliseconds which causes bpo-31786 issue.
_PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps
the timeout sign as expected. select.poll(timeout) must block
for negative values." */
// Round away from zero
// For example, used for timeout. _PyTime_ROUND_CEILING rounds
// -1e-9 to 0 milliseconds which causes bpo-31786 issue.
// _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps
// 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.
usec is in the range [0; 999999] and rounded towards zero.
For example, -1.2 is converted to (-2, 800000). */
// Convert a number of seconds, int or float, to a timeval structure.
// usec is in the range [0; 999999] and rounded towards zero.
// 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.
nsec is in the range [0; 999999999] and rounded towards zero.
For example, -1.2 is converted to (-2, 800000000). */
// Convert a number of seconds, int or float, to a timespec structure.
// nsec is in the range [0; 999999999] and rounded towards zero.
// 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.
Only use the macro for small values, prefer _PyTime_FromSeconds(). */
// Macro to create a timestamp from a number of seconds, no integer overflow.
// 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.
* Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow. */
// Create a timestamp from a number of microseconds.
// 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.
Raise an exception and return -1 on error, return 0 on success. */
// Convert a number of seconds (Python float or int) to a timestamp.
// 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.
Raise an exception and return -1 on error, return 0 on success. */
// 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.
// 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). */
PyAPI_FUNC(_PyTime_t) _PyTime_AsNanoseconds(_PyTime_t t);
// Convert timestamp to a number of nanoseconds (10^-9 seconds).
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
object. */
// Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int
// object.
// Export for '_testinternalcapi' shared extension.
PyAPI_FUNC(PyObject*) _PyTime_AsNanosecondsObject(_PyTime_t t);
#ifndef MS_WINDOWS
/* Create a timestamp from a timeval structure.
Raise an exception and return -1 on overflow, return 0 on success. */
// Create a timestamp from a timeval structure.
// 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).
tv_usec is always positive.
Raise an exception and return -1 if the conversion overflowed,
return 0 on success. */
// Convert a timestamp to a timeval structure (microsecond resolution).
// tv_usec is always positive.
// Raise an exception and return -1 if the conversion overflowed,
// 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.
On overflow, clamp tv_sec to _PyTime_t min/max. */
// Similar to _PyTime_AsTimeval() but don't raise an exception on overflow.
// 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).
us is always positive. This function is similar to _PyTime_AsTimeval()
except that secs is always a time_t type, whereas the timeval structure
uses a C long for tv_sec on Windows.
Raise an exception and return -1 if the conversion overflowed,
return 0 on success. */
// Convert a timestamp to a number of seconds (secs) and microseconds (us).
// us is always positive. This function is similar to _PyTime_AsTimeval()
// except that secs is always a time_t type, whereas the timeval structure
// uses a C long for tv_sec on Windows.
// Raise an exception and return -1 if the conversion overflowed,
// 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.
Raise an exception and return -1 on overflow, return 0 on success. */
// Create a timestamp from a timespec structure.
// 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).
tv_nsec is always positive.
Raise an exception and return -1 on error, return 0 on success. */
// Convert a timestamp to a timespec structure (nanosecond resolution).
// tv_nsec is always positive.
// 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.
On overflow, clamp tv_sec to _PyTime_t min/max. */
// Similar to _PyTime_AsTimespec() but don't raise an exception on overflow.
// 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.
Clamp to [_PyTime_MIN; _PyTime_MAX] on overflow.
The caller must ensure that ((div - 1) * mul) cannot overflow. */
// Compute ticks * mul / div.
// Clamp to [_PyTime_MIN; _PyTime_MAX] on 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.
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_GetSystemClockWithInfo() to check for failure. */
// 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].
//
// 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.
* On success, set *t and *info (if not NULL), and return 0.
* On error, raise an exception and return -1.
*/
PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo(
// 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(
_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.
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() to check for failure. */
// 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.
//
// 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() 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.
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.
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. */
// 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.
//
// 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.
// 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.
Return 0 on success, raise an exception and return -1 on error. */
// Converts a timestamp to the Gregorian time, using the local time zone.
// 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.
Return 0 on success, raise an exception and return -1 on error. */
// Converts a timestamp to the Gregorian time, assuming UTC.
// 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
measure a short duration.
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() to check for failure. */
// Get the performance counter: clock with the highest available resolution to
// measure a short duration.
//
// 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() 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
measure a short duration.
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. */
// Get the performance counter: clock with the highest available resolution to
// measure a short duration.
//
// 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(
_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