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 | #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 |
26 | |
27 | typedef enum { |
28 | /* Round towards minus infinity (-inf). |
29 | For example, used to read a clock. */ |
30 | _PyTime_ROUND_FLOOR=0, |
31 | /* Round towards infinity (+inf). |
32 | For example, used for timeout to wait "at least" N seconds. */ |
33 | _PyTime_ROUND_CEILING |
34 | } _PyTime_round_t; |
35 | |
36 | /* Convert a time_t to a PyLong. */ |
37 | PyAPI_FUNC(PyObject *) _PyLong_FromTime_t( |
38 | time_t sec); |
39 | |
40 | /* Convert a PyLong to a time_t. */ |
41 | PyAPI_FUNC(time_t) _PyLong_AsTime_t( |
42 | PyObject *obj); |
43 | |
44 | /* Convert a number of seconds, int or float, to time_t. */ |
45 | PyAPI_FUNC(int) _PyTime_ObjectToTime_t( |
46 | PyObject *obj, |
47 | time_t *sec, |
48 | _PyTime_round_t); |
49 | |
50 | /* Convert a number of seconds, int or float, to a timeval structure. |
51 | usec is in the range [0; 999999] and rounded towards zero. |
52 | For example, -1.2 is converted to (-2, 800000). */ |
53 | PyAPI_FUNC(int) _PyTime_ObjectToTimeval( |
54 | PyObject *obj, |
55 | time_t *sec, |
56 | long *usec, |
57 | _PyTime_round_t); |
58 | |
59 | /* Convert a number of seconds, int or float, to a timespec structure. |
60 | nsec is in the range [0; 999999999] and rounded towards zero. |
61 | For example, -1.2 is converted to (-2, 800000000). */ |
62 | PyAPI_FUNC(int) _PyTime_ObjectToTimespec( |
63 | PyObject *obj, |
64 | time_t *sec, |
65 | long *nsec, |
66 | _PyTime_round_t); |
67 | |
68 | |
69 | /* Create a timestamp from a number of seconds. */ |
70 | PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds); |
71 | |
72 | /* Macro to create a timestamp from a number of seconds, no integer overflow. |
73 | Only use the macro for small values, prefer _PyTime_FromSeconds(). */ |
74 | #define _PYTIME_FROMSECONDS(seconds) \ |
75 | ((_PyTime_t)(seconds) * (1000 * 1000 * 1000)) |
76 | |
77 | /* Create a timestamp from a number of nanoseconds. */ |
78 | PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(PY_LONG_LONG ns); |
79 | |
80 | /* Convert a number of seconds (Python float or int) to a timetamp. |
81 | Raise an exception and return -1 on error, return 0 on success. */ |
82 | PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t, |
83 | PyObject *obj, |
84 | _PyTime_round_t round); |
85 | |
86 | /* Convert a number of milliseconds (Python float or int, 10^-3) to a timetamp. |
87 | Raise an exception and return -1 on error, return 0 on success. */ |
88 | PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t, |
89 | PyObject *obj, |
90 | _PyTime_round_t round); |
91 | |
92 | /* Convert a timestamp to a number of seconds as a C double. */ |
93 | PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t); |
94 | |
95 | /* Convert timestamp to a number of milliseconds (10^-3 seconds). */ |
96 | PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t, |
97 | _PyTime_round_t round); |
98 | |
99 | /* Convert timestamp to a number of microseconds (10^-6 seconds). */ |
100 | PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t, |
101 | _PyTime_round_t round); |
102 | |
103 | /* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int |
104 | object. */ |
105 | PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t); |
106 | |
107 | /* Convert a timestamp to a timeval structure (microsecond resolution). |
108 | tv_usec is always positive. |
109 | Raise an exception and return -1 if the conversion overflowed, |
110 | return 0 on success. */ |
111 | PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t, |
112 | struct timeval *tv, |
113 | _PyTime_round_t round); |
114 | |
115 | /* Similar to _PyTime_AsTimeval(), but don't raise an exception on error. */ |
116 | PyAPI_FUNC(int) _PyTime_AsTimeval_noraise(_PyTime_t t, |
117 | struct timeval *tv, |
118 | _PyTime_round_t round); |
119 | |
120 | /* Convert a timestamp to a number of seconds (secs) and microseconds (us). |
121 | us is always positive. This function is similar to _PyTime_AsTimeval() |
122 | except that secs is always a time_t type, whereas the timeval structure |
123 | uses a C long for tv_sec on Windows. |
124 | Raise an exception and return -1 if the conversion overflowed, |
125 | return 0 on success. */ |
126 | PyAPI_FUNC(int) _PyTime_AsTimevalTime_t( |
127 | _PyTime_t t, |
128 | time_t *secs, |
129 | int *us, |
130 | _PyTime_round_t round); |
131 | |
132 | #if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE) |
133 | /* Convert a timestamp to a timespec structure (nanosecond resolution). |
134 | tv_nsec is always positive. |
135 | Raise an exception and return -1 on error, return 0 on success. */ |
136 | PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts); |
137 | #endif |
138 | |
139 | /* Get the current time from the system clock. |
140 | |
141 | The function cannot fail. _PyTime_Init() ensures that the system clock |
142 | works. */ |
143 | PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void); |
144 | |
145 | /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
146 | The clock is not affected by system clock updates. The reference point of |
147 | the returned value is undefined, so that only the difference between the |
148 | results of consecutive calls is valid. |
149 | |
150 | The function cannot fail. _PyTime_Init() ensures that a monotonic clock |
151 | is available and works. */ |
152 | PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void); |
153 | |
154 | |
155 | /* Structure used by time.get_clock_info() */ |
156 | typedef struct { |
157 | const char *implementation; |
158 | int monotonic; |
159 | int adjustable; |
160 | double resolution; |
161 | } _Py_clock_info_t; |
162 | |
163 | /* Get the current time from the system clock. |
164 | * Fill clock information if info is not NULL. |
165 | * Raise an exception and return -1 on error, return 0 on success. |
166 | */ |
167 | PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo( |
168 | _PyTime_t *t, |
169 | _Py_clock_info_t *info); |
170 | |
171 | /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards. |
172 | The clock is not affected by system clock updates. The reference point of |
173 | the returned value is undefined, so that only the difference between the |
174 | results of consecutive calls is valid. |
175 | |
176 | Fill info (if set) with information of the function used to get the time. |
177 | |
178 | Return 0 on success, raise an exception and return -1 on error. */ |
179 | PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo( |
180 | _PyTime_t *t, |
181 | _Py_clock_info_t *info); |
182 | |
183 | |
184 | /* Initialize time. |
185 | Return 0 on success, raise an exception and return -1 on error. */ |
186 | PyAPI_FUNC(int) _PyTime_Init(void); |
187 | |
188 | #ifdef __cplusplus |
189 | } |
190 | #endif |
191 | |
192 | #endif /* Py_PYTIME_H */ |
193 | #endif /* Py_LIMITED_API */ |
194 | |