| 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 arithmetic |
| 4 |
// 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 code |
| 20 |
// might still allude to that. |
| 21 |
// |
| 22 |
// Integer overflows are detected and raise OverflowError. Conversion to a |
| 23 |
// resolution larger than 1 nanosecond is rounded correctly with the requested |
| 24 |
// 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 "at |
| 28 |
// least" N seconds. |
| 29 |
// * Round to nearest with ties going to nearest even integer. For example, used |
| 30 |
// 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]. The |
| 34 |
// caller doesn't have to handle errors and so doesn't need to hold the GIL to |
| 35 |
// handle exceptions. For example, _PyTime_Add(t1, t2) computes t1+t2 and |
| 36 |
// clamps the result on overflow. |
| 37 |
// |
| 38 |
// Clocks: |
| 39 |
// |
| 40 |
// * System clock |
| 41 |
// * Monotonic clock |
| 42 |
// * Performance counter |
| 43 |
// |
| 44 |
// Internally, operations like (t * k / q) with integers are implemented in a |
| 45 |
// way to reduce the risk of integer overflow. Such operation is used to convert a |
| 46 |
// clock value expressed in ticks with a frequency to PyTime_t, like |
| 47 |
// QueryPerformanceCounter() with QueryPerformanceFrequency() on Windows. |
| 48 |
|
| 49 |
|
| 50 |
#ifndef Py_INTERNAL_TIME_H |
| 51 |
#define Py_INTERNAL_TIME_H |
| 52 |
#ifdef __cplusplus |
| 53 |
extern "C" { |
| 54 |
#endif |
| 55 |
|
| 56 |
#ifndef Py_BUILD_CORE |
| 57 |
# error "this header requires Py_BUILD_CORE define" |
| 58 |
#endif |
| 59 |
|
| 60 |
#include "pycore_runtime_structs.h" // _PyTimeFraction |
| 61 |
|
| 62 |
#ifdef __clang__ |
| 63 |
struct timeval; |
| 64 |
#endif |
| 65 |
|
| 66 |
#define _SIZEOF_PYTIME_T 8 |
| 67 |
|
| 68 |
typedef 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 zero |
| 82 |
// For example, used for timeout. _PyTime_ROUND_CEILING rounds |
| 83 |
// -1e-9 to 0 milliseconds which causes bpo-31786 issue. |
| 84 |
// _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps |
| 85 |
// the timeout sign as expected. select.poll(timeout) must block |
| 86 |
// for negative values. |
| 87 |
_PyTime_ROUND_UP=3, |
| 88 |
|
| 89 |
// _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be |
| 90 |
// used for timeouts. |
| 91 |
_PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP |
| 92 |
} _PyTime_round_t; |
| 93 |
|
| 94 |
|
| 95 |
// Convert a time_t to a PyLong. |
| 96 |
// Export for '_testinternalcapi' shared extension |
| 97 |
PyAPI_FUNC(PyObject*) _PyLong_FromTime_t(time_t sec); |
| 98 |
|
| 99 |
// Convert a PyLong to a time_t. |
| 100 |
// Export for '_datetime' shared extension |
| 101 |
PyAPI_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. |
| 105 |
PyAPI_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. |
| 114 |
PyAPI_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. |
| 124 |
PyAPI_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. |
| 133 |
PyAPI_FUNC(PyTime_t) _PyTime_FromSeconds(int seconds); |
| 134 |
|
| 135 |
// Create a timestamp from a number of seconds in double. |
| 136 |
extern 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. |
| 148 |
extern 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. |
| 152 |
PyAPI_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. |
| 158 |
PyAPI_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. |
| 165 |
PyAPI_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. |
| 171 |
PyAPI_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. |
| 176 |
PyAPI_FUNC(PyTime_t) _PyTime_AsMicroseconds(PyTime_t t, |
| 177 |
_PyTime_round_t round); |
| 178 |
|
| 179 |
#ifdef MS_WINDOWS |
| 180 |
// Convert timestamp to a number of 100 nanoseconds (10^-7 seconds). |
| 181 |
extern PyTime_t _PyTime_As100Nanoseconds(PyTime_t t, |
| 182 |
_PyTime_round_t round); |
| 183 |
#endif |
| 184 |
|
| 185 |
// Convert a timestamp (number of nanoseconds) as a Python int object. |
| 186 |
// Export for '_testinternalcapi' shared extension. |
| 187 |
PyAPI_FUNC(PyObject*) _PyTime_AsLong(PyTime_t t); |
| 188 |
|
| 189 |
#ifndef MS_WINDOWS |
| 190 |
// Create a timestamp from a timeval structure. |
| 191 |
// Raise an exception and return -1 on overflow, return 0 on success. |
| 192 |
extern int _PyTime_FromTimeval(PyTime_t *tp, struct timeval *tv); |
| 193 |
#endif |
| 194 |
|
| 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. |
| 200 |
PyAPI_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. |
| 207 |
PyAPI_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 structure |
| 214 |
// 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. |
| 218 |
PyAPI_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. |
| 227 |
extern 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. |
| 233 |
PyAPI_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. |
| 238 |
PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(PyTime_t t, struct timespec *ts); |
| 239 |
#endif |
| 240 |
|
| 241 |
|
| 242 |
// Compute t1 + t2. Clamp to [PyTime_MIN; PyTime_MAX] on overflow. |
| 243 |
extern PyTime_t _PyTime_Add(PyTime_t t1, PyTime_t t2); |
| 244 |
|
| 245 |
// Structure used by time.get_clock_info() |
| 246 |
typedef 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. |
| 256 |
extern 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 of |
| 262 |
// the returned value is undefined, so that only the difference between the |
| 263 |
// 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. |
| 269 |
PyAPI_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. |
| 277 |
PyAPI_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. |
| 282 |
PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm); |
| 283 |
|
| 284 |
|
| 285 |
// Get the performance counter: clock with the highest available resolution to |
| 286 |
// 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. |
| 291 |
extern 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() + timeout |
| 300 |
// Export for '_ssl' shared extension. |
| 301 |
PyAPI_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. |
| 306 |
PyAPI_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. |
| 314 |
extern 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. |
| 321 |
extern PyTime_t _PyTimeFraction_Mul( |
| 322 |
PyTime_t ticks, |
| 323 |
const _PyTimeFraction *frac); |
| 324 |
|
| 325 |
// Compute a clock resolution: frac.numer / frac.denom / 1e9. |
| 326 |
extern double _PyTimeFraction_Resolution( |
| 327 |
const _PyTimeFraction *frac); |
| 328 |
|
| 329 |
extern PyStatus _PyTime_Init(struct _Py_time_runtime_state *state); |
| 330 |
|
| 331 |
#ifdef __cplusplus |
| 332 |
} |
| 333 |
#endif |
| 334 |
#endif // !Py_INTERNAL_TIME_H |