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 | #ifdef PY_INT64_T |
| 17 | /* _PyTime_t: Python timestamp with subsecond precision. It can be used to |
| 18 | store a duration, and so indirectly a date (related to another date, like |
| 19 | UNIX epoch). */ |
| 20 | typedef PY_INT64_T _PyTime_t; |
| 21 | #define _PyTime_MIN PY_LLONG_MIN |
| 22 | #define _PyTime_MAX PY_LLONG_MAX |
| 23 | #else |
| 24 | # error "_PyTime_t need signed 64-bit integer type" |
| 25 | #endif |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 26 | |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 27 | typedef enum { |
Victor Stinner | 02937aa | 2015-03-28 05:02:39 +0100 | [diff] [blame] | 28 | /* Round towards minus infinity (-inf). |
| 29 | For example, used to read a clock. */ |
Victor Stinner | a695f83 | 2015-03-30 03:57:14 +0200 | [diff] [blame] | 30 | _PyTime_ROUND_FLOOR=0, |
Victor Stinner | bcdd777 | 2015-03-30 03:52:49 +0200 | [diff] [blame] | 31 | /* Round towards infinity (+inf). |
| 32 | For example, used for timeout to wait "at least" N seconds. */ |
Victor Stinner | 7447423 | 2015-09-02 01:43:56 +0200 | [diff] [blame] | 33 | _PyTime_ROUND_CEILING=1, |
Victor Stinner | 7667f58 | 2015-09-09 01:02:23 +0200 | [diff] [blame] | 34 | /* Round to nearest with ties going to nearest even integer. |
Victor Stinner | 7447423 | 2015-09-02 01:43:56 +0200 | [diff] [blame] | 35 | For example, used to round from a Python float. */ |
Victor Stinner | 7667f58 | 2015-09-09 01:02:23 +0200 | [diff] [blame] | 36 | _PyTime_ROUND_HALF_EVEN |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 37 | } _PyTime_round_t; |
| 38 | |
Larry Hastings | 6fe20b3 | 2012-04-19 15:07:49 -0700 | [diff] [blame] | 39 | /* Convert a time_t to a PyLong. */ |
| 40 | PyAPI_FUNC(PyObject *) _PyLong_FromTime_t( |
| 41 | time_t sec); |
| 42 | |
Larry Hastings | 76ad59b | 2012-05-03 00:30:07 -0700 | [diff] [blame] | 43 | /* Convert a PyLong to a time_t. */ |
| 44 | PyAPI_FUNC(time_t) _PyLong_AsTime_t( |
| 45 | PyObject *obj); |
| 46 | |
Victor Stinner | 1bd18ba | 2015-03-30 00:25:38 +0200 | [diff] [blame] | 47 | /* Convert a number of seconds, int or float, to time_t. */ |
| 48 | PyAPI_FUNC(int) _PyTime_ObjectToTime_t( |
| 49 | PyObject *obj, |
| 50 | time_t *sec, |
| 51 | _PyTime_round_t); |
| 52 | |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 53 | /* Convert a number of seconds, int or float, to a timeval structure. |
| 54 | usec is in the range [0; 999999] and rounded towards zero. |
| 55 | For example, -1.2 is converted to (-2, 800000). */ |
| 56 | PyAPI_FUNC(int) _PyTime_ObjectToTimeval( |
| 57 | PyObject *obj, |
| 58 | time_t *sec, |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 59 | long *usec, |
| 60 | _PyTime_round_t); |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 61 | |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 62 | /* Convert a number of seconds, int or float, to a timespec structure. |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 63 | nsec is in the range [0; 999999999] and rounded towards zero. |
| 64 | For example, -1.2 is converted to (-2, 800000000). */ |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 65 | PyAPI_FUNC(int) _PyTime_ObjectToTimespec( |
| 66 | PyObject *obj, |
| 67 | time_t *sec, |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 68 | long *nsec, |
| 69 | _PyTime_round_t); |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 70 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 71 | |
Victor Stinner | 13019fd | 2015-04-03 13:10:54 +0200 | [diff] [blame] | 72 | /* Create a timestamp from a number of seconds. */ |
Victor Stinner | 88ed640 | 2015-04-09 10:23:12 +0200 | [diff] [blame] | 73 | PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds); |
| 74 | |
| 75 | /* Macro to create a timestamp from a number of seconds, no integer overflow. |
| 76 | Only use the macro for small values, prefer _PyTime_FromSeconds(). */ |
| 77 | #define _PYTIME_FROMSECONDS(seconds) \ |
| 78 | ((_PyTime_t)(seconds) * (1000 * 1000 * 1000)) |
Victor Stinner | 13019fd | 2015-04-03 13:10:54 +0200 | [diff] [blame] | 79 | |
| 80 | /* Create a timestamp from a number of nanoseconds. */ |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 81 | PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(PY_LONG_LONG ns); |
| 82 | |
Victor Stinner | fa09beb | 2015-03-30 21:36:10 +0200 | [diff] [blame] | 83 | /* Convert a number of seconds (Python float or int) to a timetamp. |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 84 | Raise an exception and return -1 on error, return 0 on success. */ |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 85 | PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t, |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 86 | PyObject *obj, |
| 87 | _PyTime_round_t round); |
| 88 | |
Victor Stinner | fa09beb | 2015-03-30 21:36:10 +0200 | [diff] [blame] | 89 | /* Convert a number of milliseconds (Python float or int, 10^-3) to a timetamp. |
| 90 | Raise an exception and return -1 on error, return 0 on success. */ |
| 91 | PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t, |
| 92 | PyObject *obj, |
| 93 | _PyTime_round_t round); |
| 94 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 95 | /* Convert a timestamp to a number of seconds as a C double. */ |
| 96 | PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t); |
| 97 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 98 | /* Convert timestamp to a number of milliseconds (10^-3 seconds). */ |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 99 | PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t, |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 100 | _PyTime_round_t round); |
| 101 | |
Victor Stinner | f5faad2 | 2015-03-28 03:52:05 +0100 | [diff] [blame] | 102 | /* Convert timestamp to a number of microseconds (10^-6 seconds). */ |
| 103 | PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t, |
| 104 | _PyTime_round_t round); |
| 105 | |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 106 | /* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int |
| 107 | object. */ |
| 108 | PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t); |
| 109 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 110 | /* Convert a timestamp to a timeval structure (microsecond resolution). |
Victor Stinner | 95e9cef | 2015-03-28 01:26:47 +0100 | [diff] [blame] | 111 | tv_usec is always positive. |
Victor Stinner | ea9c0dd | 2015-03-30 02:51:13 +0200 | [diff] [blame] | 112 | Raise an exception and return -1 if the conversion overflowed, |
| 113 | return 0 on success. */ |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 114 | PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t, |
| 115 | struct timeval *tv, |
| 116 | _PyTime_round_t round); |
| 117 | |
Victor Stinner | ea9c0dd | 2015-03-30 02:51:13 +0200 | [diff] [blame] | 118 | /* Similar to _PyTime_AsTimeval(), but don't raise an exception on error. */ |
| 119 | PyAPI_FUNC(int) _PyTime_AsTimeval_noraise(_PyTime_t t, |
| 120 | struct timeval *tv, |
| 121 | _PyTime_round_t round); |
| 122 | |
Victor Stinner | 1e2b688 | 2015-09-18 13:23:02 +0200 | [diff] [blame] | 123 | /* Convert a timestamp to a number of seconds (secs) and microseconds (us). |
| 124 | us is always positive. This function is similar to _PyTime_AsTimeval() |
| 125 | except that secs is always a time_t type, whereas the timeval structure |
| 126 | uses a C long for tv_sec on Windows. |
| 127 | Raise an exception and return -1 if the conversion overflowed, |
| 128 | return 0 on success. */ |
| 129 | PyAPI_FUNC(int) _PyTime_AsTimevalTime_t( |
| 130 | _PyTime_t t, |
| 131 | time_t *secs, |
| 132 | int *us, |
| 133 | _PyTime_round_t round); |
| 134 | |
Victor Stinner | c337838 | 2015-03-28 05:07:51 +0100 | [diff] [blame] | 135 | #if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE) |
Victor Stinner | 34dc0f4 | 2015-03-27 18:19:03 +0100 | [diff] [blame] | 136 | /* Convert a timestamp to a timespec structure (nanosecond resolution). |
Victor Stinner | 95e9cef | 2015-03-28 01:26:47 +0100 | [diff] [blame] | 137 | tv_nsec is always positive. |
Victor Stinner | 34dc0f4 | 2015-03-27 18:19:03 +0100 | [diff] [blame] | 138 | Raise an exception and return -1 on error, return 0 on success. */ |
| 139 | PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts); |
| 140 | #endif |
| 141 | |
Victor Stinner | a47b881 | 2015-03-27 18:16:17 +0100 | [diff] [blame] | 142 | /* Get the current time from the system clock. |
Victor Stinner | 09e5cf2 | 2015-03-30 00:09:18 +0200 | [diff] [blame] | 143 | |
| 144 | The function cannot fail. _PyTime_Init() ensures that the system clock |
| 145 | works. */ |
| 146 | PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void); |
| 147 | |
Victor Stinner | 1bd18ba | 2015-03-30 00:25:38 +0200 | [diff] [blame] | 148 | /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
| 149 | The clock is not affected by system clock updates. The reference point of |
| 150 | the returned value is undefined, so that only the difference between the |
| 151 | results of consecutive calls is valid. |
| 152 | |
| 153 | The function cannot fail. _PyTime_Init() ensures that a monotonic clock |
| 154 | is available and works. */ |
| 155 | PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void); |
| 156 | |
| 157 | |
| 158 | /* Structure used by time.get_clock_info() */ |
| 159 | typedef struct { |
| 160 | const char *implementation; |
| 161 | int monotonic; |
| 162 | int adjustable; |
| 163 | double resolution; |
| 164 | } _Py_clock_info_t; |
| 165 | |
Victor Stinner | 09e5cf2 | 2015-03-30 00:09:18 +0200 | [diff] [blame] | 166 | /* Get the current time from the system clock. |
Victor Stinner | a47b881 | 2015-03-27 18:16:17 +0100 | [diff] [blame] | 167 | * Fill clock information if info is not NULL. |
| 168 | * Raise an exception and return -1 on error, return 0 on success. |
| 169 | */ |
| 170 | PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo( |
| 171 | _PyTime_t *t, |
| 172 | _Py_clock_info_t *info); |
| 173 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 174 | /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
| 175 | The clock is not affected by system clock updates. The reference point of |
| 176 | the returned value is undefined, so that only the difference between the |
| 177 | results of consecutive calls is valid. |
| 178 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 179 | Fill info (if set) with information of the function used to get the time. |
| 180 | |
| 181 | Return 0 on success, raise an exception and return -1 on error. */ |
| 182 | PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo( |
| 183 | _PyTime_t *t, |
| 184 | _Py_clock_info_t *info); |
| 185 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 186 | |
Victor Stinner | 1bd18ba | 2015-03-30 00:25:38 +0200 | [diff] [blame] | 187 | /* Initialize time. |
| 188 | Return 0 on success, raise an exception and return -1 on error. */ |
| 189 | PyAPI_FUNC(int) _PyTime_Init(void); |
| 190 | |
Alexander Belopolsky | 6fc4ade | 2010-08-05 17:34:27 +0000 | [diff] [blame] | 191 | #ifdef __cplusplus |
| 192 | } |
| 193 | #endif |
| 194 | |
| 195 | #endif /* Py_PYTIME_H */ |
Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 196 | #endif /* Py_LIMITED_API */ |