|
| 1 | +#ifndef Py_LIMITED_API |
| 2 | +#ifndef Py_PYTIME_H |
| 3 | +#define Py_PYTIME_H |
| 4 | + |
| 5 | +#include "pyconfig.h" /* include for defines */ |
| 6 | +#include "object.h" |
| 7 | + |
| 8 | +/************************************************************************** |
| 9 | +Symbols and macros to supply platform-independent interfaces to time related |
| 10 | +functions and constants |
| 11 | +**************************************************************************/ |
| 12 | +#ifdef __cplusplus |
| 13 | +extern "C" { |
| 14 | +#endif |
| 15 | + |
| 16 | +/* _PyTime_t: Python timestamp with subsecond precision. It can be used to |
| 17 | + store a duration, and so indirectly a date (related to another date, like |
| 18 | + UNIX epoch). */ |
| 19 | +typedef int64_t _PyTime_t; |
| 20 | +#define _PyTime_MIN INT64_MIN |
| 21 | +#define _PyTime_MAX INT64_MAX |
| 22 | + |
| 23 | +typedef enum { |
| 24 | + /* Round towards minus infinity (-inf). |
| 25 | + For example, used to read a clock. */ |
| 26 | + _PyTime_ROUND_FLOOR=0, |
| 27 | + /* Round towards infinity (+inf). |
| 28 | + For example, used for timeout to wait "at least" N seconds. */ |
| 29 | + _PyTime_ROUND_CEILING=1, |
| 30 | + /* Round to nearest with ties going to nearest even integer. |
| 31 | + For example, used to round from a Python float. */ |
| 32 | + _PyTime_ROUND_HALF_EVEN=2, |
| 33 | + /* Round away from zero |
| 34 | + For example, used for timeout. _PyTime_ROUND_CEILING rounds |
| 35 | + -1e-9 to 0 milliseconds which causes bpo-31786 issue. |
| 36 | + _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps |
| 37 | + the timeout sign as expected. select.poll(timeout) must block |
| 38 | + for negative values." */ |
| 39 | + _PyTime_ROUND_UP=3, |
| 40 | + /* _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be |
| 41 | + used for timeouts. */ |
| 42 | + _PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP |
| 43 | +} _PyTime_round_t; |
| 44 | + |
| 45 | + |
| 46 | +/* Convert a time_t to a PyLong. */ |
| 47 | +PyAPI_FUNC(PyObject *) _PyLong_FromTime_t( |
| 48 | + time_t sec); |
| 49 | + |
| 50 | +/* Convert a PyLong to a time_t. */ |
| 51 | +PyAPI_FUNC(time_t) _PyLong_AsTime_t( |
| 52 | + PyObject *obj); |
| 53 | + |
| 54 | +/* Convert a number of seconds, int or float, to time_t. */ |
| 55 | +PyAPI_FUNC(int) _PyTime_ObjectToTime_t( |
| 56 | + PyObject *obj, |
| 57 | + time_t *sec, |
| 58 | + _PyTime_round_t); |
| 59 | + |
| 60 | +/* Convert a number of seconds, int or float, to a timeval structure. |
| 61 | + usec is in the range [0; 999999] and rounded towards zero. |
| 62 | + For example, -1.2 is converted to (-2, 800000). */ |
| 63 | +PyAPI_FUNC(int) _PyTime_ObjectToTimeval( |
| 64 | + PyObject *obj, |
| 65 | + time_t *sec, |
| 66 | + long *usec, |
| 67 | + _PyTime_round_t); |
| 68 | + |
| 69 | +/* Convert a number of seconds, int or float, to a timespec structure. |
| 70 | + nsec is in the range [0; 999999999] and rounded towards zero. |
| 71 | + For example, -1.2 is converted to (-2, 800000000). */ |
| 72 | +PyAPI_FUNC(int) _PyTime_ObjectToTimespec( |
| 73 | + PyObject *obj, |
| 74 | + time_t *sec, |
| 75 | + long *nsec, |
| 76 | + _PyTime_round_t); |
| 77 | + |
| 78 | + |
| 79 | +/* Create a timestamp from a number of seconds. */ |
| 80 | +PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds); |
| 81 | + |
| 82 | +/* Macro to create a timestamp from a number of seconds, no integer overflow. |
| 83 | + Only use the macro for small values, prefer _PyTime_FromSeconds(). */ |
| 84 | +#define _PYTIME_FROMSECONDS(seconds) \ |
| 85 | + ((_PyTime_t)(seconds) * (1000 * 1000 * 1000)) |
| 86 | + |
| 87 | +/* Create a timestamp from a number of nanoseconds. */ |
| 88 | +PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(_PyTime_t ns); |
| 89 | + |
| 90 | +/* Create a timestamp from nanoseconds (Python int). */ |
| 91 | +PyAPI_FUNC(int) _PyTime_FromNanosecondsObject(_PyTime_t *t, |
| 92 | + PyObject *obj); |
| 93 | + |
| 94 | +/* Convert a number of seconds (Python float or int) to a timetamp. |
| 95 | + Raise an exception and return -1 on error, return 0 on success. */ |
| 96 | +PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t, |
| 97 | + PyObject *obj, |
| 98 | + _PyTime_round_t round); |
| 99 | + |
| 100 | +/* Convert a number of milliseconds (Python float or int, 10^-3) to a timetamp. |
| 101 | + Raise an exception and return -1 on error, return 0 on success. */ |
| 102 | +PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t, |
| 103 | + PyObject *obj, |
| 104 | + _PyTime_round_t round); |
| 105 | + |
| 106 | +/* Convert a timestamp to a number of seconds as a C double. */ |
| 107 | +PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t); |
| 108 | + |
| 109 | +/* Convert timestamp to a number of milliseconds (10^-3 seconds). */ |
| 110 | +PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t, |
| 111 | + _PyTime_round_t round); |
| 112 | + |
| 113 | +/* Convert timestamp to a number of microseconds (10^-6 seconds). */ |
| 114 | +PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t, |
| 115 | + _PyTime_round_t round); |
| 116 | + |
| 117 | +/* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int |
| 118 | + object. */ |
| 119 | +PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t); |
| 120 | + |
| 121 | +/* Create a timestamp from a timeval structure. |
| 122 | + Raise an exception and return -1 on overflow, return 0 on success. */ |
| 123 | +PyAPI_FUNC(int) _PyTime_FromTimeval(_PyTime_t *tp, struct timeval *tv); |
| 124 | + |
| 125 | +/* Convert a timestamp to a timeval structure (microsecond resolution). |
| 126 | + tv_usec is always positive. |
| 127 | + Raise an exception and return -1 if the conversion overflowed, |
| 128 | + return 0 on success. */ |
| 129 | +PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t, |
| 130 | + struct timeval *tv, |
| 131 | + _PyTime_round_t round); |
| 132 | + |
| 133 | +/* Similar to _PyTime_AsTimeval(), but don't raise an exception on error. */ |
| 134 | +PyAPI_FUNC(int) _PyTime_AsTimeval_noraise(_PyTime_t t, |
| 135 | + struct timeval *tv, |
| 136 | + _PyTime_round_t round); |
| 137 | + |
| 138 | +/* Convert a timestamp to a number of seconds (secs) and microseconds (us). |
| 139 | + us is always positive. This function is similar to _PyTime_AsTimeval() |
| 140 | + except that secs is always a time_t type, whereas the timeval structure |
| 141 | + uses a C long for tv_sec on Windows. |
| 142 | + Raise an exception and return -1 if the conversion overflowed, |
| 143 | + return 0 on success. */ |
| 144 | +PyAPI_FUNC(int) _PyTime_AsTimevalTime_t( |
| 145 | + _PyTime_t t, |
| 146 | + time_t *secs, |
| 147 | + int *us, |
| 148 | + _PyTime_round_t round); |
| 149 | + |
| 150 | +#if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE) |
| 151 | +/* Create a timestamp from a timespec structure. |
| 152 | + Raise an exception and return -1 on overflow, return 0 on success. */ |
| 153 | +PyAPI_FUNC(int) _PyTime_FromTimespec(_PyTime_t *tp, struct timespec *ts); |
| 154 | + |
| 155 | +/* Convert a timestamp to a timespec structure (nanosecond resolution). |
| 156 | + tv_nsec is always positive. |
| 157 | + Raise an exception and return -1 on error, return 0 on success. */ |
| 158 | +PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts); |
| 159 | +#endif |
| 160 | + |
| 161 | +/* Compute ticks * mul / div. |
| 162 | + The caller must ensure that ((div - 1) * mul) cannot overflow. */ |
| 163 | +PyAPI_FUNC(_PyTime_t) _PyTime_MulDiv(_PyTime_t ticks, |
| 164 | + _PyTime_t mul, |
| 165 | + _PyTime_t div); |
| 166 | + |
| 167 | +/* Get the current time from the system clock. |
| 168 | +
|
| 169 | + The function cannot fail. _PyTime_Init() ensures that the system clock |
| 170 | + works. */ |
| 171 | +PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void); |
| 172 | + |
| 173 | +/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
| 174 | + The clock is not affected by system clock updates. The reference point of |
| 175 | + the returned value is undefined, so that only the difference between the |
| 176 | + results of consecutive calls is valid. |
| 177 | +
|
| 178 | + The function cannot fail. _PyTime_Init() ensures that a monotonic clock |
| 179 | + is available and works. */ |
| 180 | +PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void); |
| 181 | + |
| 182 | + |
| 183 | +/* Structure used by time.get_clock_info() */ |
| 184 | +typedef struct { |
| 185 | + const char *implementation; |
| 186 | + int monotonic; |
| 187 | + int adjustable; |
| 188 | + double resolution; |
| 189 | +} _Py_clock_info_t; |
| 190 | + |
| 191 | +/* Get the current time from the system clock. |
| 192 | + * Fill clock information if info is not NULL. |
| 193 | + * Raise an exception and return -1 on error, return 0 on success. |
| 194 | + */ |
| 195 | +PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo( |
| 196 | + _PyTime_t *t, |
| 197 | + _Py_clock_info_t *info); |
| 198 | + |
| 199 | +/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
| 200 | + The clock is not affected by system clock updates. The reference point of |
| 201 | + the returned value is undefined, so that only the difference between the |
| 202 | + results of consecutive calls is valid. |
| 203 | +
|
| 204 | + Fill info (if set) with information of the function used to get the time. |
| 205 | +
|
| 206 | + Return 0 on success, raise an exception and return -1 on error. */ |
| 207 | +PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo( |
| 208 | + _PyTime_t *t, |
| 209 | + _Py_clock_info_t *info); |
| 210 | + |
| 211 | + |
| 212 | +/* Initialize time. |
| 213 | + Return 0 on success, raise an exception and return -1 on error. */ |
| 214 | +PyAPI_FUNC(int) _PyTime_Init(void); |
| 215 | + |
| 216 | +/* Converts a timestamp to the Gregorian time, using the local time zone. |
| 217 | + Return 0 on success, raise an exception and return -1 on error. */ |
| 218 | +PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm); |
| 219 | + |
| 220 | +/* Converts a timestamp to the Gregorian time, assuming UTC. |
| 221 | + Return 0 on success, raise an exception and return -1 on error. */ |
| 222 | +PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm); |
| 223 | + |
| 224 | +/* Get the performance counter: clock with the highest available resolution to |
| 225 | + measure a short duration. |
| 226 | +
|
| 227 | + The function cannot fail. _PyTime_Init() ensures that the system clock |
| 228 | + works. */ |
| 229 | +PyAPI_FUNC(_PyTime_t) _PyTime_GetPerfCounter(void); |
| 230 | + |
| 231 | +/* Get the performance counter: clock with the highest available resolution to |
| 232 | + measure a short duration. |
| 233 | +
|
| 234 | + Fill info (if set) with information of the function used to get the time. |
| 235 | +
|
| 236 | + Return 0 on success, raise an exception and return -1 on error. */ |
| 237 | +PyAPI_FUNC(int) _PyTime_GetPerfCounterWithInfo( |
| 238 | + _PyTime_t *t, |
| 239 | + _Py_clock_info_t *info); |
| 240 | + |
| 241 | +#ifdef __cplusplus |
| 242 | +} |
| 243 | +#endif |
| 244 | + |
| 245 | +#endif /* Py_PYTIME_H */ |
| 246 | +#endif /* Py_LIMITED_API */ |
0 commit comments