To prepare Python to add support of monotonic clock in pytime.h, I propose to rewrite pytime.h to use a new _PyTimeSpec structure which has a resolution of 1 nanosecond on only work on integers.

Currently, pytime.h uses a _PyTime_timeval structure which has a solution of 1 microsecond and works internally on floating point numbers. Computing the difference between two timestamps may loose precision.

The tv_nsec field of _PyTimeSpec must be in the range [0; 999999999], even for negative numbers. For example, -1 ns is stored as (-1, 999999999). This property makes the code more complex, especially to round correctly.


The new API is based on the idea that all timestamps must be stored as _PyTimeSpec.

Convert a value into a _PyTimeSpec:

- _PyTimeSpec_from_double(): C double
- _PyTimeSpec_from_object(): Python int or float object
- you can also fill directly the tv_sec and tv_nsec fields

Convert a _PyTimeSpec timestamp into a value:

- _PyTimeSpec_to_time_t(): C time_t
- _PyTimeSpec_to_timeval(): C timeval (tv_sec, tv_usec), but ot directly the structure because the exact structure is different depending on the OS and OS version
- _PyTimeSpec_ms(): C long, number of milliseconds

Operations on _PyTimeSpec:

- _PyTimeSpec_add(): a+b
- _PyTimeSpec_sub(): a-b

I removed high-level functions like _PyTime_ObjectToTimeval(): you should now combine _PyTimeSpec_from_object() with _PyTimeSpec_to_timeval(). I did this to not multiply the number of functions, because I want to test all functions in unit tests and have a short API.


I tried to enhance detecton of overflow. I didn't review carefuly my patch yet. I'm not sure that all calls check for error and handle exceptions correctly. Only the following functions raise an exception on error:

- _PyTimeSpec_from_object()
- _PyTimeSpec_to_time_t()
- _PyTimeSpec_to_timeval()

Other functions sets the minimum/maximum value in case of underflow/overflow. So even if you don't check for errors, the behaviour on overflow should be acceptable.


The new _PyTimeSpec_Init() function checks that the system clock works, so _PyTimeSpec_get_time() and _PyTimeSpec_get_time_info() don't need to check for error. In fact, these functions call Py_FatalError() on error, but it should never happen. This idea was proposed in the issue #22043 to check if the monotonic clock is working. Maybe we can avoid checking the system clock in _PyTimeSpec_Init() and only check the monotonic clock. I hope that all platforms have a working system clock! The oppoosite would be a huge issue.


The patch removes function which are exposed in the stable ABI. Since the functions are private, name starting with ("_Py"), I consider that it's ok to remove them. The functions are replaced with new functions which a have a new name. I excluded pytime.h from the stable ABI. I don't know why private functions were part of the stable ABI :-/


The patch comes with unit tests for each function.


I didn't implement handling of overflow and underflow in _PyTimeSpec_add() and _PyTimeSpec_sub() yet. But I implemented detection for overflow for the simple case.


See also:

- Issue #22043: "Use a monotonic clock to compute timeouts".
- PEP 410: "Use decimal.Decimal type for timestamps" (rejected)