1
- // The _PyTime_t API is written to use timestamp and timeout values stored in
2
- // various formats and to read clocks.
1
+ // Internal PyTime_t C API: see Doc/c-api/time.rst for the documentation.
3
2
//
4
- // The _PyTime_t type is an integer to support directly common arithmetic
5
- // operations like t1 + t2.
3
+ // The PyTime_t type is an integer to support directly common arithmetic
4
+ // operations such as t1 + t2.
6
5
//
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].
6
+ // Time formats:
11
7
//
12
- // Formats:
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).
13
16
//
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)
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.
22
21
//
23
22
// 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).
23
+ // resolution larger than 1 nanosecond is rounded correctly with the requested
24
+ // rounding mode. Available rounding modes:
27
25
//
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.
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.
32
37
//
33
38
// Clocks:
34
39
//
35
40
// * System clock
36
41
// * Monotonic clock
37
42
// * Performance counter
38
43
//
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().
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
+
43
49
44
50
#ifndef Py_INTERNAL_TIME_H
45
51
#define Py_INTERNAL_TIME_H
@@ -56,14 +62,7 @@ extern "C" {
56
62
struct timeval ;
57
63
#endif
58
64
59
- // _PyTime_t: Python timestamp with subsecond precision. It can be used to
60
- // store a duration, and so indirectly a date (related to another date, like
61
- // UNIX epoch).
62
- typedef int64_t _PyTime_t ;
63
- // _PyTime_MIN nanoseconds is around -292.3 years
64
- #define _PyTime_MIN INT64_MIN
65
- // _PyTime_MAX nanoseconds is around +292.3 years
66
- #define _PyTime_MAX INT64_MAX
65
+ typedef PyTime_t _PyTime_t ;
67
66
#define _SIZEOF_PYTIME_T 8
68
67
69
68
typedef enum {
@@ -147,7 +146,7 @@ PyAPI_FUNC(_PyTime_t) _PyTime_FromSecondsDouble(double seconds, _PyTime_round_t
147
146
PyAPI_FUNC (_PyTime_t ) _PyTime_FromNanoseconds (_PyTime_t ns );
148
147
149
148
// Create a timestamp from a number of microseconds.
150
- // Clamp to [_PyTime_MIN; _PyTime_MAX ] on overflow.
149
+ // Clamp to [PyTime_MIN; PyTime_MAX ] on overflow.
151
150
extern _PyTime_t _PyTime_FromMicrosecondsClamp (_PyTime_t us );
152
151
153
152
// Create a timestamp from nanoseconds (Python int).
@@ -169,10 +168,6 @@ PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t,
169
168
PyObject * obj ,
170
169
_PyTime_round_t round );
171
170
172
- // Convert a timestamp to a number of seconds as a C double.
173
- // Export for '_socket' shared extension.
174
- PyAPI_FUNC (double ) _PyTime_AsSecondsDouble (_PyTime_t t );
175
-
176
171
// Convert timestamp to a number of milliseconds (10^-3 seconds).
177
172
// Export for '_ssl' shared extension.
178
173
PyAPI_FUNC (_PyTime_t ) _PyTime_AsMilliseconds (_PyTime_t t ,
@@ -183,9 +178,6 @@ PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t,
183
178
PyAPI_FUNC (_PyTime_t ) _PyTime_AsMicroseconds (_PyTime_t t ,
184
179
_PyTime_round_t round );
185
180
186
- // Convert timestamp to a number of nanoseconds (10^-9 seconds).
187
- extern _PyTime_t _PyTime_AsNanoseconds (_PyTime_t t );
188
-
189
181
#ifdef MS_WINDOWS
190
182
// Convert timestamp to a number of 100 nanoseconds (10^-7 seconds).
191
183
extern _PyTime_t _PyTime_As100Nanoseconds (_PyTime_t t ,
@@ -250,7 +242,7 @@ PyAPI_FUNC(void) _PyTime_AsTimespec_clamp(_PyTime_t t, struct timespec *ts);
250
242
#endif
251
243
252
244
253
- // Compute t1 + t2. Clamp to [_PyTime_MIN; _PyTime_MAX ] on overflow.
245
+ // Compute t1 + t2. Clamp to [PyTime_MIN; PyTime_MAX ] on overflow.
254
246
extern _PyTime_t _PyTime_Add (_PyTime_t t1 , _PyTime_t t2 );
255
247
256
248
// Structure used by time.get_clock_info()
@@ -267,7 +259,8 @@ typedef struct {
267
259
// On integer overflow, silently ignore the overflow and clamp the clock to
268
260
// [_PyTime_MIN; _PyTime_MAX].
269
261
//
270
- // Use _PyTime_GetSystemClockWithInfo() to check for failure.
262
+ // Use _PyTime_GetSystemClockWithInfo or the public PyTime_Time() to check
263
+ // for failure.
271
264
// Export for '_random' shared extension.
272
265
PyAPI_FUNC (_PyTime_t ) _PyTime_GetSystemClock (void );
273
266
@@ -287,7 +280,8 @@ extern int _PyTime_GetSystemClockWithInfo(
287
280
// On integer overflow, silently ignore the overflow and clamp the clock to
288
281
// [_PyTime_MIN; _PyTime_MAX].
289
282
//
290
- // Use _PyTime_GetMonotonicClockWithInfo() to check for failure.
283
+ // Use _PyTime_GetMonotonicClockWithInfo or the public PyTime_Monotonic()
284
+ // to check for failure.
291
285
// Export for '_random' shared extension.
292
286
PyAPI_FUNC (_PyTime_t ) _PyTime_GetMonotonicClock (void );
293
287
@@ -322,10 +316,12 @@ PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm);
322
316
// On integer overflow, silently ignore the overflow and clamp the clock to
323
317
// [_PyTime_MIN; _PyTime_MAX].
324
318
//
325
- // Use _PyTime_GetPerfCounterWithInfo() to check for failure.
319
+ // Use _PyTime_GetPerfCounterWithInfo() or the public PyTime_PerfCounter
320
+ // to check for failure.
326
321
// Export for '_lsprof' shared extension.
327
322
PyAPI_FUNC (_PyTime_t ) _PyTime_GetPerfCounter (void );
328
323
324
+
329
325
// Get the performance counter: clock with the highest available resolution to
330
326
// measure a short duration.
331
327
//
@@ -336,6 +332,13 @@ extern int _PyTime_GetPerfCounterWithInfo(
336
332
_PyTime_t * t ,
337
333
_Py_clock_info_t * info );
338
334
335
+ // Alias for backward compatibility
336
+ #define _PyTime_MIN PyTime_MIN
337
+ #define _PyTime_MAX PyTime_MAX
338
+ #define _PyTime_AsSecondsDouble PyTime_AsSecondsDouble
339
+
340
+
341
+ // --- _PyDeadline -----------------------------------------------------------
339
342
340
343
// Create a deadline.
341
344
// Pseudo code: _PyTime_GetMonotonicClock() + timeout.
0 commit comments