gh-110850: Add PyTime_t C API

[encukou]

This builds on Victor's PR: #112135

Additionally:

• The API of the public functions now allows them to raise exceptions
• The units of PyTime_t are now an implementation detail; PyTime_AsNanoseconds() is provided to convert to nanoseconds. (Currently, it's a no-op and always succeeds; the API allows reporting errors like overflow in the future.)

• Issue: Please expose _PyTime_t, _PyTime_FromTimeval, and _PyTime_AsSecondsDouble as public APIs #110850

---

📚 Documentation preview 📚: https://cpython-previews--115215.org.readthedocs.build/

[vstinner]

Here is a first review.

I suggest to declare that PyTime_t is a number of nanoseconds and not add PyTime_AsNanoseconds().

There are some Sphinx warnings, like: c:identifier reference target not found: result in time.rst.

[vstinner]

We should either:

• Stick to 64-bit and nanoseconds.
• Design the API so that the type can become 128-bit integer and use better resolution than nanoseconds. In this case, I suggest to add 2 functions: PyTime_AsNanoseconds() and PyTime_FromNanoseconds().

[vstinner]

@encukou: Thanks for working on this PR!

[colesbury]

The fallible APIs and generalization of PyTime_t makes these APIs harder to use without, it seems to me, sufficient benefit:

• API users are likely to start relying on details, like the fact that PyTime_t is 64-bit time in nanoseconds. If we ever in the future wanted an API with a different precision or data type, we'd be better off introducing a new API than breaking users.
• The underlying functions shouldn't fail on modern operating systems. Is there any OS we support that doesn't have CLOCK_MONOTONIC?

I commented below, but I don't think we can set+clear exceptions in the internal versions. They're used in contexts that don't have active PyThreadStates.

[colesbury]

Oh, I see that fallible vs infallible API has already been extensively discussed in the C-API WG. The API doc should probably explicitly state that the functions require holding the GIL.

[vstinner]

@colesbury:

Oh, I see that fallible vs infallible API has already been extensively discussed in the C-API WG. The API doc should probably explicitly state that the functions require holding the GIL.

That's the public C API. If Python needs variants which cannot fail, we can still have some in our internal C API.

Right, the rationale for reporting errors was discussed in length in the issue: capi-workgroup/decisions#8.

[vstinner]

LGTM.

For a few seconds (or many nanoseconds ;-)), I tried to imagine how the API and the implementation would look without PyTime_t type: using int64_t type. It's tempting to make the API as small as possible. IMO the API is better with a decided type, even if it's well documented that it's exactly int64_t. In terms of typing, it's better, it makes the code easier to follow, to review, etc.

[encukou]

Yes: unlike int64_t, PyTime_t is always in nanoseconds.

[encukou]

C API WG is in favour, so I'll merge.

[encukou]

Thank you for the code & reviews!

[vstinner]

@encukou and me added a bare minimum public C API to read time with a PyTime_t type (64-bit signed number: nanoseconds): change commit 879f454.

typedef int64_t PyTime_t;
#define PyTime_MIN INT64_MIN
#define PyTime_MAX INT64_MAX

PyAPI_FUNC(double) PyTime_AsSecondsDouble(PyTime_t t);
PyAPI_FUNC(int) PyTime_Monotonic(PyTime_t *result);
PyAPI_FUNC(int) PyTime_PerfCounter(PyTime_t *result);
PyAPI_FUNC(int) PyTime_Time(PyTime_t *result);

If someone wants more functions to be exposed, please open a separated issue.