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