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 PY_LLONG_MIN 21 #define _PyTime_MAX PY_LLONG_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 */ 247