Skip to content

gh-110850: Add PyTime_t C API #112135

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.

Sign up for GitHub

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

Closed
vstinner wants to merge 3 commits into from
Closed

gh-110850: Add PyTime_t C API #112135

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6c40241
gh-110850: Add PyTime_t C API
vstinner Nov 15, 2023
d8cf97d
Address Sam's review: update doc
vstinner Dec 14, 2023
c6f5be9
Avoid reference to epoch_
vstinner Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Address Sam's review: update doc
  • Loading branch information
@vstinner
vstinner committed Jan 18, 2024
commit d8cf97d02df07452f1b3bd41ae060091f9c88650
55 changes: 21 additions & 34 deletions Doc/c-api/time.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,24 +8,24 @@ PyTime C API
PyTime API
----------

The PyTime_t API is written to use timestamp and timeout values stored in
various formats and to read clocks with a resolution of one nanosecond.

The :c:type:`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) as reference, the supported date range is around
[1677-09-21; 2262-04-11].
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

Timestamp type with subsecond precision: 64-bit signed integer.
A timestamp or duration in nanoseconds represented as a 64-bit signed
integer.
Comment on lines +20 to +21

@encukou encukou Feb 8, 2024

Copy link
Copy Markdown
Member

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.

@vstinner vstinner Feb 8, 2024

Copy link
Copy Markdown
Member Author

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 just PyTime_t one_ns = 1;. No "from nanoseconds" or "to nanoseconds" are needed. It makes the API simpler to use (so less error prone).


The reference point for timestamps depends on the clock used. For example,
:c:func:`PyTime_Time` returns timestamps relative to the UNIX epoch.

This type can be used to store a duration. Indirectly, it can be used to
store a date relative to a reference date, such as 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
Expand Down Expand Up @@ -56,48 +56,35 @@ Functions

.. c:function:: PyTime_t PyTime_Monotonic(void)

Get the monotonic clock: clock that cannot go backwards.

The monotonic clock is not affected by system clock updates. The reference
point of the returned value is undefined, so that only the difference
between the results of consecutive calls is valid.
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.
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.

See also the :func:`time.monotonic` function.


.. c:function:: PyTime_t PyTime_PerfCounter(void)

Get the performance counter: clock with the highest available resolution to
measure a short duration.
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.

The performance counter does include time elapsed during sleep and is
system-wide. The reference point of the returned value is undefined, so that
only the difference between the results of two calls is valid.

If reading the clock fails, silently ignore the error and return 0.
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.

See also the :func:`time.perf_counter` function.


.. c:function:: PyTime_t PyTime_Time(void)

Get the system clock.

The system clock can be changed automatically (e.g. by a NTP daemon) or
manually by the system administrator. So it can also go backward. Use
:c:func:`PyTime_Monotonic` to use a monotonic clock.
Return the time in nanoseconds since the epoch_. 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.

See also the :func:`time.time` function.