diff options
| author | Victor Stinner <vstinner@python.org> | 2021-09-30 11:23:03 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-09-30 11:23:03 +0200 |
| commit | b34dd58fee707b8044beaf878962a6fa12b304dc (patch) | |
| tree | f99bf86aa5ffacef6cf91338e03326e149a7e1b5 | |
| parent | 37b8294d6295ca12553fd7c98778be71d24f4b24 (diff) | |
| download | cpython-git-b34dd58fee707b8044beaf878962a6fa12b304dc.tar.gz | |
bpo-41710: Document _PyTime_t API in pytime.h (GH-28647)
| -rw-r--r-- | Include/cpython/pytime.h | 41 |
1 files changed, 41 insertions, 0 deletions
diff --git a/Include/cpython/pytime.h b/Include/cpython/pytime.h index db3adfab6a..5440720f1b 100644 --- a/Include/cpython/pytime.h +++ b/Include/cpython/pytime.h @@ -1,3 +1,44 @@ +// The _PyTime_t API is written to use timestamp and timeout values stored in +// various formats and to read clocks. +// +// The _PyTime_t type is an integer to support directly common arithmetic +// operations like t1 + t2. +// +// The _PyTime_t API supports a resolution of 1 nanosecond. The _PyTime_t type +// is signed to support negative timestamps. The supported range is around +// [-292.3 years; +292.3 years]. Using the Unix epoch (January 1st, 1970), the +// supported date range is around [1677-09-21; 2262-04-11]. +// +// Formats: +// +// * seconds +// * seconds as a floating pointer number (C double) +// * milliseconds (10^-3 seconds) +// * microseconds (10^-6 seconds) +// * 100 nanoseconds (10^-7 seconds) +// * nanoseconds (10^-9 seconds) +// * timeval structure, 1 microsecond resolution (10^-6 seconds) +// * timespec structure, 1 nanosecond resolution (10^-9 seconds) +// +// Integer overflows are detected and raise OverflowError. Conversion to a +// resolution worse than 1 nanosecond is rounded correctly with the requested +// rounding mode. There are 4 rounding modes: floor (towards -inf), ceiling +// (towards +inf), half even and up (away from zero). +// +// Some functions clamp the result in the range [_PyTime_MIN; _PyTime_MAX], so +// the caller doesn't have to handle errors and doesn't need to hold the GIL. +// +// Clocks: +// +// * System clock +// * Monotonic clock +// * Performance counter +// +// Operations like (t * k / q) with integers are implemented in a way to reduce +// the risk of integer overflow. Such operation is used to convert a clock +// value expressed in ticks with a frequency to _PyTime_t, like +// QueryPerformanceCounter() with QueryPerformanceFrequency(). + #ifndef Py_LIMITED_API #ifndef Py_PYTIME_H #define Py_PYTIME_H |