Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 1 | #ifndef Py_LIMITED_API |
Alexander Belopolsky | 6fc4ade | 2010-08-05 17:34:27 +0000 | [diff] [blame] | 2 | #ifndef Py_PYTIME_H |
| 3 | #define Py_PYTIME_H |
| 4 | |
Victor Stinner | 4195b5c | 2012-02-08 23:03:19 +0100 | [diff] [blame] | 5 | #include "pyconfig.h" /* include for defines */ |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 6 | #include "object.h" |
Alexander Belopolsky | 6fc4ade | 2010-08-05 17:34:27 +0000 | [diff] [blame] | 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 | |
Victor Stinner | 1bd18ba | 2015-03-30 00:25:38 +0200 | [diff] [blame] | 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). */ |
Benjamin Peterson | 9b3d770 | 2016-09-06 13:24:00 -0700 | [diff] [blame] | 19 | typedef int64_t _PyTime_t; |
Victor Stinner | 944aa01 | 2019-08-23 17:17:52 +0100 | [diff] [blame] | 20 | #define _PyTime_MIN INT64_MIN |
| 21 | #define _PyTime_MAX INT64_MAX |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 22 | |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 23 | typedef enum { |
Victor Stinner | 02937aa | 2015-03-28 05:02:39 +0100 | [diff] [blame] | 24 | /* Round towards minus infinity (-inf). |
| 25 | For example, used to read a clock. */ |
Victor Stinner | a695f83 | 2015-03-30 03:57:14 +0200 | [diff] [blame] | 26 | _PyTime_ROUND_FLOOR=0, |
Victor Stinner | bcdd777 | 2015-03-30 03:52:49 +0200 | [diff] [blame] | 27 | /* Round towards infinity (+inf). |
| 28 | For example, used for timeout to wait "at least" N seconds. */ |
Victor Stinner | 7447423 | 2015-09-02 01:43:56 +0200 | [diff] [blame] | 29 | _PyTime_ROUND_CEILING=1, |
Victor Stinner | 7667f58 | 2015-09-09 01:02:23 +0200 | [diff] [blame] | 30 | /* Round to nearest with ties going to nearest even integer. |
Victor Stinner | 7447423 | 2015-09-02 01:43:56 +0200 | [diff] [blame] | 31 | For example, used to round from a Python float. */ |
Pablo Galindo | 2c15b29 | 2017-10-17 15:14:41 +0100 | [diff] [blame] | 32 | _PyTime_ROUND_HALF_EVEN=2, |
Serhiy Storchaka | bdf4298 | 2017-10-26 16:59:40 +0300 | [diff] [blame] | 33 | /* Round away from zero |
Pablo Galindo | 2c15b29 | 2017-10-17 15:14:41 +0100 | [diff] [blame] | 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, |
Serhiy Storchaka | bdf4298 | 2017-10-26 16:59:40 +0300 | [diff] [blame] | 40 | /* _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be |
Pablo Galindo | 2c15b29 | 2017-10-17 15:14:41 +0100 | [diff] [blame] | 41 | used for timeouts. */ |
| 42 | _PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 43 | } _PyTime_round_t; |
| 44 | |
Pablo Galindo | 2c15b29 | 2017-10-17 15:14:41 +0100 | [diff] [blame] | 45 | |
Larry Hastings | 6fe20b3 | 2012-04-19 15:07:49 -0700 | [diff] [blame] | 46 | /* Convert a time_t to a PyLong. */ |
| 47 | PyAPI_FUNC(PyObject *) _PyLong_FromTime_t( |
| 48 | time_t sec); |
| 49 | |
Larry Hastings | 76ad59b | 2012-05-03 00:30:07 -0700 | [diff] [blame] | 50 | /* Convert a PyLong to a time_t. */ |
| 51 | PyAPI_FUNC(time_t) _PyLong_AsTime_t( |
| 52 | PyObject *obj); |
| 53 | |
Victor Stinner | 1bd18ba | 2015-03-30 00:25:38 +0200 | [diff] [blame] | 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 | |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 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, |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 66 | long *usec, |
| 67 | _PyTime_round_t); |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 68 | |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 69 | /* Convert a number of seconds, int or float, to a timespec structure. |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 70 | nsec is in the range [0; 999999999] and rounded towards zero. |
| 71 | For example, -1.2 is converted to (-2, 800000000). */ |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 72 | PyAPI_FUNC(int) _PyTime_ObjectToTimespec( |
| 73 | PyObject *obj, |
| 74 | time_t *sec, |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 75 | long *nsec, |
| 76 | _PyTime_round_t); |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 77 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 78 | |
Victor Stinner | 13019fd | 2015-04-03 13:10:54 +0200 | [diff] [blame] | 79 | /* Create a timestamp from a number of seconds. */ |
Victor Stinner | 88ed640 | 2015-04-09 10:23:12 +0200 | [diff] [blame] | 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)) |
Victor Stinner | 13019fd | 2015-04-03 13:10:54 +0200 | [diff] [blame] | 86 | |
| 87 | /* Create a timestamp from a number of nanoseconds. */ |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 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); |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 93 | |
Victor Stinner | fa09beb | 2015-03-30 21:36:10 +0200 | [diff] [blame] | 94 | /* Convert a number of seconds (Python float or int) to a timetamp. |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 95 | Raise an exception and return -1 on error, return 0 on success. */ |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 96 | PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t, |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 97 | PyObject *obj, |
| 98 | _PyTime_round_t round); |
| 99 | |
Victor Stinner | fa09beb | 2015-03-30 21:36:10 +0200 | [diff] [blame] | 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 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 106 | /* Convert a timestamp to a number of seconds as a C double. */ |
| 107 | PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t); |
| 108 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 109 | /* Convert timestamp to a number of milliseconds (10^-3 seconds). */ |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 110 | PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t, |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 111 | _PyTime_round_t round); |
| 112 | |
Victor Stinner | f5faad2 | 2015-03-28 03:52:05 +0100 | [diff] [blame] | 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 | |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 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 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 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 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 125 | /* Convert a timestamp to a timeval structure (microsecond resolution). |
Victor Stinner | 95e9cef | 2015-03-28 01:26:47 +0100 | [diff] [blame] | 126 | tv_usec is always positive. |
Victor Stinner | ea9c0dd | 2015-03-30 02:51:13 +0200 | [diff] [blame] | 127 | Raise an exception and return -1 if the conversion overflowed, |
| 128 | return 0 on success. */ |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 129 | PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t, |
| 130 | struct timeval *tv, |
| 131 | _PyTime_round_t round); |
| 132 | |
Victor Stinner | ea9c0dd | 2015-03-30 02:51:13 +0200 | [diff] [blame] | 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 | |
Victor Stinner | 1e2b688 | 2015-09-18 13:23:02 +0200 | [diff] [blame] | 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 | |
Victor Stinner | c337838 | 2015-03-28 05:07:51 +0100 | [diff] [blame] | 150 | #if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE) |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 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 | |
Victor Stinner | 34dc0f4 | 2015-03-27 18:19:03 +0100 | [diff] [blame] | 155 | /* Convert a timestamp to a timespec structure (nanosecond resolution). |
Victor Stinner | 95e9cef | 2015-03-28 01:26:47 +0100 | [diff] [blame] | 156 | tv_nsec is always positive. |
Victor Stinner | 34dc0f4 | 2015-03-27 18:19:03 +0100 | [diff] [blame] | 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 | |
Victor Stinner | c29b585 | 2017-11-02 07:28:27 -0700 | [diff] [blame] | 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 | |
Victor Stinner | a47b881 | 2015-03-27 18:16:17 +0100 | [diff] [blame] | 167 | /* Get the current time from the system clock. |
Victor Stinner | 09e5cf2 | 2015-03-30 00:09:18 +0200 | [diff] [blame] | 168 | |
| 169 | The function cannot fail. _PyTime_Init() ensures that the system clock |
| 170 | works. */ |
| 171 | PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void); |
| 172 | |
Victor Stinner | 1bd18ba | 2015-03-30 00:25:38 +0200 | [diff] [blame] | 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 | |
Victor Stinner | 09e5cf2 | 2015-03-30 00:09:18 +0200 | [diff] [blame] | 191 | /* Get the current time from the system clock. |
Victor Stinner | a47b881 | 2015-03-27 18:16:17 +0100 | [diff] [blame] | 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 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 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 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 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 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 211 | |
Victor Stinner | 1bd18ba | 2015-03-30 00:25:38 +0200 | [diff] [blame] | 212 | /* Initialize time. |
| 213 | Return 0 on success, raise an exception and return -1 on error. */ |
| 214 | PyAPI_FUNC(int) _PyTime_Init(void); |
| 215 | |
Alexander Belopolsky | 3e7a3cb | 2016-09-28 17:31:35 -0400 | [diff] [blame] | 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 | |
Victor Stinner | cba9a0c | 2017-10-12 08:51:56 -0700 | [diff] [blame] | 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. */ |
Victor Stinner | bdaeb7d | 2017-10-16 08:44:31 -0700 | [diff] [blame] | 229 | PyAPI_FUNC(_PyTime_t) _PyTime_GetPerfCounter(void); |
Victor Stinner | a997c7b | 2017-10-10 02:51:50 -0700 | [diff] [blame] | 230 | |
| 231 | /* Get the performance counter: clock with the highest available resolution to |
Victor Stinner | cba9a0c | 2017-10-12 08:51:56 -0700 | [diff] [blame] | 232 | measure a short duration. |
Victor Stinner | a997c7b | 2017-10-10 02:51:50 -0700 | [diff] [blame] | 233 | |
Victor Stinner | cba9a0c | 2017-10-12 08:51:56 -0700 | [diff] [blame] | 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. */ |
Victor Stinner | bdaeb7d | 2017-10-16 08:44:31 -0700 | [diff] [blame] | 237 | PyAPI_FUNC(int) _PyTime_GetPerfCounterWithInfo( |
| 238 | _PyTime_t *t, |
Victor Stinner | a997c7b | 2017-10-10 02:51:50 -0700 | [diff] [blame] | 239 | _Py_clock_info_t *info); |
| 240 | |
Alexander Belopolsky | 6fc4ade | 2010-08-05 17:34:27 +0000 | [diff] [blame] | 241 | #ifdef __cplusplus |
| 242 | } |
| 243 | #endif |
| 244 | |
| 245 | #endif /* Py_PYTIME_H */ |
Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 246 | #endif /* Py_LIMITED_API */ |