Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.14/internal/pycore_time.h
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
