codekingpro/portable-devtools

1// Internal PyTime_t C API: see Doc/c-api/time.rst for the documentation.2//3// The PyTime_t type is an integer to support directly common arithmetic4// operations such as t1 + t2.5//6// Time formats:7//8// * Seconds.9// * Seconds as a floating-point number (C double).10// * Milliseconds (10^-3 seconds).11// * Microseconds (10^-6 seconds).12// * 100 nanoseconds (10^-7 seconds), used on Windows.13// * Nanoseconds (10^-9 seconds).14// * timeval structure, 1 microsecond (10^-6 seconds).15// * timespec structure, 1 nanosecond (10^-9 seconds).16//17// Note that PyTime_t is now specified as int64_t, in nanoseconds.18// (If we need to change this, we'll need new public API with new names.)19// Previously, PyTime_t was configurable (in theory); some comments and code20// might still allude to that.21//22// Integer overflows are detected and raise OverflowError. Conversion to a23// resolution larger than 1 nanosecond is rounded correctly with the requested24// rounding mode. Available rounding modes:25//26// * Round towards minus infinity (-inf). For example, used to read a clock.27// * Round towards infinity (+inf). For example, used for timeout to wait "at28//   least" N seconds.29// * Round to nearest with ties going to nearest even integer. For example, used30//   to round from a Python float.31// * Round away from zero. For example, used for timeout.32//33// Some functions clamp the result in the range [PyTime_MIN; PyTime_MAX]. The34// caller doesn't have to handle errors and so doesn't need to hold the GIL to35// handle exceptions. For example, _PyTime_Add(t1, t2) computes t1+t2 and36// clamps the result on overflow.37//38// Clocks:39//40// * System clock41// * Monotonic clock42// * Performance counter43//44// Internally, operations like (t * k / q) with integers are implemented in a45// way to reduce the risk of integer overflow. Such operation is used to convert a46// clock value expressed in ticks with a frequency to PyTime_t, like47// QueryPerformanceCounter() with QueryPerformanceFrequency() on Windows.48 49 50#ifndef Py_INTERNAL_TIME_H51#define Py_INTERNAL_TIME_H52#ifdef __cplusplus53extern "C" {54#endif55 56#ifndef Py_BUILD_CORE57#  error "this header requires Py_BUILD_CORE define"58#endif59 60#include "pycore_runtime_structs.h" // _PyTimeFraction61 62#ifdef __clang__63struct timeval;64#endif65 66#define _SIZEOF_PYTIME_T 867 68typedef enum {69    // Round towards minus infinity (-inf).70    // For example, used to read a clock.71    _PyTime_ROUND_FLOOR=0,72 73    // Round towards infinity (+inf).74    // For example, used for timeout to wait "at least" N seconds.75    _PyTime_ROUND_CEILING=1,76 77    // Round to nearest with ties going to nearest even integer.78    // For example, used to round from a Python float.79    _PyTime_ROUND_HALF_EVEN=2,80 81    // Round away from zero82    // For example, used for timeout. _PyTime_ROUND_CEILING rounds83    // -1e-9 to 0 milliseconds which causes bpo-31786 issue.84    // _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps85    // the timeout sign as expected. select.poll(timeout) must block86    // for negative values.87    _PyTime_ROUND_UP=3,88 89    // _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be90    // used for timeouts.91    _PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP92} _PyTime_round_t;93 94 95// Convert a time_t to a PyLong.96// Export for '_testinternalcapi' shared extension97PyAPI_FUNC(PyObject*) _PyLong_FromTime_t(time_t sec);98 99// Convert a PyLong to a time_t.100// Export for '_datetime' shared extension101PyAPI_FUNC(time_t) _PyLong_AsTime_t(PyObject *obj);102 103// Convert a number of seconds, int or float, to time_t.104// Export for '_datetime' shared extension.105PyAPI_FUNC(int) _PyTime_ObjectToTime_t(106    PyObject *obj,107    time_t *sec,108    _PyTime_round_t);109 110// Convert a number of seconds, int or float, to a timeval structure.111// usec is in the range [0; 999999] and rounded towards zero.112// For example, -1.2 is converted to (-2, 800000).113// Export for '_datetime' shared extension.114PyAPI_FUNC(int) _PyTime_ObjectToTimeval(115    PyObject *obj,116    time_t *sec,117    long *usec,118    _PyTime_round_t);119 120// Convert a number of seconds, int or float, to a timespec structure.121// nsec is in the range [0; 999999999] and rounded towards zero.122// For example, -1.2 is converted to (-2, 800000000).123// Export for '_testinternalcapi' shared extension.124PyAPI_FUNC(int) _PyTime_ObjectToTimespec(125    PyObject *obj,126    time_t *sec,127    long *nsec,128    _PyTime_round_t);129 130 131// Create a timestamp from a number of seconds.132// Export for '_socket' shared extension.133PyAPI_FUNC(PyTime_t) _PyTime_FromSeconds(int seconds);134 135// Create a timestamp from a number of seconds in double.136extern int _PyTime_FromSecondsDouble(137    double seconds,138    _PyTime_round_t round,139    PyTime_t *result);140 141// Macro to create a timestamp from a number of seconds, no integer overflow.142// Only use the macro for small values, prefer _PyTime_FromSeconds().143#define _PYTIME_FROMSECONDS(seconds) \144            ((PyTime_t)(seconds) * (1000 * 1000 * 1000))145 146// Create a timestamp from a number of microseconds.147// Clamp to [PyTime_MIN; PyTime_MAX] on overflow.148extern PyTime_t _PyTime_FromMicrosecondsClamp(PyTime_t us);149 150// Create a timestamp from a Python int object (number of nanoseconds).151// Export for '_lsprof' shared extension.152PyAPI_FUNC(int) _PyTime_FromLong(PyTime_t *t,153    PyObject *obj);154 155// Convert a number of seconds (Python float or int) to a timestamp.156// Raise an exception and return -1 on error, return 0 on success.157// Export for '_socket' shared extension.158PyAPI_FUNC(int) _PyTime_FromSecondsObject(PyTime_t *t,159    PyObject *obj,160    _PyTime_round_t round);161 162// Convert a number of milliseconds (Python float or int, 10^-3) to a timestamp.163// Raise an exception and return -1 on error, return 0 on success.164// Export for 'select' shared extension.165PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(PyTime_t *t,166    PyObject *obj,167    _PyTime_round_t round);168 169// Convert timestamp to a number of milliseconds (10^-3 seconds).170// Export for '_ssl' shared extension.171PyAPI_FUNC(PyTime_t) _PyTime_AsMilliseconds(PyTime_t t,172    _PyTime_round_t round);173 174// Convert timestamp to a number of microseconds (10^-6 seconds).175// Export for '_queue' shared extension.176PyAPI_FUNC(PyTime_t) _PyTime_AsMicroseconds(PyTime_t t,177    _PyTime_round_t round);178 179#ifdef MS_WINDOWS180// Convert timestamp to a number of 100 nanoseconds (10^-7 seconds).181extern PyTime_t _PyTime_As100Nanoseconds(PyTime_t t,182    _PyTime_round_t round);183#endif184 185// Convert a timestamp (number of nanoseconds) as a Python int object.186// Export for '_testinternalcapi' shared extension.187PyAPI_FUNC(PyObject*) _PyTime_AsLong(PyTime_t t);188 189#ifndef MS_WINDOWS190// Create a timestamp from a timeval structure.191// Raise an exception and return -1 on overflow, return 0 on success.192extern int _PyTime_FromTimeval(PyTime_t *tp, struct timeval *tv);193#endif194 195// Convert a timestamp to a timeval structure (microsecond resolution).196// tv_usec is always positive.197// Raise an exception and return -1 if the conversion overflowed,198// return 0 on success.199// Export for 'select' shared extension.200PyAPI_FUNC(int) _PyTime_AsTimeval(PyTime_t t,201    struct timeval *tv,202    _PyTime_round_t round);203 204// Similar to _PyTime_AsTimeval() but don't raise an exception on overflow.205// On overflow, clamp tv_sec to PyTime_t min/max.206// Export for 'select' shared extension.207PyAPI_FUNC(void) _PyTime_AsTimeval_clamp(PyTime_t t,208    struct timeval *tv,209    _PyTime_round_t round);210 211// Convert a timestamp to a number of seconds (secs) and microseconds (us).212// us is always positive. This function is similar to _PyTime_AsTimeval()213// except that secs is always a time_t type, whereas the timeval structure214// uses a C long for tv_sec on Windows.215// Raise an exception and return -1 if the conversion overflowed,216// return 0 on success.217// Export for '_datetime' shared extension.218PyAPI_FUNC(int) _PyTime_AsTimevalTime_t(219    PyTime_t t,220    time_t *secs,221    int *us,222    _PyTime_round_t round);223 224#if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE)225// Create a timestamp from a timespec structure.226// Raise an exception and return -1 on overflow, return 0 on success.227extern int _PyTime_FromTimespec(PyTime_t *tp, const struct timespec *ts);228 229// Convert a timestamp to a timespec structure (nanosecond resolution).230// tv_nsec is always positive.231// Raise an exception and return -1 on error, return 0 on success.232// Export for '_testinternalcapi' shared extension.233PyAPI_FUNC(int) _PyTime_AsTimespec(PyTime_t t, struct timespec *ts);234 235// Similar to _PyTime_AsTimespec() but don't raise an exception on overflow.236// On overflow, clamp tv_sec to PyTime_t min/max.237// Export for '_testinternalcapi' shared extension.238PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(PyTime_t t, struct timespec *ts);239#endif240 241 242// Compute t1 + t2. Clamp to [PyTime_MIN; PyTime_MAX] on overflow.243extern PyTime_t _PyTime_Add(PyTime_t t1, PyTime_t t2);244 245// Structure used by time.get_clock_info()246typedef struct {247    const char *implementation;248    int monotonic;249    int adjustable;250    double resolution;251} _Py_clock_info_t;252 253// Get the current time from the system clock.254// On success, set *t and *info (if not NULL), and return 0.255// On error, raise an exception and return -1.256extern int _PyTime_TimeWithInfo(257    PyTime_t *t,258    _Py_clock_info_t *info);259 260// Get the time of a monotonic clock, i.e. a clock that cannot go backwards.261// The clock is not affected by system clock updates. The reference point of262// the returned value is undefined, so that only the difference between the263// results of consecutive calls is valid.264//265// Fill info (if set) with information of the function used to get the time.266//267// Return 0 on success, raise an exception and return -1 on error.268// Export for '_testsinglephase' shared extension.269PyAPI_FUNC(int) _PyTime_MonotonicWithInfo(270    PyTime_t *t,271    _Py_clock_info_t *info);272 273 274// Converts a timestamp to the Gregorian time, using the local time zone.275// Return 0 on success, raise an exception and return -1 on error.276// Export for '_datetime' shared extension.277PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm);278 279// Converts a timestamp to the Gregorian time, assuming UTC.280// Return 0 on success, raise an exception and return -1 on error.281// Export for '_datetime' shared extension.282PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm);283 284 285// Get the performance counter: clock with the highest available resolution to286// measure a short duration.287//288// Fill info (if set) with information of the function used to get the time.289//290// Return 0 on success, raise an exception and return -1 on error.291extern int _PyTime_PerfCounterWithInfo(292    PyTime_t *t,293    _Py_clock_info_t *info);294 295 296// --- _PyDeadline -----------------------------------------------------------297 298// Create a deadline.299// Pseudo code: return PyTime_MonotonicRaw() + timeout300// Export for '_ssl' shared extension.301PyAPI_FUNC(PyTime_t) _PyDeadline_Init(PyTime_t timeout);302 303// Get remaining time from a deadline.304// Pseudo code: return deadline - PyTime_MonotonicRaw()305// Export for '_ssl' shared extension.306PyAPI_FUNC(PyTime_t) _PyDeadline_Get(PyTime_t deadline);307 308 309// --- _PyTimeFraction -------------------------------------------------------310 311// Set a fraction.312// Return 0 on success.313// Return -1 if the fraction is invalid.314extern int _PyTimeFraction_Set(315    _PyTimeFraction *frac,316    PyTime_t numer,317    PyTime_t denom);318 319// Compute ticks * frac.numer / frac.denom.320// Clamp to [PyTime_MIN; PyTime_MAX] on overflow.321extern PyTime_t _PyTimeFraction_Mul(322    PyTime_t ticks,323    const _PyTimeFraction *frac);324 325// Compute a clock resolution: frac.numer / frac.denom / 1e9.326extern double _PyTimeFraction_Resolution(327    const _PyTimeFraction *frac);328 329extern PyStatus _PyTime_Init(struct _Py_time_runtime_state *state);330 331#ifdef __cplusplus332}333#endif334#endif   // !Py_INTERNAL_TIME_H335