Skip to content

Latest commit

 

History

History
114 lines (71 loc) · 3.23 KB

time.rst

File metadata and controls

114 lines (71 loc) · 3.23 KB

PyTime C API

.. 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`.

Types

.. 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`.

Clock Functions

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 the :term:`GIL` held.

.. 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.

Raw Clock Functions

Similar to clock functions, but don't set an exception on error and don't require the caller to hold the GIL.

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, acquire the GIL 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 holding the GIL.
.. 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 holding the GIL.
.. 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 holding the GIL.

Conversion functions

.. 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.