1
- // The _PyTime_t API is written to use timestamp and timeout values stored in
2
- // various formats and to read clocks.
3
- //
4
- // The _PyTime_t type is an integer to support directly common arithmetic
5
- // operations like t1 + t2.
6
- //
7
- // The _PyTime_t API supports a resolution of 1 nanosecond. The _PyTime_t type
8
- // is signed to support negative timestamps. The supported range is around
9
- // [-292.3 years; +292.3 years]. Using the Unix epoch (January 1st, 1970), the
10
- // supported date range is around [1677-09-21; 2262-04-11].
11
- //
12
- // Formats:
13
- //
14
- // * seconds
15
- // * seconds as a floating pointer number (C double)
16
- // * milliseconds (10^-3 seconds)
17
- // * microseconds (10^-6 seconds)
18
- // * 100 nanoseconds (10^-7 seconds)
19
- // * nanoseconds (10^-9 seconds)
20
- // * timeval structure, 1 microsecond resolution (10^-6 seconds)
21
- // * timespec structure, 1 nanosecond resolution (10^-9 seconds)
22
- //
23
- // Integer overflows are detected and raise OverflowError. Conversion to a
24
- // resolution worse than 1 nanosecond is rounded correctly with the requested
25
- // rounding mode. There are 4 rounding modes: floor (towards -inf), ceiling
26
- // (towards +inf), half even and up (away from zero).
27
- //
28
- // Some functions clamp the result in the range [_PyTime_MIN; _PyTime_MAX], so
29
- // the caller doesn't have to handle errors and doesn't need to hold the GIL.
30
- // For example, _PyTime_Add(t1, t2) computes t1+t2 and clamp the result on
31
- // overflow.
32
- //
33
- // Clocks:
34
- //
35
- // * System clock
36
- // * Monotonic clock
37
- // * Performance counter
38
- //
39
- // Operations like (t * k / q) with integers are implemented in a way to reduce
40
- // the risk of integer overflow. Such operation is used to convert a clock
41
- // value expressed in ticks with a frequency to _PyTime_t, like
42
- // QueryPerformanceCounter() with QueryPerformanceFrequency().
1
+ // Internal PyTime_t C API: see Doc/c-api/time.rst for the documentation.
43
2
44
3
#ifndef Py_INTERNAL_TIME_H
45
4
#define Py_INTERNAL_TIME_H
@@ -66,14 +25,7 @@ struct _time_runtime_state {
66
25
struct timeval ;
67
26
#endif
68
27
69
- // _PyTime_t: Python timestamp with subsecond precision. It can be used to
70
- // store a duration, and so indirectly a date (related to another date, like
71
- // UNIX epoch).
72
- typedef int64_t _PyTime_t ;
73
- // _PyTime_MIN nanoseconds is around -292.3 years
74
- #define _PyTime_MIN INT64_MIN
75
- // _PyTime_MAX nanoseconds is around +292.3 years
76
- #define _PyTime_MAX INT64_MAX
28
+ typedef PyTime_t _PyTime_t ;
77
29
#define _SIZEOF_PYTIME_T 8
78
30
79
31
typedef enum {
@@ -157,7 +109,7 @@ PyAPI_FUNC(_PyTime_t) _PyTime_FromSecondsDouble(double seconds, _PyTime_round_t
157
109
PyAPI_FUNC (_PyTime_t ) _PyTime_FromNanoseconds (_PyTime_t ns );
158
110
159
111
// Create a timestamp from a number of microseconds.
160
- // Clamp to [_PyTime_MIN; _PyTime_MAX ] on overflow.
112
+ // Clamp to [PyTime_MIN; PyTime_MAX ] on overflow.
161
113
extern _PyTime_t _PyTime_FromMicrosecondsClamp (_PyTime_t us );
162
114
163
115
// Create a timestamp from nanoseconds (Python int).
@@ -179,10 +131,6 @@ PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t,
179
131
PyObject * obj ,
180
132
_PyTime_round_t round );
181
133
182
- // Convert a timestamp to a number of seconds as a C double.
183
- // Export for '_socket' shared extension.
184
- PyAPI_FUNC (double ) _PyTime_AsSecondsDouble (_PyTime_t t );
185
-
186
134
// Convert timestamp to a number of milliseconds (10^-3 seconds).
187
135
// Export for '_ssl' shared extension.
188
136
PyAPI_FUNC (_PyTime_t ) _PyTime_AsMilliseconds (_PyTime_t t ,
@@ -260,11 +208,11 @@ PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(_PyTime_t t, struct timespec *ts);
260
208
#endif
261
209
262
210
263
- // Compute t1 + t2. Clamp to [_PyTime_MIN; _PyTime_MAX ] on overflow.
211
+ // Compute t1 + t2. Clamp to [PyTime_MIN; PyTime_MAX ] on overflow.
264
212
extern _PyTime_t _PyTime_Add (_PyTime_t t1 , _PyTime_t t2 );
265
213
266
214
// Compute ticks * mul / div.
267
- // Clamp to [_PyTime_MIN; _PyTime_MAX ] on overflow.
215
+ // Clamp to [PyTime_MIN; PyTime_MAX ] on overflow.
268
216
// The caller must ensure that ((div - 1) * mul) cannot overflow.
269
217
extern _PyTime_t _PyTime_MulDiv (_PyTime_t ticks ,
270
218
_PyTime_t mul ,
@@ -278,36 +226,13 @@ typedef struct {
278
226
double resolution ;
279
227
} _Py_clock_info_t ;
280
228
281
- // Get the current time from the system clock.
282
- //
283
- // If the internal clock fails, silently ignore the error and return 0.
284
- // On integer overflow, silently ignore the overflow and clamp the clock to
285
- // [_PyTime_MIN; _PyTime_MAX].
286
- //
287
- // Use _PyTime_GetSystemClockWithInfo() to check for failure.
288
- // Export for '_random' shared extension.
289
- PyAPI_FUNC (_PyTime_t ) _PyTime_GetSystemClock (void );
290
-
291
229
// Get the current time from the system clock.
292
230
// On success, set *t and *info (if not NULL), and return 0.
293
231
// On error, raise an exception and return -1.
294
232
extern int _PyTime_GetSystemClockWithInfo (
295
233
_PyTime_t * t ,
296
234
_Py_clock_info_t * info );
297
235
298
- // Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
299
- // The clock is not affected by system clock updates. The reference point of
300
- // the returned value is undefined, so that only the difference between the
301
- // results of consecutive calls is valid.
302
- //
303
- // If the internal clock fails, silently ignore the error and return 0.
304
- // On integer overflow, silently ignore the overflow and clamp the clock to
305
- // [_PyTime_MIN; _PyTime_MAX].
306
- //
307
- // Use _PyTime_GetMonotonicClockWithInfo() to check for failure.
308
- // Export for '_random' shared extension.
309
- PyAPI_FUNC (_PyTime_t ) _PyTime_GetMonotonicClock (void );
310
-
311
236
// Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
312
237
// The clock is not affected by system clock updates. The reference point of
313
238
// the returned value is undefined, so that only the difference between the
@@ -332,17 +257,6 @@ PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm);
332
257
// Export for '_datetime' shared extension.
333
258
PyAPI_FUNC (int ) _PyTime_gmtime (time_t t , struct tm * tm );
334
259
335
- // Get the performance counter: clock with the highest available resolution to
336
- // measure a short duration.
337
- //
338
- // If the internal clock fails, silently ignore the error and return 0.
339
- // On integer overflow, silently ignore the overflow and clamp the clock to
340
- // [_PyTime_MIN; _PyTime_MAX].
341
- //
342
- // Use _PyTime_GetPerfCounterWithInfo() to check for failure.
343
- // Export for '_lsprof' shared extension.
344
- PyAPI_FUNC (_PyTime_t ) _PyTime_GetPerfCounter (void );
345
-
346
260
// Get the performance counter: clock with the highest available resolution to
347
261
// measure a short duration.
348
262
//
@@ -355,12 +269,12 @@ extern int _PyTime_GetPerfCounterWithInfo(
355
269
356
270
357
271
// Create a deadline.
358
- // Pseudo code: _PyTime_GetMonotonicClock () + timeout.
272
+ // Pseudo code: PyTime_GetMonotonicClock () + timeout.
359
273
// Export for '_ssl' shared extension.
360
274
PyAPI_FUNC (_PyTime_t ) _PyDeadline_Init (_PyTime_t timeout );
361
275
362
276
// Get remaining time from a deadline.
363
- // Pseudo code: deadline - _PyTime_GetMonotonicClock ().
277
+ // Pseudo code: deadline - PyTime_GetMonotonicClock ().
364
278
// Export for '_ssl' shared extension.
365
279
PyAPI_FUNC (_PyTime_t ) _PyDeadline_Get (_PyTime_t deadline );
366
280
0 commit comments