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 | |
| 16 | #ifdef HAVE_GETTIMEOFDAY |
| 17 | typedef struct timeval _PyTime_timeval; |
| 18 | #else |
| 19 | typedef struct { |
| 20 | time_t tv_sec; /* seconds since Jan. 1, 1970 */ |
| 21 | long tv_usec; /* and microseconds */ |
| 22 | } _PyTime_timeval; |
| 23 | #endif |
| 24 | |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 25 | /* Structure used by time.get_clock_info() */ |
| 26 | typedef struct { |
| 27 | const char *implementation; |
Benjamin Peterson | 49a69e4 | 2012-05-01 09:38:34 -0400 | [diff] [blame] | 28 | int monotonic; |
Victor Stinner | 2b89fdf | 2012-06-12 22:46:37 +0200 | [diff] [blame] | 29 | int adjustable; |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 30 | double resolution; |
| 31 | } _Py_clock_info_t; |
| 32 | |
Alexander Belopolsky | 6fc4ade | 2010-08-05 17:34:27 +0000 | [diff] [blame] | 33 | /* Similar to POSIX gettimeofday but cannot fail. If system gettimeofday |
| 34 | * fails or is not available, fall back to lower resolution clocks. |
| 35 | */ |
| 36 | PyAPI_FUNC(void) _PyTime_gettimeofday(_PyTime_timeval *tp); |
| 37 | |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 38 | /* Similar to _PyTime_gettimeofday() but retrieve also information on the |
| 39 | * clock used to get the current time. */ |
Victor Stinner | 0011124 | 2014-08-29 16:31:59 +0200 | [diff] [blame] | 40 | PyAPI_FUNC(int) _PyTime_gettimeofday_info( |
Victor Stinner | ec89539 | 2012-04-29 02:41:27 +0200 | [diff] [blame] | 41 | _PyTime_timeval *tp, |
| 42 | _Py_clock_info_t *info); |
| 43 | |
Antoine Pitrou | 3e1fd27 | 2010-09-28 21:23:11 +0000 | [diff] [blame] | 44 | #define _PyTime_INTERVAL(tv_start, tv_end) \ |
| 45 | ((tv_end.tv_sec - tv_start.tv_sec) + \ |
| 46 | (tv_end.tv_usec - tv_start.tv_usec) * 0.000001) |
| 47 | |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 48 | typedef enum { |
| 49 | /* Round towards zero. */ |
| 50 | _PyTime_ROUND_DOWN=0, |
| 51 | /* Round away from zero. */ |
| 52 | _PyTime_ROUND_UP |
| 53 | } _PyTime_round_t; |
| 54 | |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 55 | /* Convert a number of seconds, int or float, to time_t. */ |
| 56 | PyAPI_FUNC(int) _PyTime_ObjectToTime_t( |
| 57 | PyObject *obj, |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 58 | time_t *sec, |
| 59 | _PyTime_round_t); |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 60 | |
Larry Hastings | 6fe20b3 | 2012-04-19 15:07:49 -0700 | [diff] [blame] | 61 | /* Convert a time_t to a PyLong. */ |
| 62 | PyAPI_FUNC(PyObject *) _PyLong_FromTime_t( |
| 63 | time_t sec); |
| 64 | |
Larry Hastings | 76ad59b | 2012-05-03 00:30:07 -0700 | [diff] [blame] | 65 | /* Convert a PyLong to a time_t. */ |
| 66 | PyAPI_FUNC(time_t) _PyLong_AsTime_t( |
| 67 | PyObject *obj); |
| 68 | |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 69 | /* Convert a number of seconds, int or float, to a timeval structure. |
| 70 | usec is in the range [0; 999999] and rounded towards zero. |
| 71 | For example, -1.2 is converted to (-2, 800000). */ |
| 72 | PyAPI_FUNC(int) _PyTime_ObjectToTimeval( |
| 73 | PyObject *obj, |
| 74 | time_t *sec, |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 75 | long *usec, |
| 76 | _PyTime_round_t); |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 77 | |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 78 | /* Convert a number of seconds, int or float, to a timespec structure. |
Victor Stinner | 5d272cc | 2012-03-13 13:35:55 +0100 | [diff] [blame] | 79 | nsec is in the range [0; 999999999] and rounded towards zero. |
| 80 | For example, -1.2 is converted to (-2, 800000000). */ |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 81 | PyAPI_FUNC(int) _PyTime_ObjectToTimespec( |
| 82 | PyObject *obj, |
| 83 | time_t *sec, |
Victor Stinner | 3c1b379 | 2014-02-17 00:02:43 +0100 | [diff] [blame] | 84 | long *nsec, |
| 85 | _PyTime_round_t); |
Victor Stinner | 643cd68 | 2012-03-02 22:54:03 +0100 | [diff] [blame] | 86 | |
Victor Stinner | ae58649 | 2014-09-02 23:18:25 +0200 | [diff] [blame] | 87 | /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
| 88 | The clock is not affected by system clock updates. The reference point of |
| 89 | the returned value is undefined, so that only the difference between the |
| 90 | results of consecutive calls is valid. |
| 91 | |
| 92 | The function never fails. _PyTime_Init() ensures that a monotonic clock |
| 93 | is available and works. */ |
| 94 | PyAPI_FUNC(void) _PyTime_monotonic( |
| 95 | _PyTime_timeval *tp); |
| 96 | |
| 97 | /* Similar to _PyTime_monotonic(), fill also info (if set) with information of |
| 98 | the function used to get the time. |
| 99 | |
| 100 | Return 0 on success, raise an exception and return -1 on error. */ |
| 101 | PyAPI_FUNC(int) _PyTime_monotonic_info( |
| 102 | _PyTime_timeval *tp, |
| 103 | _Py_clock_info_t *info); |
| 104 | |
Victor Stinner | 9a8089b | 2015-03-20 01:42:20 +0100 | [diff] [blame] | 105 | /* Add interval seconds to tv */ |
| 106 | PyAPI_FUNC(void) |
| 107 | _PyTime_AddDouble(_PyTime_timeval *tv, double interval, |
| 108 | _PyTime_round_t round); |
| 109 | |
Victor Stinner | 0011124 | 2014-08-29 16:31:59 +0200 | [diff] [blame] | 110 | /* Initialize time. |
| 111 | Return 0 on success, raise an exception and return -1 on error. */ |
| 112 | PyAPI_FUNC(int) _PyTime_Init(void); |
Alexander Belopolsky | 6fc4ade | 2010-08-05 17:34:27 +0000 | [diff] [blame] | 113 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 114 | /****************** NEW _PyTime_t API **********************/ |
| 115 | |
| 116 | #ifdef PY_INT64_T |
| 117 | typedef PY_INT64_T _PyTime_t; |
| 118 | #else |
| 119 | # error "_PyTime_t need signed 64-bit integer type" |
| 120 | #endif |
| 121 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 122 | /* Create a timestamp from a number of nanoseconds (C long). */ |
| 123 | PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(PY_LONG_LONG ns); |
| 124 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 125 | /* Convert a Python float or int to a timetamp. |
| 126 | Raise an exception and return -1 on error, return 0 on success. */ |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 127 | PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t, |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 128 | PyObject *obj, |
| 129 | _PyTime_round_t round); |
| 130 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 131 | /* Convert a timestamp to a number of seconds as a C double. */ |
| 132 | PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t); |
| 133 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 134 | /* Convert timestamp to a number of milliseconds (10^-3 seconds). */ |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 135 | PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t, |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 136 | _PyTime_round_t round); |
| 137 | |
Victor Stinner | 992c43f | 2015-03-27 17:12:45 +0100 | [diff] [blame] | 138 | /* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int |
| 139 | object. */ |
| 140 | PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t); |
| 141 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 142 | /* Convert a timestamp to a timeval structure (microsecond resolution). |
| 143 | Raise an exception and return -1 on error, return 0 on success. */ |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 144 | PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t, |
| 145 | struct timeval *tv, |
| 146 | _PyTime_round_t round); |
| 147 | |
Victor Stinner | a47b881 | 2015-03-27 18:16:17 +0100 | [diff] [blame^] | 148 | /* Get the current time from the system clock. |
| 149 | * Fill clock information if info is not NULL. |
| 150 | * Raise an exception and return -1 on error, return 0 on success. |
| 151 | */ |
| 152 | PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo( |
| 153 | _PyTime_t *t, |
| 154 | _Py_clock_info_t *info); |
| 155 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 156 | /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
| 157 | The clock is not affected by system clock updates. The reference point of |
| 158 | the returned value is undefined, so that only the difference between the |
| 159 | results of consecutive calls is valid. |
| 160 | |
| 161 | The function cannot fail. _PyTime_Init() ensures that a monotonic clock |
| 162 | is available and works. */ |
| 163 | PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void); |
| 164 | |
Victor Stinner | 4bfb460 | 2015-03-27 22:27:24 +0100 | [diff] [blame] | 165 | /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
| 166 | The clock is not affected by system clock updates. The reference point of |
| 167 | the returned value is undefined, so that only the difference between the |
| 168 | results of consecutive calls is valid. |
| 169 | |
| 170 | Fill info (if set) with information of the function used to get the time. |
| 171 | |
| 172 | Return 0 on success, raise an exception and return -1 on error. */ |
| 173 | PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo( |
| 174 | _PyTime_t *t, |
| 175 | _Py_clock_info_t *info); |
| 176 | |
Victor Stinner | cb29f01 | 2015-03-27 13:31:18 +0100 | [diff] [blame] | 177 | |
Alexander Belopolsky | 6fc4ade | 2010-08-05 17:34:27 +0000 | [diff] [blame] | 178 | #ifdef __cplusplus |
| 179 | } |
| 180 | #endif |
| 181 | |
| 182 | #endif /* Py_PYTIME_H */ |
Martin v. Löwis | 4d0d471 | 2010-12-03 20:14:31 +0000 | [diff] [blame] | 183 | #endif /* Py_LIMITED_API */ |