Debian Codegraph @

Include/internal/pycore_time.h

raw
1 // Internal PyTime_t C API: see Doc/c-api/time.rst for the documentation.
2 //
3 // The PyTime_t type is an integer to support directly common arithmetic
4 // operations such as t1 + t2.
5 //
6 // Time formats:
7 //
8 // * Seconds.
9 // * Seconds as a floating-point number (C double).
10 // * Milliseconds (10^-3 seconds).
11 // * Microseconds (10^-6 seconds).
12 // * 100 nanoseconds (10^-7 seconds), used on Windows.
13 // * Nanoseconds (10^-9 seconds).
14 // * timeval structure, 1 microsecond (10^-6 seconds).
15 // * timespec structure, 1 nanosecond (10^-9 seconds).
16 //
17 // Note that PyTime_t is now specified as int64_t, in nanoseconds.
18 // (If we need to change this, we'll need new public API with new names.)
19 // Previously, PyTime_t was configurable (in theory); some comments and code
20 // might still allude to that.
21 //
22 // Integer overflows are detected and raise OverflowError. Conversion to a
23 // resolution larger than 1 nanosecond is rounded correctly with the requested
24 // rounding mode. Available rounding modes:
25 //
26 // * Round towards minus infinity (-inf). For example, used to read a clock.
27 // * Round towards infinity (+inf). For example, used for timeout to wait "at
28 // least" N seconds.
29 // * Round to nearest with ties going to nearest even integer. For example, used
30 // to round from a Python float.
31 // * Round away from zero. For example, used for timeout.
32 //
33 // Some functions clamp the result in the range [PyTime_MIN; PyTime_MAX]. The
34 // caller doesn't have to handle errors and so doesn't need to hold the GIL to
35 // handle exceptions. For example, _PyTime_Add(t1, t2) computes t1+t2 and
36 // clamps the result on overflow.
37 //
38 // Clocks:
39 //
40 // * System clock
41 // * Monotonic clock
42 // * Performance counter
43 //
44 // Internally, operations like (t * k / q) with integers are implemented in a
45 // way to reduce the risk of integer overflow. Such operation is used to convert a
46 // clock value expressed in ticks with a frequency to PyTime_t, like
47 // QueryPerformanceCounter() with QueryPerformanceFrequency() on Windows.
48
49
50 #ifndef Py_INTERNAL_TIME_H
51 #define Py_INTERNAL_TIME_H
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55
56 #ifndef Py_BUILD_CORE
57 # error "this header requires Py_BUILD_CORE define"
58 #endif
59
60 #include "pycore_runtime_structs.h" // _PyTimeFraction
61
62 #ifdef __clang__
63 struct timeval;
64 #endif
65
66 #define _SIZEOF_PYTIME_T 8
67
68 typedef enum {
69 // Round towards minus infinity (-inf).
70 // For example, used to read a clock.
71 _PyTime_ROUND_FLOOR=0,
72
73 // Round towards infinity (+inf).
74 // For example, used for timeout to wait "at least" N seconds.
75 _PyTime_ROUND_CEILING=1,
76
77 // Round to nearest with ties going to nearest even integer.
78 // For example, used to round from a Python float.
79 _PyTime_ROUND_HALF_EVEN=2,
80
81 // Round away from zero
82 // For example, used for timeout. _PyTime_ROUND_CEILING rounds
83 // -1e-9 to 0 milliseconds which causes bpo-31786 issue.
84 // _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps
85 // the timeout sign as expected. select.poll(timeout) must block
86 // for negative values.
87 _PyTime_ROUND_UP=3,
88
89 // _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be
90 // used for timeouts.
91 _PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP
92 } _PyTime_round_t;
93
94
95 // Convert a time_t to a PyLong.
96 // Export for '_testinternalcapi' shared extension
97 PyAPI_FUNC(PyObject*) _PyLong_FromTime_t(time_t sec);
98
99 // Convert a PyLong to a time_t.
100 // Export for '_datetime' shared extension
101 PyAPI_FUNC(time_t) _PyLong_AsTime_t(PyObject *obj);
102
103 // Convert a number of seconds, int or float, to time_t.
104 // Export for '_datetime' shared extension.
105 PyAPI_FUNC(int) _PyTime_ObjectToTime_t(
106 PyObject *obj,
107 time_t *sec,
108 _PyTime_round_t);
109
110 // Convert a number of seconds, int or float, to a timeval structure.
111 // usec is in the range [0; 999999] and rounded towards zero.
112 // For example, -1.2 is converted to (-2, 800000).
113 // Export for '_datetime' shared extension.
114 PyAPI_FUNC(int) _PyTime_ObjectToTimeval(
115 PyObject *obj,
116 time_t *sec,
117 long *usec,
118 _PyTime_round_t);
119
120 // Convert a number of seconds, int or float, to a timespec structure.
121 // nsec is in the range [0; 999999999] and rounded towards zero.
122 // For example, -1.2 is converted to (-2, 800000000).
123 // Export for '_testinternalcapi' shared extension.
124 PyAPI_FUNC(int) _PyTime_ObjectToTimespec(
125 PyObject *obj,
126 time_t *sec,
127 long *nsec,
128 _PyTime_round_t);
129
130
131 // Create a timestamp from a number of seconds.
132 // Export for '_socket' shared extension.
133 PyAPI_FUNC(PyTime_t) _PyTime_FromSeconds(int seconds);
134
135 // Create a timestamp from a number of seconds in double.
136 extern int _PyTime_FromSecondsDouble(
137 double seconds,
138 _PyTime_round_t round,
139 PyTime_t *result);
140
141 // Macro to create a timestamp from a number of seconds, no integer overflow.
142 // Only use the macro for small values, prefer _PyTime_FromSeconds().
143 #define _PYTIME_FROMSECONDS(seconds) \
144 ((PyTime_t)(seconds) * (1000 * 1000 * 1000))
145
146 // Create a timestamp from a number of microseconds.
147 // Clamp to [PyTime_MIN; PyTime_MAX] on overflow.
148 extern PyTime_t _PyTime_FromMicrosecondsClamp(PyTime_t us);
149
150 // Create a timestamp from a Python int object (number of nanoseconds).
151 // Export for '_lsprof' shared extension.
152 PyAPI_FUNC(int) _PyTime_FromLong(PyTime_t *t,
153 PyObject *obj);
154
155 // Convert a number of seconds (Python float or int) to a timestamp.
156 // Raise an exception and return -1 on error, return 0 on success.
157 // Export for '_socket' shared extension.
158 PyAPI_FUNC(int) _PyTime_FromSecondsObject(PyTime_t *t,
159 PyObject *obj,
160 _PyTime_round_t round);
161
162 // Convert a number of milliseconds (Python float or int, 10^-3) to a timestamp.
163 // Raise an exception and return -1 on error, return 0 on success.
164 // Export for 'select' shared extension.
165 PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(PyTime_t *t,
166 PyObject *obj,
167 _PyTime_round_t round);
168
169 // Convert timestamp to a number of milliseconds (10^-3 seconds).
170 // Export for '_ssl' shared extension.
171 PyAPI_FUNC(PyTime_t) _PyTime_AsMilliseconds(PyTime_t t,
172 _PyTime_round_t round);
173
174 // Convert timestamp to a number of microseconds (10^-6 seconds).
175 // Export for '_queue' shared extension.
176 PyAPI_FUNC(PyTime_t) _PyTime_AsMicroseconds(PyTime_t t,
177 _PyTime_round_t round);
178
179 #ifdef MS_WINDOWS
180 // Convert timestamp to a number of 100 nanoseconds (10^-7 seconds).
181 extern PyTime_t _PyTime_As100Nanoseconds(PyTime_t t,
182 _PyTime_round_t round);
183 #endif
184
185 // Convert a timestamp (number of nanoseconds) as a Python int object.
186 // Export for '_testinternalcapi' shared extension.
187 PyAPI_FUNC(PyObject*) _PyTime_AsLong(PyTime_t t);
188
189 #ifndef MS_WINDOWS
190 // Create a timestamp from a timeval structure.
191 // Raise an exception and return -1 on overflow, return 0 on success.
192 extern int _PyTime_FromTimeval(PyTime_t *tp, struct timeval *tv);
193 #endif
194
195 // Convert a timestamp to a timeval structure (microsecond resolution).
196 // tv_usec is always positive.
197 // Raise an exception and return -1 if the conversion overflowed,
198 // return 0 on success.
199 // Export for 'select' shared extension.
200 PyAPI_FUNC(int) _PyTime_AsTimeval(PyTime_t t,
201 struct timeval *tv,
202 _PyTime_round_t round);
203
204 // Similar to _PyTime_AsTimeval() but don't raise an exception on overflow.
205 // On overflow, clamp tv_sec to PyTime_t min/max.
206 // Export for 'select' shared extension.
207 PyAPI_FUNC(void) _PyTime_AsTimeval_clamp(PyTime_t t,
208 struct timeval *tv,
209 _PyTime_round_t round);
210
211 // Convert a timestamp to a number of seconds (secs) and microseconds (us).
212 // us is always positive. This function is similar to _PyTime_AsTimeval()
213 // except that secs is always a time_t type, whereas the timeval structure
214 // uses a C long for tv_sec on Windows.
215 // Raise an exception and return -1 if the conversion overflowed,
216 // return 0 on success.
217 // Export for '_datetime' shared extension.
218 PyAPI_FUNC(int) _PyTime_AsTimevalTime_t(
219 PyTime_t t,
220 time_t *secs,
221 int *us,
222 _PyTime_round_t round);
223
224 #if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE)
225 // Create a timestamp from a timespec structure.
226 // Raise an exception and return -1 on overflow, return 0 on success.
227 extern int _PyTime_FromTimespec(PyTime_t *tp, const struct timespec *ts);
228
229 // Convert a timestamp to a timespec structure (nanosecond resolution).
230 // tv_nsec is always positive.
231 // Raise an exception and return -1 on error, return 0 on success.
232 // Export for '_testinternalcapi' shared extension.
233 PyAPI_FUNC(int) _PyTime_AsTimespec(PyTime_t t, struct timespec *ts);
234
235 // Similar to _PyTime_AsTimespec() but don't raise an exception on overflow.
236 // On overflow, clamp tv_sec to PyTime_t min/max.
237 // Export for '_testinternalcapi' shared extension.
238 PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(PyTime_t t, struct timespec *ts);
239 #endif
240
241
242 // Compute t1 + t2. Clamp to [PyTime_MIN; PyTime_MAX] on overflow.
243 extern PyTime_t _PyTime_Add(PyTime_t t1, PyTime_t t2);
244
245 // Structure used by time.get_clock_info()
246 typedef struct {
247 const char *implementation;
248 int monotonic;
249 int adjustable;
250 double resolution;
251 } _Py_clock_info_t;
252
253 // Get the current time from the system clock.
254 // On success, set *t and *info (if not NULL), and return 0.
255 // On error, raise an exception and return -1.
256 extern int _PyTime_TimeWithInfo(
257 PyTime_t *t,
258 _Py_clock_info_t *info);
259
260 // Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
261 // The clock is not affected by system clock updates. The reference point of
262 // the returned value is undefined, so that only the difference between the
263 // results of consecutive calls is valid.
264 //
265 // Fill info (if set) with information of the function used to get the time.
266 //
267 // Return 0 on success, raise an exception and return -1 on error.
268 // Export for '_testsinglephase' shared extension.
269 PyAPI_FUNC(int) _PyTime_MonotonicWithInfo(
270 PyTime_t *t,
271 _Py_clock_info_t *info);
272
273
274 // Converts a timestamp to the Gregorian time, using the local time zone.
275 // Return 0 on success, raise an exception and return -1 on error.
276 // Export for '_datetime' shared extension.
277 PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm);
278
279 // Converts a timestamp to the Gregorian time, assuming UTC.
280 // Return 0 on success, raise an exception and return -1 on error.
281 // Export for '_datetime' shared extension.
282 PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm);
283
284
285 // Get the performance counter: clock with the highest available resolution to
286 // measure a short duration.
287 //
288 // Fill info (if set) with information of the function used to get the time.
289 //
290 // Return 0 on success, raise an exception and return -1 on error.
291 extern int _PyTime_PerfCounterWithInfo(
292 PyTime_t *t,
293 _Py_clock_info_t *info);
294
295
296 // --- _PyDeadline -----------------------------------------------------------
297
298 // Create a deadline.
299 // Pseudo code: return PyTime_MonotonicRaw() + timeout
300 // Export for '_ssl' shared extension.
301 PyAPI_FUNC(PyTime_t) _PyDeadline_Init(PyTime_t timeout);
302
303 // Get remaining time from a deadline.
304 // Pseudo code: return deadline - PyTime_MonotonicRaw()
305 // Export for '_ssl' shared extension.
306 PyAPI_FUNC(PyTime_t) _PyDeadline_Get(PyTime_t deadline);
307
308
309 // --- _PyTimeFraction -------------------------------------------------------
310
311 // Set a fraction.
312 // Return 0 on success.
313 // Return -1 if the fraction is invalid.
314 extern int _PyTimeFraction_Set(
315 _PyTimeFraction *frac,
316 PyTime_t numer,
317 PyTime_t denom);
318
319 // Compute ticks * frac.numer / frac.denom.
320 // Clamp to [PyTime_MIN; PyTime_MAX] on overflow.
321 extern PyTime_t _PyTimeFraction_Mul(
322 PyTime_t ticks,
323 const _PyTimeFraction *frac);
324
325 // Compute a clock resolution: frac.numer / frac.denom / 1e9.
326 extern double _PyTimeFraction_Resolution(
327 const _PyTimeFraction *frac);
328
329 extern PyStatus _PyTime_Init(struct _Py_time_runtime_state *state);
330
331 #ifdef __cplusplus
332 }
333 #endif
334 #endif // !Py_INTERNAL_TIME_H