Doc/c-api/time.rst
.. highlight:: c
.. _c-api-time:
.. versionadded:: 3.13
The clock C API provides access to system clocks.
It is similar to the Python :mod:time module.
For C API related to the :mod:datetime module, see :ref:datetimeobjects.
.. c:type:: PyTime_t
A timestamp or duration in nanoseconds, represented as a signed 64-bit 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]. The exact limits are exposed as constants:
.. c:var:: PyTime_t PyTime_MIN
Minimum value of :c:type:PyTime_t.
.. c:var:: PyTime_t PyTime_MAX
Maximum value of :c:type:PyTime_t.
The following functions take a pointer to a :c:expr:PyTime_t that they
set to the value of a particular clock.
Details of each clock are given in the documentation of the corresponding
Python function.
The functions return 0 on success, or -1 (with an exception set)
on failure.
On integer overflow, they set the :c:data:PyExc_OverflowError exception and
set *result to the value clamped to the [PyTime_MIN; PyTime_MAX]
range.
(On current systems, integer overflows are likely caused by misconfigured
system time.)
As any other C API (unless otherwise specified), the functions must be called
with an :term:attached thread state.
.. c:function:: int PyTime_Monotonic(PyTime_t *result)
Read the monotonic clock.
See :func:time.monotonic for important details on this clock.
.. c:function:: int PyTime_PerfCounter(PyTime_t *result)
Read the performance counter.
See :func:time.perf_counter for important details on this clock.
.. c:function:: int PyTime_Time(PyTime_t *result)
Read the “wall clock” time.
See :func:time.time for details important on this clock.
Similar to clock functions, but don't set an exception on error and don't
require the caller to have an :term:attached thread state.
On success, the functions return 0.
On failure, they set *result to 0 and return -1, without setting
an exception. To get the cause of the error, :term:attach <attached thread state> a :term:thread state,
and call the regular (non-Raw) function. Note that the regular function may succeed after
the Raw one failed.
.. c:function:: int PyTime_MonotonicRaw(PyTime_t *result)
Similar to :c:func:PyTime_Monotonic,
but don't set an exception on error and don't require an :term:attached thread state.
.. c:function:: int PyTime_PerfCounterRaw(PyTime_t *result)
Similar to :c:func:PyTime_PerfCounter,
but don't set an exception on error and don't require an :term:attached thread state.
.. c:function:: int PyTime_TimeRaw(PyTime_t *result)
Similar to :c:func:PyTime_Time,
but don't set an exception on error and don't require an :term:attached thread state.
.. c:function:: double PyTime_AsSecondsDouble(PyTime_t t)
Convert a timestamp to a number of seconds as a C :c:expr:double.
The function cannot fail, but note that :c:expr:double has limited
accuracy for large values.