-
-
Notifications
You must be signed in to change notification settings - Fork 30k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
gh-110850: Add PyTime_t C API #112135
gh-110850: Add PyTime_t C API #112135
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,90 @@ | ||
.. highlight:: c | ||
|
||
PyTime C API | ||
============ | ||
|
||
.. versionadded:: 3.13 | ||
|
||
PyTime API | ||
---------- | ||
|
||
The PyTime API provides access to system clocks and time conversion functions. | ||
It is similar to the Python :mod:`time` module. | ||
|
||
|
||
Types | ||
----- | ||
|
||
.. c:type:: PyTime_t | ||
|
||
A timestamp or duration in nanoseconds represented as a 64-bit signed | ||
integer. | ||
|
||
The reference point for timestamps depends on the clock used. For example, | ||
:c:func:`PyTime_Time` returns timestamps relative to the UNIX epoch. | ||
|
||
The supported range is around [-292.3 years; +292.3 years]. Using the Unix | ||
epoch (January 1st, 1970) as reference, the supported date range is around | ||
[1677-09-21; 2262-04-11]. | ||
|
||
|
||
Constants | ||
--------- | ||
|
||
.. c:var:: PyTime_t PyTime_MIN | ||
|
||
Minimum value of the :c:type:`PyTime_t` type. | ||
|
||
:c:var:`PyTime_MIN` nanoseconds is around -292.3 years. | ||
|
||
.. c:var:: PyTime_t PyTime_MAX | ||
|
||
Maximum value of the :c:type:`PyTime_t` type. | ||
|
||
:c:var:`PyTime_MAX` nanoseconds is around +292.3 years. | ||
|
||
|
||
Functions | ||
--------- | ||
|
||
.. c:function:: double PyTime_AsSecondsDouble(PyTime_t t) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is the rounding mode? Do we need an argument for specifying it? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't know how to implement a rounding method on this function. I don't know how numbers are rounded. The function starts to lose precision at
In short, the function is implemented as: def PyTime_AsSecondsDouble(t): return float(t) / 1e9 |
||
|
||
Convert a timestamp to a number of seconds as a C :c:expr:`double`. | ||
|
||
The function cannot fail. | ||
|
||
|
||
.. c:function:: PyTime_t PyTime_Monotonic(void) | ||
|
||
Return the value in nanoseconds of a monotonic clock, i.e. a clock | ||
that cannot go backwards. Similar to :func:`time.monotonic_ns`; see | ||
:func:`time.monotonic` for details. | ||
|
||
If reading the clock fails, silently ignore the error and return ``0``. | ||
|
||
On integer overflow, silently ignore the overflow and clamp the clock to | ||
the ``[PyTime_MIN; PyTime_MAX]`` range. | ||
|
||
|
||
.. c:function:: PyTime_t PyTime_PerfCounter(void) | ||
|
||
Return the value in nanoseconds of a performance counter, i.e. a | ||
clock with the highest available resolution to measure a short duration. | ||
Similar to :func:`time.perf_counter_ns`; see :func:`time.perf_counter` for | ||
details. | ||
|
||
If reading the clock fails, silently ignore the error and return ``0``. | ||
|
||
On integer overflow, silently ignore the overflow and clamp the clock to | ||
the ``[PyTime_MIN; PyTime_MAX]`` range. | ||
|
||
|
||
.. c:function:: PyTime_t PyTime_Time(void) | ||
|
||
Return the time in nanoseconds since January 1, 1970, 00:00:00 (UTC). | ||
Similar to :func:`time.time_ns`; see :func:`time.time` for details. | ||
|
||
If reading the clock fails, silently ignore the error and return ``0``. | ||
|
||
On integer overflow, silently ignore the overflow and clamp the clock to | ||
the ``[PyTime_MIN; PyTime_MAX]`` range. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
// PyTime_t C API: see Doc/c-api/time.rst for the documentation. | ||
|
||
#ifndef Py_LIMITED_API | ||
#ifndef Py_PYTIME_H | ||
#define Py_PYTIME_H | ||
#ifdef __cplusplus | ||
extern "C" { | ||
#endif | ||
|
||
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(PyTime_t) PyTime_Monotonic(void); | ||
PyAPI_FUNC(PyTime_t) PyTime_PerfCounter(void); | ||
PyAPI_FUNC(PyTime_t) PyTime_Time(void); | ||
|
||
#ifdef __cplusplus | ||
} | ||
#endif | ||
#endif /* Py_PYTIME_H */ | ||
#endif /* Py_LIMITED_API */ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
At the C-API WG issue, you say that the units are supposed to be an implementation detail.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, now I'm confused. I don't recall the exact history of this PR that I wrote 3 months ago.
When I wrote that API 10 years ago, I tried hard to not expose the "unit" (1 nanosecond). In practice, it was always 1 nanosecond, even if on Windows, clocks only have a resolution of 100 nanoseconds in the best case.
Maybe it's time to stick to nanoseconds. On Linux,
timespec
,clock_gettime()
,nanosleep()
have a resolution of 1 nanosecond. I don't know any operating system API using a better resolution.So well, we should stick to 1 nanosecond to avoid any confusion. So creating a
PyTime_t
of 1 nanosecond is justPyTime_t one_ns = 1;
. No "from nanoseconds" or "to nanoseconds" are needed. It makes the API simpler to use (so less error prone).